Protocol Messages

The Ice protocol uses five messages:

• Request (from client to server)
• Batch request (from client to server)
• Reply (from server to client)
• Validate connection (from server to client to establish the connection, then from either side as a heartbeat)
• Close connection (client to server or server to client)

Of these messages, validate and close connection only apply to connection-oriented transports such as tcp.

As with the Ice Encoding, protocol messages have no alignment restrictions. Each message consists of a message header and (except for validate and close connection) a message body that immediately follows the header.

Message Header

Each protocol message has a 14-byte header that is encoded as if it were the following structure:

struct HeaderData
{
    int  magic;
    byte protocolMajor;
    byte protocolMinor;
    byte encodingMajor;
    byte encodingMinor;
    byte messageType;
    byte compressionStatus;
    int  messageSize;
}

The message header fields are described in the following table.

The valid message types are shown in the following table.

The encoding for the message bodies of each of these message types is described in the sections that follow.

Request Message Body

A request message contains the data necessary to perform an invocation on an object, including the identity of the object, the operation name, and input parameters. A request message is encoded as if it were the following structure:

struct RequestData
{
    int requestId;
    Ice::Identity id;
    Ice::StringSeq facet;
    string operation;
    byte mode;
    Ice::Context context;
    Encapsulation params;
}

The request fields are described in the following table.

The request identifier zero (0) is reserved for use in oneway requests and indicates that the server must not send a reply to the client. The sender gives each of its outstanding twoway requests on the connection a distinct non-zero request identifier.

The facet field has either zero elements or one element. An empty sequence denotes the default facet, and a one-element sequence provides the facet name in its first field. If a receiver receives a request with a facet field with more than one element, it must throw a MarshalException.

Batch Request Message Body

A batch request message contains one or more oneway requests, bundled together for the sake of efficiency. A batch request message is encoded as integer (not a size) that specifies the number of requests in the batch, followed by the corresponding number of requests, encoded as if each request were the following structure:

struct BatchRequestData
{
    Ice::Identity id;
    Ice::StringSeq facet;
    string operation;
    byte mode;
    Ice::Context context;
    Encapsulation params;
}

The batch request fields are described in the following table.

Note that no request ID is necessary for batch requests because only oneway invocations can be batched.

The facet field has either zero elements or one element. An empty sequence denotes the default facet, and a one-element sequence provides the facet name in its first field. If a receiver receives a batch request with a facet field with more than one element, it must throw a MarshalException.

Reply Message Body

A reply message body contains the result of a twoway dispatch, including any return value, out-parameters, or exception. A reply message body is encoded as if it were the following structure:

struct ReplyData
{
    int requestId;
    byte replyStatus;
    byte[messageSize - 19] replyPayload; // pseudo-Slice
}

The first four bytes of a reply message body contain a request ID. The request ID matches an outgoing request and allows the requester to associate the reply with the original request. The requester ignores a reply whose request ID does not match that of an outstanding request, such as the reply to a request that timed out.

The byte following the request ID indicates the status of the request, and the reply payload follows the status byte. The table below shows the possible reply status values; the first column gives the corresponding ReplyStatusReplyStatusReplyStatusReplyStatusReplyStatusReplyStatusReplyStatusReplyStatusReplyStatus enumerator.

Only the payloads of reply statuses 0 and 1 are encapsulations; the RequestFailedData and string payloads follow the status byte directly.

Ok Reply Payload

For reply status 0, the reply payload is an encapsulation that holds the out-parameters and the return value.

User Exception Reply Payload

For reply status 1, the reply payload is an encapsulation that holds the user exception.

Request Failed Reply Payload

For reply statuses 2, 3, and 4, the reply payload is the following structure:

struct RequestFailedData
{
    Ice::Identity id;
    Ice::StringSeq facet;
    string operation;
}

id, facet, and operation hold the identity, facet, and operation name of the target of the request. As in a request, facet has either zero elements or one element.

Validate Connection Message

A server sends a validate connection message when it accepts a new connection, to indicate that it is ready to receive requests: the client must not send any message on this connection before it receives the validate connection message. This message also confirms to the client that the server is indeed an Ice server and not another type of server reached by accident.

The message header comprises the entire validate connection message. The compression status of a validate connection message is always 0.

Close Connection Message

A close connection message is sent when a peer is about to gracefully shutdown a connection.

The message header comprises the entire close connection message. The compression status of a close connection message is always 0.

Either side of a connection can initiate a graceful connection closure. The side that initiates the closure (the initiator) proceeds as follows:

1. The initiator stops sending requests to the peer, and discards any request or batch request it receives from now on, without dispatching it.
2. The initiator waits until its outstanding invocations on the connection have completed, and until the dispatch of all the requests it accepted on the connection has completed and it has sent their replies.
3. The initiator sends a close connection message.
4. The initiator waits for the peer to close the connection, then closes the connection. If the peer does not close the connection within the close timeout, the initiator aborts the connection.

The peer that receives the close connection message (the receiver) closes the connection.

Because of steps 1 and 2, the receiver can re-issue its outstanding requests on a new connection without violating at-most-once semantics. Ice retries these requests as described in Automatic Retries, except for requests sent with a fixed proxy, which is bound to the closed connection.

Connection Abort

Either side can abort a connection at any time: it closes the connection without sending a close connection message. Ice aborts a connection when it detects a violation of the protocol rules, such as a message with a bad magic number, when it receives a message larger than its message size limit, or when the connection does not receive any bytes for longer than the idle timeout.

With a datagram transport such as udp, the receiver discards a datagram that violates the protocol rules and keeps receiving datagrams.

See Also

• Protocol Compression
• Data Encoding for Request and Reply Payloads
• Object Identity
• Versioning
• Request Contexts
• Oneway Invocations
• Batched Invocations
• Automatic Retries
• Connection Closure