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:

• interface ID, consisting of an interface UUID and versions (major and minor)

• binding information

• object UUID, which may be the nil UUID

• annotation, which may be an empty string.

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().