Applications and Geodes: 6.4 Inter-Application Communication: Being a Client

6.3 Messages Across an IACP Link | Next:

Any object can register as a client for an IACP server list. When an object is a client, it can send messages to the server list, which will pass them along to the servers for that list.

Registering as a Client

IACPConnect(), IACPCreateDefaultLaunchBlock()

To register as a client for a list, call the routine IACPConnect() . When you call this routine, you specify which server list you are interested in. If there is no such server list running, you can instruct the kernel to start up the server list, as well as one of the default applications for that list.

IACPConnect() is passed five arguments:

The GeodeToken of the list for which you want to register.
A set of IACPConnectFlags . The following flags are available:

IACPCF_OBEY_LAUNCH_MODEL: This indicates that GEOS should follow the launch model, which will specify whether the user should be presented a dialog box, asking the user whether an existing application should be used as the server, or a new application launched. If you set this flag, you must pass an AppLaunchBlock , with the ALB_appMode field set to MSG_GEN_PROCESS_OPEN_APPLICATION; you must also set IACPCF_SERVER_MODE to IACPSM_USER_INTERACTIBLE.
IACPCF_CLIENT_OD_SPECIFIED: This flag indicates that you will specify what object will be the new client. If you do not set this flag, the sending geode's Application object will be registered as the client.
IACPCF_FIRST_ONLY: If you pass this flag, the client will be connected to only the first server on the server list. Any messages sent by the client to the server list will be passed only to that one server.
IACPCF_SERVER_MODE: This field is three bits wide; it holds 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 need not interact with the user.
IACPSM_USER_INTERACTIBLE: This is equal to two. It indicates that the server should be able to interact with the user like any normal application.

IACPConnect() returns a word-sized IACPConnection token. You will need to pass that token when you call another IACP routine to use the connection. It will also return the number of server objects on the list; it returns this value by writing it to the address indicated by the pointer passed.

If the server list you indicate is not currently running, IACP may do one of two different things. If you pass a null handle as the third argument, IACPConnect() will fail. It will return the error value IACP_NO_CONNECTION, and indicate that there are no servers on the specified list.

If you pass an AppLaunchBlock , IACPConnect() will examine that launch block to see what application should be launched to act as a server. The AppLaunchBlock should specify the location and name of the application to open. If the ALB_appRef.AIR_diskHandle field is non-zero, IACPConnect() will look in the specified disk or standard path for an application with the right GeodeToken ; otherwise, it will look in the standard places for an application.

Note that if you pass a launch block to IACPConnect() , you may not alter or free it afterwards. If the application is created, the block you pass will be its launch block; if not, the kernel will free the block automatically. In any event, the caller no longer has access to the block.

If IACPConnect() launches an application, the caller will block until that application has been created and registers for the server list. If the application does not register for that list, the caller will never unblock. You must therefore make sure that you are launching the right application for the list. Note that every application object will automatically register for the server list which shares its token.

To create a launch block, you should call IACPCreateDefaultLaunchBlock() . This routine is passed a single argument, which specifies how the application will be opened. That argument must be MSG_GEN_PROCESS_OPEN_APPLICATION (the application will be opened as a standard, user-interactible application); MSG_GEN_PROCESS_OPEN_ENGINE (the application will be opened in engine mode, i.e. with no user interface); or MSG_GEN_PROCESS_OPEN_CUSTOM (which has an application-specified meaning).

IACPCreateDefaultLaunchBlock() allocates a launch block and sets up its fields appropriately. As created, the launch block will have the following characteristics:

The application's initial working directory (i.e. the launch block's ALB_diskHandle field) will be SP_DOCUMENT.
No application directory will be specified in the launch block (i.e. ALB_appRef. AIR_diskHandle will be zero); IACPConnect() will attempt to find the application on its own.
No initial data file will be specified (i.e. ALB_dataFile will be blank).
The application will determine its own generic parent (i.e. ALB_genParent will be null).
No extra data word will be passed to the application (i.e. ALB_extraData will be zero).
There will be no output descriptor (i.e. ALB_userLoadAckOutput and ALB_userLoadAckMessage will be null.)

IACPCreateDefaultLaunchBlock() returns the handle of the newly-created launch block. Once the block is created, you can alter any of its fields before passing the launch block to IACPConnect() . (Once you pass the launch block to IACPConnect() , you may not alter it any more.)

Often a client will want the server to open a specific document. For example, if a desktop-manager is implementing a "print-file" command, it will need to open a server application, instruct it to open the file to be printed, and then instruct it to print the file. To make the server open a document, pass the document's name in ALB_dataFile . The server will open the file when you register, and close it when you unregister.

Unregistering as a Client

IACPShutdown(), IACPShutdownAll()

If an application no longer needs to interact with a particular server list, it should call IACPShutdown() . This routine is also used by servers which wish to remove themselves from a server list. This section describes how the routine is used by clients; Being a Server describes how it is used by servers.

The routine is passed two arguments:

The IACPConnection token for the link which is being shut down.
An optr. This must be null if the routine is being called by a client.

IACPShutdown() sends MSG_META_IACP_LOST_CONNECTION to all objects on the other side of the link; that is, if a client calls IACPShutdown() , all servers on the list will be sent this message.

IACPShutdownAll() closes all IACP links for the application which calls it. The Application object automatically calls this routine when the application is exiting.

GEOS SDK TechDocs |

6.3 Messages Across an IACP Link | Next:

6.5 Being a Server