RpcNsBindingExport
The RpcNsBindingExport
function establishes a name-service database entry with multiple binding
handles and multiple objects for a server.
This function
is supported by both 32-bit platforms Windows NT and Windows 95.
#include <rpc.h>
RPC_STATUS RPC_ENTRY RpcNsBindingExport(
unsigned long EntryNameSyntax, |
|
unsigned char * EntryName, |
|
RPC_IF_HANDLE IfSpec, |
|
RPC_BINDING_VECTOR * BindingVec, |
|
UUID_VECTOR * ObjectUuidVec |
|
); |
|
Parameters
EntryNameSyntax
Specifies an
unsigned long value that indicates the syntax of the next argument, EntryName.
To use the
syntax specified in the registry value HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultSyntax, provide a value of RPC_C_NS_SYNTAX_DEFAULT.
EntryName
Points to the
entry name to which binding handles and object UUIDs are exported. You may not
provide a null or empty string.
To use the entry
name specified in the registry value
HKEY_LOCAL_MACHINE\Software\Microsoft\Rpc\NameService\
DefaultEntry, provide a null pointer or an empty string. In this case, the EntryNameSyntax
parameter is ignored and the run-time library uses the default syntax
EntryName.
IfSpec
Specifies a
stub-generated data structure specifying the interface to export. A null argument
value indicates there are no binding handles to export (only object UUIDs are
to be exported) and the BindingVec argument is ignored.
BindingVec
Points to
server bindings to export. A null argument value indicates there are no binding
handles to export (only object UUIDs are to be exported).
ObjectUuidVec
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
export (only binding handles are to be exported).
Remarks
The RpcNsBindingExport
routine allows a server application to publicly offer an interface in the
name-service database for use by any client application.
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 routine 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 the EntryName argument does not
exist, the RpcNsBindingExport routine 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 routine must also register with the local
endpoint-map database by calling either the RpcEpRegister or RpcEpRegisterNoReplace
routine.
A server is
not required to export its interface(s) to the name-service database. When a
server does not export, only clients that privately know of that server s
binding information can access its interface(s). 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 the RpcNsBindingExport routine, 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
routines:
RpcServerUseAllProtseqs
RpcServerUseProtseq
RpcServerUseAllProtseqsIf
RpcServerUseProtseqIf
RpcServerUseProtseqEp
Obtain a list of server
bindings by calling the RpcServerInqBindings routine.
The vector
returned from the RpcServerInqBindings routine becomes the Binding
argument for RpcNsBindingExport. To prevent a binding from being
exported, set the selected vector element to a null value.
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 routine.
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.
Return Values
Value |
Meaning |
RPC_S_OK |
Success |
RPC_S_NOTHING_TO_EXPORT |
Nothing to
export |
RPC_S_INVALID_BINDING |
Invalid
binding handle |
RPC_S_WRONG_KIND_OF_BINDING |
Wrong kind
of binding for operation |
RPC_S_INVALID_NAME_SYNTAX |
Invalid
name syntax |
RPC_S_UNSUPPORTED_NAME_SYNTAX |
Unsupported
name syntax |
RPC_S_INCOMPLETE_NAME |
Incomplete
name |
RPC_S_NO_NS_PRIVILEGE |
No
privilege for name-service operation |
RPC_S_NAME_SERVICE_UNAVAILABLE |
Name
service unavailable |
See Also