This appendix gives the IDL specification of the conversation manager.
It makes use of declarations given in
Following are brief descriptions of the server operations:
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.)
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).
Use of conv_are_you_there() is implementation-specific (see convc_indy() below).
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.
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
);
}
Following is a brief description of the client operation:
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 |