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_handle
Specifies an interface specification to register with the local
endpoint map.
binding_vec
Specifies a vector of 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.
Supply the value NULL to indicate there are no object UUIDs to
register.
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.
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
status
Returns 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_ok Success.
ept_s_cant_access
Error reading endpoint database.
ept_s_cant_create
Error creating endpoint database.
ept_s_cant_perform_op
Cannot perform requested operation.
ept_s_database_invalid
Endpoint map database invalid.
ept_s_invalid_entry
Invalid database entry.
ept_s_update_failed
Update failed.
rpc_s_comm_failure
Communications failure.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_no_bindings
No 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 rpc_ep_register().
Each element in 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 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 rpc_ep_unregister(). Periodically the DCE Host Daemon
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() routine 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 parameters as the server uses when calling the
rpc_ns_binding_export() routine.
The rpc_ep_register_no_replace() routine communicates with the DCE
Host Daemon (dced), 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 binding_vec.
Attempting to register a binding that specifies a protocol sequence
that the DCE Host daemon is not listening on results in the failure
of rpc_ep_register_no_replace(). The routine indicates this failure
by placing the value rpc_s_comm_failure into status.
For information about how the endpoint map service selects an element
for an interface ID and an object UUID, see the RPC information in the
OSF DCE Application Development Guide. This guide explains how the
endpoint map service searches for the endpoint of a server that is
compatible with a client. If the client supplies a non-nil object
UUID that is not in the endpoint map, or the client supplies a nil
object UUID, the search can succeed, but only if the server has
registered a nil object UUID using the rpc_ep_register_no_replace()
or rpc_ep_register() routine. The object_uuid_vec parameter can
contain both nil and non-nil object UUIDs for the routine to place
into endpoint map elements.
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 reference page.
This routine creates a cross-product from the if_handle, binding_vec
and object_uuid_vec parameters, and adds each element in the cross-
product as a separate registration in the local endpoint map. If you
supply NULL to object_uuid_vec, the corresponding elements in the
cross-product contain a nil object UUID. The rpc_ep_register()
routine's reference page summarizes the contents of an element in
the local endpoint map.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_register
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
Books: OSF DCE Application Development Guide.