Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

RpcEpRegisterNoReplace function

The RpcEpRegisterNoReplace function adds server-address information to the local endpoint-map database.

Syntax


RPC_STATUS RPC_ENTRY RpcEpRegisterNoReplace(
  RPC_IF_HANDLE IfSpec,
  RPC_BINDING_VECTOR *BindingVector,
  UUID_VECTOR *UuidVector,
  unsigned char *Annotation
);

Parameters

IfSpec

Interface to register with the local endpoint-map database.

BindingVector

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

UuidVector

Pointer to a vector of object UUIDs offered by the server. The server application constructs this vector.

A null parameter value indicates there are no object UUIDs to register.

Annotation

Pointer 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 to enumerate elements in the endpoint-map database.

Return value

ValueMeaning
RPC_S_OK

The call succeeded.

RPC_S_NO_BINDINGS

No bindings.

RPC_S_INVALID_BINDING

The binding handle was invalid.

RPC_S_WRONG_KIND_OF_BINDING

This was the wrong kind of binding for the operation.

 

Note  For a list of valid error codes, see RPC Return Values.

Remarks

The RpcEpRegisterNoReplace function adds entries to the local host's endpoint-map database. This function does not replace existing database entries.

A server uses RpcEpRegisterNoReplace rather than RpcEpRegister when multiple instances of the server will run on the same host. In other words, use this function when more than one server instance will offer the same interface UUID, object UUID, and protocol sequence at any one time.

Because entries are not replaced when calling RpcEpRegisterNoReplace, servers must unregister themselves before they stop running. Otherwise, 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.

A server can use RpcEpRegister and RpcEpRegisterNoReplace to register entries in the endpoint mapper database. Previous to Windows 2000, two functions were available to enable a server to overwrite stale entries in the endpoint mapper database left from previous server instances that are no longer running. The endpoint mapper database automatically removes entries registered by a server instance as soon as the server stops functioning. However, servers are not allowed to replace the endpoint mapper entries of another server for security purposes. Therefore, RpcEpRegister and RpcEpRegisterNoReplace perform largely the same functionality.

A server application calls RpcEpRegister to register endpoints specified by calling any of the following functions:

If the server also exports to the name-service database, the server calls RpcEpRegister with the same IfSpec, BindingVector, and UuidVector values used when calling the RpcNsBindingExport function.

If a protocol sequence is used without specifying an endpoint, the RPC run-time library automatically generates a dynamic endpoint. In this case, the server can call RpcServerInqBindings followed by RpcEpRegisterNoReplace 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)

RpcEpRegisterNoReplace creates a cross-product from the IfSpec, BindingVector, and UuidVector parameters and adds each element in the cross-product as a separate registration in the endpoint-map database.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Rpcdce.h (include Rpc.h)

Library

Rpcrt4.lib

DLL

Rpcrt4.dll

Unicode and ANSI names

RpcEpRegisterNoReplaceW (Unicode) and RpcEpRegisterNoReplaceA (ANSI)

See also

RpcBindingFromStringBinding
RpcEpRegister
RpcEpUnregister
RpcNsBindingExport
RpcServerInqBindings
RpcServerUseAllProtseqs
RpcServerUseAllProtseqsIf
RpcServerUseProtseq
RpcServerUseProtseqEp
RpcServerUseProtseqIf

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.