Home

GEONius.com
2-Oct-2015
E-mail

iiop_util - Internet Inter-ORB Protocol (IIOP) Streams

The 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.


Public Procedures

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.

Source Files

iiop_util.c
iiop_util.h

Alex Measday  /  E-mail