|
|
|
iiop_util - Internet Inter-ORB Protocol (IIOP) StreamsThe CORBA-Lite IIOP utilities are used to send and receive Internet Inter-ORB Protocol (IIOP) messages over TCP/IP network connections. An IIOP message consists of a 12-byte header followed by a message body. The contents of the header specify the message type and the length of the message body.
A IIOP stream is created on a previously established network connection. The following program implements a simple IIOP server that reads messages from a client:
#include <stdio.h> -- Standard I/O definitions.
#include "tcp_util.h" -- TCP/IP networking utilities.
#include "iiop_util.h" -- IIOP streams.
int main (int argc, char *argv[])
{
IiopStream stream ;
IiopHeader header ;
octet *body ;
TcpEndpoint client, server ;
tcpListen (argv[1], 99, &server) ; -- Create listening endpoint.
for ( ; ; ) { -- Answer next client.
tcpAnswer (server, -1.0, &client) ;
iiopCreate (client, &stream) ;
for ( ; ; ) { -- Read messages from client.
if (iiopRead (stream, -1.0, &header, &body)) break ;
... do something with the message ...
}
iiopDestroy (stream) ; -- Lost client.
}
}
The server's name is specified as the first argument on the command line
(i.e., argv[1]). If a client connection is broken, the server
loops back to wait for another client.
The client program below sends a request to an IIOP server:
#include <stdio.h> -- Standard I/O definitions.
#include "tcp_util.h" -- TCP/IP networking utilities.
#include "iiop_util.h" -- IIOP streams.
int main (int argc, char *argv[])
{
IiopStream stream ;
IiopHeader header ;
octet *body ;
TcpEndpoint connection ;
tcpCall (argv[1], 0, &connection) ; -- Call server.
iiopCreate (connection, &stream) ;
... set up message header and body ...
if (iiopWrite (stream, -1.0, &header, body)) {
... error writing to server ...
}
free (body) ;
if (iiopRead (stream, -1.0, &header, &body)) {
... error reading from server ...
}
iiopDestroy (stream) ; -- Drop server.
}
Every IIOP message, as transferred over a network connection, consists of a 12-byte message header and, optionally, a message body encoded using CORBA's Common Data Representation (CDR). The message header includes the following fields:
"GIOP" - in the first 4 bytes.
Version - specifies the GIOP version number (e.g., 1.0, 1.1, 1.2) used in the construction of the message.
Flags - most importantly, a byte-order flag that is set if the encoded data in the message is little-endian.
Type - is the GIOP::MsgType: Request, Reply, etc.
Size - is the size in bytes of the message body that follows the message header.
The IiopHeader structure returned by iiopRead()
and passed into iiopWrite() is a logical structure. In the
case of iiopRead(), the fields in the header are set based on
the contents of the physical 12-byte header. GIOP 1.0- and 1.1-specific
fields are converted to their 1.2 counterparts and the message size is
converted from the message byte order to host byte order. (GIOP 1.2 was
the latest GIOP version at the time this software was written.) In the case
of iiopWrite(), the physical 12-byte header is constructed
from the logical fields; the host byte order is assumed for message byte
order and GIOP 1.2-specific fields are converted to their earlier
counterparts depending on the version number specified in the logical
header.
The message body contains data encoded in CDR according to the GIOP version number in the header and in the byte order (big- or little-endian) indicated by the flag. See the CORBA Marshaling utilities (COMX_UTIL) for CDR decoding and encoding functions. As an example of a message body, consider the Request message. The message body consists of:
Request Header - specifying the target object of the request the operation to be performed.
Arguments - are the values, encoded in CDR, of the input and input/output parameters expected by the operation.
The similar Reply message body consists of:
Reply Header - specifying the completion status of the requested operation.
Return Values - are the return values, encoded in CDR, of the input/output and output parameters resulting from successful completion of the operation.
Function Value - is the returned function value, if any, from the operation.
Both iiopRead() and iiopWrite() take a timeout
argument that allows the application to limit the amount of time these
routines wait to perform their respective functions.
In event-driven applications (e.g., those based on the X Toolkit or the
IOX dispatcher), the socket connection
underlying the IIOP stream, returned by iiopFd(), can
be monitored for input by your event dispatcher. Because input is
buffered, the input callback must repeatedly call iiopRead()
while iiopIsReadable() is true.
When a IIOP stream is no longer needed, a single call will close the network connection and discard the stream:
iiopDestroy (stream) ;
CORBA IOP service contexts are additional (and optional) information that can
be sent along in requests to a CORBA service; see
coliRequest(). Service contexts
don't have anything to do with IIOP especially, but the IiopStream seemed
to be a useful holder for the service context list. An application or
library can create an IIOP stream, create a service context list, bind the
list to the stream using iiopSetContexts(), and then retrieve
it whenever needed using iiopGetContexts(). The list will be
automatically deallocated when the stream is destroyed.
iiopCreate() - creates an IIOP stream.
iiopDestroy() - deletes an IIOP network stream.
iiopFd() - returns an IIOP stream's socket number.
iiopGetContexts() - returns a stream's service contexts.
iiopIsReadable() - checks if input is waiting to be read from
a stream.
iiopIsUp() - checks if an IIOP stream is up.
iiopIsWriteable() - checks if data can be written to a stream.
iiopName() - returns the name of an IIOP stream.
iiopRead() - reads the next message from an IIOP stream.
iiopRequestID() - gets the next request ID.
iiopSetContexts() - sets a stream's service contexts.
iiopWrite() - writes a message to an IIOP stream.
iiop_util.c
iiop_util.h