Applications and Geodes: 6.3 Inter-Application Communication: Messages Across an IACP Link

6.2 GenApplicationClass Behavior | Next:

IACPSendMessage(), IACPSendMessageToServer()

Either a client or a server may send messages over an IACP link. Both clients and servers use the same technique. The message sender encapsulates a message, and passes the encapsulated message to IACPSendMessage() . IACPSendMessage() dispatches the message to every object on the other side of the link. For example, if a client passes a message to IACPSendMessage() , that message will be dispatched to every server object for the specified list.

IACPSendMessage() is passed five arguments:

The token for the IACP link.
The EventHandle of an encapsulated message.
The TravelOption for that message.
An encapsulated completion message; this will be dispatched once each time the first message has been successfully handled.
A member of the IACPSide enumerated type. This tells whether the message is being sent by a client or a server. If you pass the value IACPS_CLIENT, the message will be dispatched to all servers; if you pass IACPS_SERVER, the message will be dispatched to all clients.

The message will be dispatched to all geodes on the other side of a link. Note that a client need not send the message to the server object per se. It can use the travel options field to direct the message anywhere within the server object's geode. It can also specify the optr of the recipient when it encapsulates the message; in this case, it should pass a TravelOption of -1.

Every time the encapsulated message is successfully handled, the "completion message" will be dispatched. Typically, the completion message is addressed to the object that called IACPSendMessage() , instructing it to free global resources that had been allocated for the message.

The routine returns the number of messages that were dispatched. This lets the sender know how many completion messages to expect, and lets it properly initialize all reference counts to global resources.

A client may choose to send a message to a specific server. It can do this by calling IACPSendMessageToServer() . This takes almost the same arguments as IACPSendMessage() . However, instead of being passed an IACPSide value, it is passed a server number. GEOS will dispatch a single copy of the message to the specified server. IACPSendMessageToServer() returns the number of times the message was dispatched. This will ordinarily be one; however, if the specified server is no longer registered, it will be zero.

GEOS SDK TechDocs |

6.2 GenApplicationClass Behavior | Next:

6.4 Being a Client