RpcNsBindingExportA function (rpcnsi.h)
The RpcNsBindingExport function establishes a name service–database entry with multiple binding handles and multiple objects for a server.
Syntax
RPC_STATUS RpcNsBindingExportA(
unsigned long EntryNameSyntax,
RPC_CSTR EntryName,
RPC_IF_HANDLE IfSpec,
RPC_BINDING_VECTOR *BindingVec,
UUID_VECTOR *ObjectUuidVec
);
Parameters
EntryNameSyntax
Syntax of EntryName.
To use the syntax specified in the registry value entry HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.
EntryName
Pointer to the entry name to which binding handles and object UUIDs are exported. You cannot provide a null or empty string. The client and the server must both use the same entry name.
IfSpec
Stub-generated data structure specifying the interface to export. A null value indicates there are no binding handles to export (only object UUIDs are to be exported) and BindingVec is ignored.
BindingVec
Pointer to server bindings to export. A null value indicates there are no binding handles to export (only object UUIDs are to be exported).
ObjectUuidVec
Pointer to a vector of object UUIDs offered by the server. The server application constructs this vector. A null value indicates there are no object UUIDs to export (only binding handles are to be exported).
Return value
| Value | Meaning |
|---|---|
|
The call succeeded. |
|
There was nothing to export. |
|
The binding handle was invalid. |
|
This was the wrong kind of binding for the operation. |
|
The name syntax is invalid. |
|
The name syntax is unsupported. |
|
The name is incomplete. |
|
No privilege for name-service operation. |
|
The name service is unavailable. |
Remarks
The RpcNsBindingExport function allows a server application to publicly offer an interface in the name-service database for use by any client application.
Effective with Windows 2000, the RPC run-time environment uses the Active Directory as its name-service database. This means that authorized exported entries persist in the name service, and are visible even after rebooting. Unauthorized exports do not persist. See Access Control in the Security section of the Platform Software Development Kit (SDK) for more information on authorization and Access Control Lists.
To export an interface, the server application calls the RpcNsBindingExport routine with an interface and the server binding handles a client can use to access the server. A server application also calls the RpcNsBindingExport function to publicly offer the object UUID(s) of resource(s) it offers, if any, in the name-service database.
A server can export interfaces and objects in a single call to RpcNsBindingExport, or it can export them separately.If the name-service database entry specified by EntryName does not exist, RpcNsBindingExport tries to create it. In this case, the server application must have the privilege to create the entry.In addition to calling RpcNsBindingExport, a server that called the RpcServerUseAllProtseqs or RpcServerUseProtseq function must also register with the local endpoint-map database by calling either RpcEpRegister or RpcEpRegisterNoReplace.
A server is not required to export any of its interfaces to the name-service database. When a server does not export, only clients that privately know that server's binding information can access its interfaces. For example, a client that has the information needed to construct a string binding can call the RpcBindingFromStringBinding to create a binding handle for making remote procedure calls to a server.
Before calling RpcNsBindingExport, a server must do the following:
- Register one or more protocol sequences with the local RPC run-time library by calling one of the following functions:
- Obtain a list of server bindings by calling the RpcServerInqBindings function.
If a server exports to the same name-service database entry multiple times, the second and subsequent calls to RpcNsBindingExport add the binding information and object UUIDs when that data is different from the binding information already in the server entry. Existing data is not removed from the entry.
To remove binding handles and object UUIDs from the name-service database, a server application calls the RpcNsBindingUnexport function.
A server entry must have at least one binding handle to exist. As a result, exporting only UUIDs to a non-existing entry has no effect, and unexporting all binding handles deletes the entry.
Note
The rpcnsi.h header defines RpcNsBindingExport as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | rpcnsi.h (include Rpc.h) |
| Library | Rpcns4.lib |
| DLL | Rpcns4.dll |