Previous section.

CDE 1.1: Remote Procedure Call
Copyright © 1997 The Open Group

Conversation Manager Interface Definition

This appendix gives the IDL specification of the conversation manager. It makes use of declarations given in IDL Data Type Declarations .

Server Interface

Following are brief descriptions of the server operations:

conv_who_are_you()

This operation is called by a server to a client when the server has just received a non-idempotent call request from a client about whom the server knows nothing. The server calls this operation to determine the current sequence number of the client (identified by its activity ID) in question. If the returned sequence number is higher than the one in the request that prompted the conv_who_are_you() call, the request must be a duplicate and is ignored.

This operation is necessarily idempotent since it supports, and hence can not depend on, non-idempotent call semantics.

It is expected, though not logically required, that servers will maintain a cache of client activity ID/current sequence number pairs to minimise the number of times this operations needs to be called by servers. Cache entries can be dropped as is convenient to servers since the cached information can always be re-obtained by making calls on this operation.

The server passes its boot time back to the client to protect against the case where the server receives a request, executes it, crashes before sending the reply, and then reboots and receives a duplicate of the request. In this scenario, the rebooted server will necessarily make a conv_who_are_you() call. However, the input boot time will be different and the client, which will have saved the server's boot time from the conv_who_are_you() call made by the previous incarnation of the server, will notice this and return a non-zero error status to the server, prompting the server to not execute the original request. (Note that the client will still not know whether the call was executed zero or one times. The only guarantee is that it is not executed more than once.)

conv_who_are_you2()

This is a newer version of conv_who_are_you() and has a superset of the older call's semantics. The additional semantics are that this call returns a UUID that uniquely identifies the client's address space (CAS UUID). The CAS UUID is used in cases where the server is monitoring the liveness of a client which is not currently making a remote call to the server (for example, in case the server application is holding state on behalf of the client, and it wants to discard or otherwise clean up this state if the client crashes).

For compatibility with old clients (protocol version < 4), servers do not call this operation to get client sequence number information. Rather, they call this operation if, in the course of processing a client's call, they need the CAS UUID. This operation is constructed as a superset of conv_who_are_you() to make it possible in the future (or in environments with no old clients), for servers to call this operation to get the client's sequence number (and hence avoid making an extra call to get the CAS UUID).

conv_are_you_there()

Use of conv_are_you_there() is implementation-specific (see convc_indy() below).

conv_who_are_you_auth()

The version of conv_who_are_you() that is used to do authenticated RPC. Instead of calling conv_who_are_you() the server can use this function, supplying an authentication challenge to the client, and receive a response to the challenge. Should the client return a status code of rpc_s_partial_credentials, the credentials are large enough to be fragmented. In this case, the server calls conv_who_are_you_auth_more() to get the remainder of the credentials.

conv_who_are_you_auth_more()

This routine is used for fragmented credentials. This is called when conv_who_are_you_auth() returns a status of rpc_s_partial_credentials. The server loops on this routine until all portions of the credentials have been returned by the client.

[uuid(333a2276-0000-0000-0d00-00809c000000), version(3)] 
interface conv
{
    /*
     * C O N V _ W H O _ A R E _ Y O U
     */
    
    [idempotent] 
    void conv_who_are_you(
            [in]    handle_t        h,
            [in]    uuid_t          *actuid,
            [in]    unsigned32      boot_time,
            [out]   unsigned32      *seq,
            [out]   unsigned32      *st
    );
    
    /*
     * C O N V _ W H O _ A R E _ Y O U 2
     */
    
    [idempotent] 
    void conv_who_are_you2(
            [in]    handle_t        h,
            [in]    uuid_t          *actuid,
            [in]    unsigned32      boot_time,
            [out]   unsigned32      *seq,
            [out]   uuid_t          *cas_uuid,
            [out]   unsigned32      *st
    );
    
    /*
     * C O N V _ A R E _ Y O U _ T H E R E
     */
    
    [idempotent] 
    void conv_are_you_there(
            [in]    handle_t        h,
            [in]    uuid_t          *actuid,
            [in]    unsigned32      boot_time,
            [out]   unsigned32      *st
    );
    
    /*
     * C O N V _ W H O _ A R E _ Y O U _ A U T H
     */
    
    [idempotent] 
    void conv_who_are_you_auth(
            [in]    handle_t        h,
            [in]    uuid_t          *actuid,
            [in]    unsigned32      boot_time,
            [in, size_is(in_len)]    
                    byte            in_data[],
            [in]    signed32        in_len,
            [in]    signed32        out_max_len,
            [out]   unsigned32      *seq,
            [out]   uuid_t          *cas_uuid,
            [out, length_is(*out_len), size_is(out_max_len)]    
                    byte            out_data[],
            [out]   signed32        *out_len,
            [out]   unsigned32      *st
    );

    /*
     * C O N V _ W H O _ A R E _ Y O U _ A U T H _ M O R E
     */

    [idempotent]
    void conv_who_are_you_auth_more(
            [in]    handle_t        h,
            [in]    uuid_t          *actuid,
            [in]    unsigned32      boot_time,
            [in]    signed32        index,
            [in]    signed32        out_max_len,
            [out, length_is(*out_len), size_is(out_max_len)]
                    byte            out_data[],
            [out]   signed32        *out_len,
            [out]   unsigned32      *st
    );

}

Client Interface

Following is a brief description of the client operation:

convc_indy()

A client can call this operation to assert its liveness to a server that holds state on its behalf. That is, if a server/client is maintaining liveness and the server does not receive one of these calls within a certain period of time, it will assume the client has died and will notify the server stub routine. Use of convc_indy() is implementation-specific, and not specified in this document.

[uuid(4a967f14-3000-0000-0d00-012882000000), version(1)] 
interface convc
{
    /*
     * C O N V C _ I N D Y
     */
    
    [maybe] 
    void convc_indy(
            [in]    handle_t        h,
            [in]    uuid_t          *cas_uuid
    );
}


Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.

Contents Next section Index