Inter-Client Exchange Library

When an application detects that there is new data to read on an ICE connection (via select it calls the IceProcessMessages function Chapter 9, Processing Messages. When IceProcessMessages reads an ICE message header with a major opcode other than zero (reserved for the ICE protocol), it needs to call a function that will read the rest of the message, unpack it, and process it accordingly.

If the message arrives at the client that initiated the ProtocolSetup the IcePoProcessMsgProc callback is invoked.

If the message arrives at the client that accepted the ProtocolSetup the IcePaProcessMsgProc callback is invoked.

In order to read the message, both of these callbacks should use the macros defined for this purpose (see the section called “Reading ICE Messages”.). Note that byte swapping may be necessary. As a convenience, the length field in the ICE header will be swapped by ICElib if necessary.

In both of these callbacks, the client_data argument is a pointer to client data that was registered at ProtocolSetup time. In the case of IcePoProcessMsgProc the client data was set in the call to IceProtocolSetup In the case of IcePaProcessMsgProc the client data was set in the IceProtocolSetupProc callback.

The IcePoProcessMsgProc callback needs to check the reply_wait argument. If reply_wait is NULL , the ICE library expects the function to pass the message to the client via a callback. For example, if this is a Session Management "Save Yourself" message, this function should notify the client of the "Save Yourself" via a callback. The details of how such a callback would be defined are implementation-dependent.

However, if reply_wait is not NULL , then the client is waiting for a reply or an error for a message it previously sent. The reply_wait is of type IceReplyWaitInfo

IceReplyWaitInfo contains the major/minor opcodes and sequence number of the message for which a reply is being awaited. It also contains a pointer to the reply message to be filled in (the protocol library should cast this IcePointer to the appropriate reply type). In most cases, the reply will have some fixed-size part, and the client waiting for the reply will have provided a pointer to a structure to hold this fixed-size data. If there is variable-length data, it would be expected that the IcePoProcessMsgProc callback will have to allocate additional memory and store pointer(s) to that memory in the fixed-size structure. If the entire data is variable length (for example., a single variable-length string), then the client waiting for the reply would probably just pass a pointer to fixed-size space to hold a pointer, and the IcePoProcessMsgProc callback would allocate the storage and store the pointer. It is the responsibility of the client receiving the reply to free any memory allocated on its behalf.

If reply_wait is not NULL and IcePoProcessMsgProc has a reply or error to return in response to this reply_wait (that is, no callback was generated), then the reply_ready_ret argument should be set to True Note that an error should only be returned if it corresponds to the reply being waited for. Otherwise, the IcePoProcessMsgProc should either handle the error internally or invoke an error handler for its library.

If reply_wait is NULL, then care must be taken not to store any value in reply_ready_ret, because this pointer may also be NULL.

The IcePaProcessMsgProc callback, on the other hand, should always pass the message to the client via a callback. For example, if this is a Session Management "Interact Request" message, this function should notify the client of the "Interact Request" via a callback.

The reason the IcePaProcessMsgProc callback does not have a reply_wait, like IcePoProcessMsgProc does, is because a process that is acting as a server should never block for a reply (infinite blocking can occur if the connecting client does not act properly, denying access to other clients).

As already stated, a protocol library must register the authentication methods that it supports with the ICE library. For each authentication method, there are two callbacks that may be registered:

IcePoAuthProc is the callback invoked for the client that initiated the ProtocolSetup This callback must be able to respond to the initial "Authentication Required" message or subsequent "Authentication Next Phase" messages sent by the other client.

Authentication may require several phases, depending on the authentication method. As a result, the IcePoAuthProc may be called more than once when authenticating a client, and some state will have to be maintained between each invocation. At the start of each ProtocolSetup *auth_state_ptr is NULL, and the function should initialize its state and set this pointer. In subsequent invocations of the callback, the pointer should be used to get at any state previously stored by the callback.

If needed, the network ID of the client accepting the ProtocolSetup can be obtained by calling the IceConnectionString function.

ICElib will be responsible for freeing the reply_data_ret and error_string_ret pointers with free

The auth_data pointer may point to a volatile block of memory. If the data must be kept beyond this invocation of the callback, be sure to make a copy of it.

The IcePoAuthProc should return one of four values:

IcePaAuthProc is the callback invoked for the client that received the ProtocolSetup

Authentication may require several phases, depending on the authentication method. As a result, the IcePaAuthProc may be called more than once when authenticating a client, and some state will have to be maintained between each invocation. At the start of each ProtocolSetup auth_datalen is zero, *auth_state_ptr is NULL, and the function should initialize its state and set this pointer. In subsequent invocations of the callback, the pointer should be used to get at any state previously stored by the callback.

If needed, the network ID of the client accepting the ProtocolSetup can be obtained by calling the IceConnectionString function.

The auth_data pointer may point to a volatile block of memory. If the data must be kept beyond this invocation of the callback, be sure to make a copy of it.

ICElib will be responsible for transmitting and freeing the reply_data_ret and error_string_ret pointers with free

The IcePaAuthProc should return one of four values:

To open an ICE connection with another client (that is, waiting for connections), use IceOpenConnection

IceOpenConnection returns an opaque ICE connection object if it succeeds; otherwise, it returns NULL.

The network_ids_list argument contains a list of network IDs separated by commas. An attempt will be made to use the first network ID. If that fails, an attempt will be made using the second network ID, and so on. Each network ID has the following format:

Most protocol libraries will have some sort of open function that should internally make a call into IceOpenConnection When IceOpenConnection is called, it may be possible to use a previously opened ICE connection (if the target client is the same). However, there are cases in which shared ICE connections are not desired.

The context argument is used to determine if an ICE connection can be shared. If context is NULL, then the caller is always willing to share the connection. If context is not NULL, then the caller is not willing to use a previously opened ICE connection that has a different non-NULL context associated with it.

In addition, if major_opcode_check contains a nonzero major opcode value, a previously created ICE connection will be used only if the major opcode is not active on the connection. This can be used to force multiple ICE connections between two clients for the same protocol.

Any authentication requirements are handled internally by the ICE library. The method by which the authentication data is obtained is implementation-dependent. ^[1]

After IceOpenConnection is called, the client is ready to send a ProtocolSetup (provided that IceRegisterForProtocolSetup was called) or receive a ProtocolSetup (provided that IceRegisterForProtocolReply was called).

Clients wishing to accept ICE connections must first call IceListenForConnections or IceListenForWellKnownConnections so that they can listen for connections. A list of opaque "listen" objects are returned, one for each type of transport method that is available (for example, Unix Domain, TCP, DECnet, and so on).

Normally clients will let ICElib allocate an available name in each transport and return listen objects. Such a client will then use IceComposeNetworkIdList to extract the chosen names and make them available to other clients for opening the connection. In certain cases it may be necessary for a client to listen for connections on pre-arranged transport object names. Such a client may use IceListenForWellKnownConnections to specify the names for the listen objects.

The return value of IceListenForConnections is zero for failure and a positive value for success.

IceListenForWellKnownConnections constructs a list of network IDs by prepending each known transport to port_id and then attempts to create listen objects for the result. Port_id is the portnumber, objname, or path portion of the ICE network ID. If a listen object for a particular network ID cannot be created the network ID is ignored. If no listen objects are created IceListenForWellKnownConnections returns failure.

The return value of IceListenForWellKnownConnections is zero for failure and a positive value for success.

To close and free the listen objects, use IceFreeListenObjs

To detect a new connection on a listen object, use select on the descriptor associated with the listen object.

To obtain the descriptor, use IceGetListenConnectionNumber

To obtain the network ID string associated with a listen object, use IceGetListenConnectionString

A network ID has the following format:

To compose a string containing a list of network IDs separated by commas (the format recognized by IceOpenConnection use IceComposeNetworkIdList

If authentication fails when a client attempts to open an ICE connection and the initiating client has not required authentication, a host based authentication procedure may be invoked to provide a last chance for the client to connect. Each listen object has such a callback associated with it, and this callback is set using the IceSetHostBasedAuthProc function.

By default, each listen object has no host based authentication procedure associated with it. Passing NULL for host_based_auth_proc turns off host based authentication if it was previously set.

The host_name argument is a string in the form protocol/ hostname, where protocol is one of {tcp, decnet, local}.

If IceHostBasedAuthProc returns True access will be granted, even though the original authentication failed. Note that authentication can effectively be disabled by registering an IceHostBasedAuthProc which always returns True

Host based authentication is also allowed at ProtocolSetup time. The callback is specified in the IceRegisterForProtocolReply function (see Chapter 6, Protocol Registration).

After a connection attempt is detected on a listen object returned by IceListenForConnections you should call IceAcceptConnection This returns a new opaque ICE connection object.

The status_ret argument is set to one of the following values:

In general, to detect new connections, you should call select on the file descriptors associated with the listen objects. When a new connection is detected, the IceAcceptConnection function should be called. IceAcceptConnection may return a new ICE connection that is in a pending state. This is because before the connection can become valid, authentication may be necessary. Because the ICE library cannot block and wait for the connection to become valid (infinite blocking can occur if the connecting client does not act properly), the application must wait for the connection status to become valid.

The following pseudo-code demonstrates how connections are accepted:

new_ice_conn = IceAcceptConnection (listen_obj, &accept_status);
if (accept_status != IceAcceptSuccess)
{
     close the file descriptor and return
}

status = IceConnectionStatus (new_ice_conn);
time_start = time_now;

while (status == IceConnectPending)
{
     select() on {new_ice_conn, all open connections}

     for (each ice_conn in the list of open connections)
          if (data ready on ice_conn)
          {
               status = IceProcessMessages (ice_conn, NULL, NULL);
               if (status == IceProcessMessagesIOError)
                    IceCloseConnection(ice_conn);
          }
     if data ready on new_ice_conn
     {
          /*
          * IceProcessMessages is called until the connection
          * is non-pending.  Doing so handles the connection
          * setup request and any authentication requirements.
          */

          IceProcessMessages ( new_ice_conn, NULL, NULL);
          status = IceConnectionStatus (new_ice_conn);
     }
     else
     {
          if (time_now - time_start > MAX_WAIT_TIME)
               status = IceConnectRejected;
     }
}

if (status == IceConnectAccepted)
{
     Add new_ice_conn to the list of open connections
}
else
{
     IceCloseConnection
     new_ice_conn
}

After IceAcceptConnection is called and the connection has been validated, the client is ready to receive a ProtocolSetup (provided that IceRegisterForProtocolReply was called) or send a ProtocolSetup (provided that IceRegisterForProtocolSetup was called).

To close an ICE connection created with IceOpenConnection or IceAcceptConnection use IceCloseConnection

To actually close an ICE connection, the following conditions must be met:

When it is known that the client on the other side of the ICE connection has terminated the connection without initiating shutdown negotiation, the IceSetShutdownNegotiation function should be called to turn off shutdown negotiation. This will prevent IceCloseConnection from writing to a broken connection.

To check the shutdown negotiation status of an ICE connection, use IceCheckShutdownNegotiation

IceCheckShutdownNegotiation returns True if shutdown negotiation will take place on the connection; otherwise, it returns False Negotiation is on by default for a connection. It can only be changed with the IceSetShutdownNegotiation function.

To add a watch procedure that will be called each time ICElib opens a new connection via IceOpenConnection or IceAcceptConnection or closes a connection via IceCloseConnection use IceAddConnectionWatch

The return value of IceAddConnectionWatch is zero for failure, and a positive value for success.

Note that several calls to IceOpenConnection might share the same ICE connection. In such a case, the watch procedure is only invoked when the connection is first created (after authentication succeeds). Similarly, because connections might be shared, the watch procedure is called only if IceCloseConnection actually closes the connection (right before the IceConn is freed).

The watch procedures are very useful for applications that need to add a file descriptor to a select mask when a new connection is created and remove the file descriptor when the connection is destroyed. Because connections are shared, knowing when to add and remove the file descriptor from the select mask would be difficult without the watch procedures.

Multiple watch procedures may be registered with the ICE library. No assumptions should be made about their order of invocation.

If one or more ICE connections were already created by the ICE library at the time the watch procedure is registered, the watch procedure will instantly be invoked for each of these ICE connections (with the opening argument set to True

The watch procedure is of type IceWatchProc

If opening is True the client should set the *watch_data pointer to any data it may need to save until the connection is closed and the watch procedure is invoked again with opening set to False

To remove a watch procedure, use IceRemoveConnectionWatch

The ICE library maintains an output buffer used for generating messages. Protocol libraries layered on top of ICE may choose to batch messages together and flush the output buffer at appropriate times.

If an IO error has occurred on an ICE connection, all write operations will be ignored. For further information, see Chapter 13, Error Handling.

To get the size of the ICE output buffer, use IceGetOutBufSize

To flush the ICE output buffer, use IceFlush

Note that the output buffer may be implicitly flushed if there is insufficient space to generate a message.

The following macros can be used to generate ICE messages:

IceGetHeader is used to set up a message header on an ICE connection. It sets the major and minor opcodes of the message, and initializes the message's length to the length of the header. If additional variable length data follows, the message's length field should be updated.

IceGetHeaderExtra is used to generate a message with a fixed (and relatively small) amount of variable length data. The complete message must fit in the ICE output buffer.

IceSimpleMessage is used to generate a message that is identical in size to the ICE header message, and has no additional data.

IceErrorHeader sets up an error message header.

Note that the two clients connected by ICE may be using different major opcodes for a given protocol. The offending_major_opcode passed to this macro is the major opcode of the protocol for the client sending the error message.

Generic errors, which are common to all protocols, have classes in the range 0x8000..0xFFFF. See the Inter-Client Exchange Protocol standard for more details.

Per-protocol errors have classes in the range 0x0000-0x7fff.

To write data to an ICE connection, use the IceWriteData macro. If the data fits into the ICE output buffer, it is copied there. Otherwise, the ICE output buffer is flushed and the data is directly sent.

This macro is used in conjunction with IceGetHeader and IceErrorHeader

To write data as 16-bit quantities, use IceWriteData16

To write data as 32-bit quantities, use IceWriteData32

To write data as 32-bit quantities, use IceWriteData32

To bypass copying data to the ICE output buffer, use IceSendData to directly send data over the network connection. If necessary, the ICE output buffer is first flushed.

To force 32-bit or 64-bit alignment, use IceWritePad A maximum of 7 pad bytes can be specified.

The ICE library maintains an input buffer used for reading messages. If the ICE library chooses to perform nonblocking reads (this is implementation-dependent), then for every read operation that it makes, zero or more complete messages may be read into the input buffer. As a result, for all of the macros described in this section that read messages, an actual read operation will occur on the connection only if the data is not already present in the input buffer.

To get the size of the ICE input buffer, use IceGetInBufSize

When reading messages, care must be taken to check for IO errors. If any IO error occurs in reading any part of a message, the message should be thrown out. After using any of the macros described below for reading messages, the IceValidIO macro can be used to check if an IO error occurred on the connection. After an IO error has occurred on an ICE connection, all read operations will be ignored. For further information, see Chapter 13, Error Handling.

The following macros can be used to read ICE messages.

IceReadSimpleMessage is used for messages that are identical in size to the 8-byte ICE header, but use the spare 2 bytes in the header to encode additional data. Note that the ICE library always reads in these first 8 bytes, so it can obtain the major opcode of the message. IceReadSimpleMessage simply returns a pointer to these 8 bytes; it does not actually read any data into the input buffer.

For a message with variable length data, there are two ways of reading the message. One method involves reading the complete message in one pass using IceReadCompleteMessage The second method involves reading the message header (note that this may be larger than the 8-byte ICE header), then reading the variable length data in chunks (see IceReadMessageHeader and IceReadData

If the ICE input buffer has sufficient space, IceReadCompleteMessage will read the complete message into the ICE input buffer. Otherwise, a buffer will be allocated to hold the variable length data. After the call, the pdata argument should be checked against NULL to make sure that there was sufficient memory to allocate the buffer.

After calling IceReadCompleteMessage and processing the message, IceDisposeCompleteMessage should be called.

If a buffer had to be allocated to hold the variable length data (because it did not fit in the ICE input buffer), it is freed here by ICElib.

IceReadMessageHeader reads just the message header. The rest of the data should be read with the IceReadData family of macros. This method of reading a message should be used when the variable length data must be read in chunks.

To read data directly into a user supplied buffer, use IceReadData

To read data as 16-bit quantities, use IceReadData16

To read data as 32-bit quantities, use IceReadData32

To force 32-bit or 64-bit alignment, use IceReadPad A maximum of 7 pad bytes can be specified.