Standard Control Operations

Protocol and Session Operations

These operations can be performed on both sessions and protocols.

GETMYHOST, GETMYHOSTCOUNT

When used on a protocol, GETMYHOST asks for all possible host addresses for the local host. When used on a session, GETMYHOST asks for the local host addresses actually being used on the connection. If the buffer is too small for all of the hosts, GETMYHOST will write as many hosts as the buffer allows (GETMYHOST with a buffer large enough to hold one host will return the most common or default host.) GETMYHOSTCOUNT asks for the number of hosts which will be returned by GETMYHOST.

GETMAXPACKET, GETOPTPACKET

Treats the buffer as a pointer to an integer and sets it to the length of the longest message that the XObj can deliver (GETMAXPACKET) or the length of the longest message that can be delivered without fragmentation (GETOPTPACKET.) A protocol typically implements this operation by querying the lower XObjs and then subtracting its header length.

Although GETMAXPACKET and GETOPTPACKET can be performed on protocols, it is preferable to use them on sessions, since different sessions of the same protocol may return different values.

RESOLVE, RRESOLVE

These operations map high-level addresses into low-level addresses (RESOLVE) and vice versa (RRESOLVE.)

Session Operations

GETPEERHOST, GETPEERHOSTCOUNT

GETPEERHOST returns the host addresses of all peers of a session. It is an error to submit a buffer that is too small for all of the peer hosts, and -1 will be returned. GETPEERHOSTCOUNT asks for the number of hosts which will be returned by GETPEERHOST.

GETMYPROTO, GETPEERPROTO

Treats the buffer as a pointer to a long and sets it to the local or remote ``protocol number'' of the session. For example, UDP returns the local UDP port from a GETMYPROTO operation.

GETPARTICIPANTS

Treats the buffer as a simple array of bytes. The lower session creates a participant list with data that was used to open the session. This participant list is then written into the control buffer using partExternalize (see section 3.) The caller will have to run partInternalize on the buffer before it can be used as a participant list.

Sessions typically implement this control op by first executing it on their lower session. If their protocol uses information on participant stacks, they then run partInternalize on the buffer, push their protocol-specific information on the participant stacks, and then re-externalize the participant list into the buffer.

FREERESOURCES

Treats the buffer as a pointer to an xmsg_handle_t. This value is interpreted as the result of a previous xPush and frees the resources associated with that message.

SETNONBLOCKINGIO

Treats the buffer as a pointer to an int (non-zero == TRUE.) This operation is interpreted by sessions which do output buffering. Such sessions may block threads executing an xPush until sufficient buffer space is available to hold the outgoing message. If SETNONBLOCKINGIO(true) is performed on such a session, a thread which would normally block in such a situation returns with an XMSG_ERR_WOULDBLOCKmessage handle instead.