Previous section.

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

NAME

rpc_ep_register- adds to, or replaces, server address information in the local endpoint map

SYNOPSIS

#include <dce/rpc.h>

void rpc_ep_register( rpc_if_handle_t if_handle, rpc_binding_vector_t *binding_vec, uuid_vector_t *object_uuid_vec, unsigned_char_t *annotation, unsigned32 *status);

PARAMETERS

Input

if_handle
Specifies an interface specification to register with the local endpoint map.

binding_vec
Specifies a vector of server binding handles over which the server can receive remote procedure calls.

object_uuid_vec
Specifies a vector of object UUIDs that the server offers. The server application constructs this vector.

The application supplies the value NULL to indicate that there are no object UUIDs to register. In this case, each cross-product element added to the local endpoint map contains the nil UUID. (See DESCRIPTION for further discussion of cross-product elements.)

annotation
Defines a character string comment applied to each cross-product element added to the local endpoint map. The string can be up to 64 characters long, including the null terminating character. Strings longer than 64 characters are truncated. The application supplies the value NULL or the string "" to indicate an empty annotation string.

When replacing elements, the annotation string supplied, including an empty annotation string, replaces any existing annotation string.

Output

status
Returns the status code from this routine. The status code indicates whether the routine completed successfully, or if not, why not.

Possible status codes and their meanings include:

rpc_s_ok
Success.

ept_s_cant_perform_op

Cannot perform the requested operation.

DESCRIPTION

The rpc_ep_register() routine adds elements to, or replaces elements in, the local host's endpoint map.

Each element added to the local endpoint map logically contains the following:

When an existing map element matches a supplied element, this routine replaces the map element's endpoint with the endpoint from the supplied element's binding information. When there is no such match, a new map element is added.

For a match between an existing and supplied element to occur, the interface UUIDs, object UUIDs and binding information (except for the endpoint) from both elements must be equal. Matching rules for interface version numbers are specified in the following table.

Existing Element Relationship Supplied Element Routine's Action
Major version number Not equal to Major version number Ignores minor version number relationship and adds a new endpoint map element. The existing element remains unchanged.
Major version number Equal to Major version number Acts according to the minor version number relationship.
Minor version number Equal to Minor version number Replaces the endpoint of the existing element based on the supplied information.
Minor version number Less than Minor version number Replaces the existing element based on the supplied information.
Minor version number Greater than Minor version number Ignores the supplied information. The existing element remains unchanged.

A server uses this routine when only a single instance of the server will run on the server's host; that is, when no more than one server instance will offer the same interface UUID, object UUID and protocol sequence. Servers use rpc_ep_register_no_replace() when multiple instances of the server may run on the server's host.

Note:
Servers should call rpc_ep_unregister() to unregister endpoints before they stop running. If a server stops running without calling rpc_ep_unregister(), applications may waste time trying to communicate with the non-existent server. Since rpc_ep_register() replaces existing compatible local endpoint map elements, it will remove obsolete compatible elements left by servers that have crashed without unregistering their endpoints. However, server applications that stop normally should unregister their endpoints. They should not rely on new instantiations to clean up obsolete endpoints

A server application calls this routine to register endpoints that have been specified by calling any of the following routines:

rpc_server_use_all_protseqs() rpc_server_use_all_protseqs_if() rpc_server_use_protseq() rpc_server_use_protseq_ep()
Note:
When the server also exports binding information to the name service database, the server calls this routine with the same if_handle, binding_vec, and object_uuid_vec arguments that the server uses when calling the rpc_ns_binding_export() routine.

The rpc_ep_register() routine creates elements to add to the local endpoint map as a cross-product of the if_handle, binding_vec and object_uuid_vec arguments.

When the object_uuid_vec argument is NULL, the cross-product of if_handle, binding_vec and the nil UUID is created.

The annotation string is also included in each cross-product element. The string is used by applications for informational purposes only. The RPC run-time system does not use it to determine which server instance a client communicates with, or for enumerating endpoint map elements.

The following example shows the cross-product created when if_handle has the value ifhand, binding_vec has the values b1, b2, b3, and object_uuid_vec has the values u1, u2, u3, u4. The cross-product contains 12 elements, as follows:

(ifhand,b1,u1) (ifhand,b1,u2) (ifhand,b1,u3) (ifhand,b1,u4) (ifhand,b2,u1) (ifhand,b2,u2) (ifhand,b2,u3) (ifhand,b2,u4) (ifhand,b3,u1) (ifhand,b3,u2) (ifhand,b3,u3) (ifhand,b3,u4)

Each cross-product element also contains the annotation string.

RETURN VALUE

None.

SEE ALSO


rpc_ep_register_no_replace()
rpc_ep_resolve_binding()
rpc_ep_unregister()
rpc_mgmt_ep_unregister()
rpc_ns_binding_export()
rpc_server_inq_bindings()
rpc_server_use_all_protseqs()
rpc_server_use_all_protseqs_if()
rpc_server_use_protseq()
rpc_server_use_protseq_ep()
rpc_server_use_protseq_if().

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