Applications and Geodes: 6.5 Inter-Application Communication: Being a Server

Every time an application is launched, its Application object automatically registers as a server for the server list that shares its GeodeToken . The Application class has default handlers for all the notification messages IACP sends to the server objects.

If you wish, you can have another object act as a server. However, if you do this, you will have to do more of the work yourself. While the notification messages are defined for MetaClass , and thus can be handled by any class of object, MetaClass does not come with handlers for these messages; if the server is not subclassed from GenApplicationClass , you will have to write the handlers yourself. This is discussed below.

Registering and Unregistering a Server

IACPRegisterServer(), IACPUnregisterServer(), IACPGetServerNumber()

You will not generally need to register and unregister a server object explicitly. As noted above, when an application is launched, the application object is automatically registered as a server for the list with its GeodeToken ; when the application exits, the Application object is automatically unregistered from that list.

However, you may wish to explicitly register an object as a server. For example, you might want your application object to be a server on a list with a different GeodeToken ; or you might want to register a non-Application object as a server. In this case, you will need to explicitly register and unregister the object.

To register an object as a server, call IACPRegisterServer() . This routine is passed the following arguments:

The GeodeToken of the list for which you are registering as a server.
The optr of the object which is registering as a server. This object must be able to handle the MSG_META_IACP... messages appropriately (this is built into GenApplicationClass ).
A member of the IACPServerMode enumerated type. This type specifies how the client expects the server to behave. Currently, only two types are supported:

IACPSM_NOT_USER_INTERACTIBLE: This is equal to zero. It indicates that the server object will not interact directly with users.
IACPSM_USER_INTERACTIBLE: This is equal to two. It indicates that the server will be able to interact with the user like any normal application.

IACPRegisterServer() registers the object as a server for the appropriate list; it creates the server list if necessary.

To unregister an object as a server, call IACPUnregisterServer() . This routine is passed two arguments: the GeodeToken of the server list, and the optr of the server. The object will be removed immediately from the server list. Note, however, that the server list might have already dispatched some messages to the server being removed; these messages might be waiting on the server object's queue, and thus the server object might get some IACP messages even after it calls IACPUnregisterServer() . One way to deal with this is to have the server object send itself a message, via the queue, immediately after it calls IACPUnregisterServer() . When the object receives this message, it will know that it has no more IACP messages on its queue.

Every server object on a given server list has a unique server number . This server number will not change while the server is attached to the list. A server object can find out its server number by calling IACPGetServerNumber() . This routine takes two arguments: the IACPConnection and the optr to the server object. It returns the object's server number.

Non-Application Servers and Clients

MSG_META_IACP_PROCESS_MESSAGE, IACPProcessMessage(), MSG_META_IACP_NEW_CONNECTION, MSG_META_IACP_LOST_CONNECTION

Every server and client object must be able to handle certain messages. GenApplicationClass comes with handlers for these messages, so you need not write them yourself. However, if you will be using some other kind of object as the server, you must handle the messages yourself. You may also choose to have your application object subclass any of these messages; in that case, you should generally have your handler use @callsuper .

When a server or client sends an IACP message, the kernel passes the encapsulated message to each object on the other side of the link. It does this by sending the message MSG_META_IACP_PROCESS_MESSAGE to each object. This message comes with three arguments:

msgToSend: The EventHandle of the encapsulated message.
topt: The TravelOption for that message.
completionMsg: TheEventHandle of any message to be sent after msgToSend has been dispatched. (This field may be set to zero, indicating that there is no completion message.)

The recipient of MSG_META_IACP_PROCESS_MESSAGE should call IACPProcessMessage() . This routine is passed four arguments: the optr of the object calling the routine, and the three arguments passed with MSG_META_IACP_PROCESS_MESSAGE. IACPProcessMessage() dispatches both encapsulated messages properly.

Remember, if the client or server is subclassed from GenApplicationClass , all of this is done for you. You need only write a handler for the message if the client or server object is not from a subclass of GenApplicationClass .

Whenever a client registers on an IACP list, the kernel sends MSG_META_IACP_NEW_CONNECTION to all servers on that list. This message comes with three arguments:

appLaunchBlock: This is the handle of the AppLaunchBlock which the server passed to IACPConnect() .
justLaunched: This is a Boolean value. If the server's application has just been launched specifically to be a server, this will be true (i.e. non-zero).
IACPConnection: This is the token for the IACP connection.

When an object (either client or server) removes itself from an IACP connection, the kernel sends MSG_META_IACP_LOST_CONNECTION to all objects on the other side of the link. This message has two parameters:

connection: The token for the IACP list.
serverNum: If a server removed itself from the list (and this message is being sent to clients), this field will have the number of the server that removed itself. If a client removed itself from the list, this field will be zero.

Whenever a new client is attached to a server list, MSG_META_IACP_NEW_CONNECTION is sent to every server object. This message comes with three arguments:

appLaunchBlock: This is the handle of the application's launch block. The default GenApplicationClass handler examines the launch block to see if the application should open a document.
justLaunched: If the application was just launched specifically to be a server, this field will be true (i.e. non-zero).
connection: This is the token for the IACP connection.

When a client is removed from a server list, every server object is sent MSG_META_IACP_LOST_CONNECTION . Similarly, when a server is removed, every client object is sent MSG_META_IACP_LOST_CONNECTION . The message comes with two arguments:

IACPConnection: This is the token for the IACP connection.
serverNum: If a server left the list (and the message is being sent to clients), this argument will hold its serverNum . If a client left the list (and the message is being sent to servers), this argument will be set to zero.

GEOS SDK TechDocs |

6.4 Being a Client