RpcEpRegister
The RpcEpRegister
function adds to or replaces server address information in the local
endpoint-map database.
This function
is supported by both 32-bit platforms Windows NT and Windows 95.
#include <rpc.h>
RPC_STATUS RPC_ENTRY RpcEpRegister(
RPC_IF_HANDLE IfSpec, |
|
RPC_BINDING_VECTOR * BindingVector, |
|
UUID_VECTOR * UuidVector, |
|
unsigned char * Annotation |
|
); |
|
Parameters
IfSpec
Specifies an
interface to register with the local endpoint-map database.
BindingVector
Points to a
vector of binding handles over which the server can receive remote procedure
calls.
UuidVector
Points to a
vector of object UUIDs offered by the server. The server application constructs
this vector.
A null
argument value indicates there are no object UUIDs to register.
Annotation
Points to the
character-string comment applied to each cross-product element added to the
local endpoint-map database. The string can be up to 64 characters long,
including the null terminating character. Specify a null value or a
null-terminated string ( \0 ) if there is no annotation string.
The
annotation string is used by applications for information only. RPC does not
use this string to determine which server instance a client communicates with
or for enumerating elements in the endpoint-map database.
Remarks
The RpcEpRegister
routine adds or replaces entries in the local host s endpoint-map database. For
an existing database entry that matches the provided interface specification,
binding handle, and object UUID, this routine replaces the entry s endpoint
with the endpoint in the provided binding handle.
A server uses
RpcEpRegister rather than RpcEpRegisterNoReplace when only a
single instance of the server will run on the server s host. In other words,
use this routine when no more than one server instance will offer the same
interface UUID, object UUID, and protocol sequence at any one time.
When entries
are not replaced, stale data accumulates each time a server instance stops
running without calling RpcEpUnregister. Stale entries increase the
likelihood that a client will receive endpoints to nonexistent servers. The
client will spend time trying to communicate with a nonexistent server before
obtaining another endpoint.
Using RpcEpRegister
to replace existing endpoint-map database entries reduces the likelihood that a
client will be given the endpoint of a nonexistent server instance. A server
application calls this routine to register endpoints specified by calling any
of the following routines:
RpcServerUseAllProtseqs
RpcServerUseProtseq
RpcServerUseProtseqEp
A server that
calls only RpcServerUseAllProtseqsIf or RpcServerUseProtseqIf
does not need to call RpcEpRegister. In this case, the client s run-time
library uses an endpoint from the client s interface specification to fill in a
partially bound binding handle.
If the server
also exports to the name-service database, the server calls RpcEpRegister
with the same IfSpec, BindingVector, and UuidVector that
the server uses when calling the RpcNsBindingExport routine.
For
automatically started servers running over one of the connection-based protocol
sequences (ncacn_np, ncacn_nb, ncacn_ip_tcp, ncacn_osi_dns),
the RPC run-time library automatically generates a dynamic endpoint. In this
case, the server can call RpcServerInqBindings followed by RpcEpRegister
to make itself available to multiple clients. Otherwise, the automatically
started server is known only to the client for which the server was started.
Each element
added to the endpoint-map database logically contains the following:
Interface UUID
Interface version (major and
minor)
Binding handle
Object UUID (optional)
Annotation (optional)
RpcEpRegister creates a cross-product from the IfSpec, BindingVector,
and UuidVector arguments and adds each element in the cross-product as a
separate registration in the endpoint-map database.
Return Values
Value |
Meaning |
RPC_S_OK |
Success |
RPC_S_NO_BINDINGS |
No bindings |
RPC_S_INVALID_BINDING |
Invalid
binding handle |
RPC_S_WRONG_KIND_OF_BINDING |
Wrong kind
of binding for operation |
See Also