NAME

rpc_ep_register_no_replace - Adds to server address information in the local endpoint map

Used by server applications. 

SYNOPSIS

#include <dce/rpc.h>
void rpc_ep_register_no_replace(

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_handleSpecifies an interface specification to register with the local endpoint map. 

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

object_uuid_vecSpecifies a vector of object UUIDs that the server offers. The server application constructs this vector.  Supply the value NULL to indicate there are no object UUIDs to register. 

annotationDefines 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.  Specify NULL or the string \0 if there is no annotation string.  The string is used by applications for informational purposes only. The RPC runtime does not use this string to determine which server instance a client communicates with, or for enumerating endpoint map elements.

Output

statusReturns the status code from this routine.  This status code indicates whether the routine completed successfully or, if not, why not.  The possible status codes and their meanings are as follows:

rpc_s_okSuccess. 

ept_s_cant_accessError reading endpoint database. 

ept_s_cant_createError creating endpoint database. 

ept_s_cant_perform_opCannot perform requested operation. 

ept_s_database_invalidEndpoint map database invalid. 

ept_s_invalid_entryInvalid database entry. 

ept_s_update_failedUpdate failed. 

rpc_s_comm_failureCommunications failure. 

rpc_s_invalid_bindingInvalid binding handle. 

rpc_s_invalid_if_handleInvalid interface handle. 

rpc_s_no_bindingsNo bindings. 

rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.

DESCRIPTION

The rpc_ep_register_no_replace routine adds elements to the local host’s endpoint map.  The routine does not replace existing elements.  Otherwise, this routine is identical to routine rpc_ep_register. 

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

       •Annotation (optional)

A server uses this routine, instead of routine rpc_ep_register, when multiple instances of the server run on the same host.  Use this routine if, at any time, more than one server instance offers the same interface UUID, object UUID, and protocol sequence. 

Since this routine does not replace elements, calling servers must unregister (that is, remove) themselves before they stop running.  Otherwise, when local endpoint map elements are not replaced, obsolete elements accumulate each time a server instance stops running without calling routine rpc_ep_unregister.  Periodically the RPC daemon (RPCD) identifies obsolete elements and removes them from the local endpoint map.  However, during the time between these removals the obsolete elements increase the chance that a client will receive endpoints to nonexistent servers.  The client then wastes time trying to communicate with these servers before obtaining another endpoint. 

A server program calls this routine to register endpoints that were specified by calling any of the following routines:

       •rpc_server_use_all_protseqs

       •rpc_server_use_protseq

       •rpc_server_use_protseq_ep

A server that calls only the rpc_server_use_all_protseqs_if or rpc_server_use_protseq_if routines does not need to call this routine.  In such cases, the client’s runtime uses an endpoint from the client’s interface specification to fill in a partially bound binding handle.  However, it is recommended that you also register well-known endpoints that the server specifies (registering endpoints from interface definitions is unnecessary). 

If the server also exports to the name service database, the server calls this routine with the same if_handle, binding_vec and object_uuid_vec arguments as the server uses when calling the rpc_ns_binding_export routine. 

Routine rpc_ep_register_no_replace communicates with the RPC daemon (RPCD) which, in turn, communicates with the local endpoint map.  The routine communicates using one of the protocol sequences specified in one of the binding handles in argument binding_vec.  Attempting to register a binding that specifies a protocol sequence that the RPC daemon is not listening on results in the failure of routine rpc_ep_register_no_replace.  The routine indicates this failure by placing the value rpc_s_comm_failure into argument status. 

For information about how the endpoint map service selects an element for an interface ID and an object UUID, see the NCS 2.0 Programmer’s Guide. 

For an explanation of how a server can establish a client-server relationship without using the local endpoint map, see the explanation of a string binding in the rpc_intro(3) reference page. 

This routine creates a cross-product from the if_handle, binding_vec and object_uuid_vec arguments, and adds each element in the cross-product as a separate registration in the local endpoint map.  The description of the rpc_ep_register routine summarizes the contents of an element in the local endpoint map. 

RETURN VALUES

None. 

RELATED INFORMATION

Functions: rpc_ep_register(3), rpc_ep_resolve_binding(3), rpc_ep_unregister(3), rpc_mgmt_ep_unregister(3), rpc_ns_binding_export(3), rpc_server_inq_bindings(3), rpc_server_use_all_protseqs(3), rpc_server_use_all_protseqs_if(3), rpc_server_use_protseq(3), rpc_server_use_protseq_ep(3), rpc_server_use_protseq_if(3)