NAME
rpc_ns_binding_export - Establishes a name service database entry
with binding handles or object UUIDs for a
server
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>(
void rpc_ns_binding_export( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_handle_t if_handle,
rpc_binding_vector_t *binding_vec,
uuid_vector_t *object_uuid_vec,
unsigned32 *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of the entry_name
parameter.
To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX
logical name, provide the value rpc_c_ns_syntax_default.
entry_name
Specifies the entry name to which binding handles and object UUIDs
are exported. This can be either the global or cell-relative
name.
if_handle
Specifies a stub-generated data structure that identifies the
interface to export. Specifying the value NULL indicates there
are no binding handles to export (only object UUIDs are exported)
and the binding_vec parameter is ignored.
binding_vec
Specifies a vector of server bindings to export. Specify the value
NULL for this parameter in cases where there are no binding
handles to export (only object UUIDs are exported).
object_uuid_vec
Identifies a vector of object UUIDs offered by the server. The
server application constructs this vector. NULL indicates there
are no object UUIDs to export (only binding handles are exported).
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.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_nothing_to_export
Nothing to export.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_ns_binding_export() routine allows a server application to
publicly offer, in the name service database, an interface that any
client application can use. A server application can also use this
routine to publicly offer the object UUIDs of the application's
resources.
To export an interface, the server application calls the routine with
an interface and the server binding handles that a client can use to
access the server.
A server can export interfaces and objects in a single call to this
routine, or it can export them separately.
If the entry in the name service database specified by the entry_name
parameter does not exist, rpc_ns_binding_export() tries to create it.
In this case a server must have the correct permissions to create the
entry. Otherwise, a management application with the necessary
permissions creates the entry by calling rpc_ns_mgmt_entry_create()
before the server runs.
A server is not required to export its interfaces to the name service
database. When a server does not export any interfaces, only clients
that privately know of 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
rpc_binding_from_string_binding() to create a binding handle for
making remote procedure calls to a server.
Before calling rpc_ns_binding_export() to export interfaces (but not
to export object UUIDs), a server must do the following:
+ Register one or more protocol sequences with the local RPC
runtime by calling one of the following routines:
rpc_server_use_protseq() rpc_server_use_protseq_ep()
rpc_server_use_protseq_if() rpc_server_use_all_protseqs()
rpc_server_use_all_protseqs_if()
+ Obtain a list of server bindings by calling
rpc_server_inq_bindings(). The vector returned from
rpc_server_inq_bindings() becomes the binding_vec parameter
for this routine. To prevent a binding from being exported,
set the selected vector element to the value NULL.
(See the section on RPC data types and structures in the
rpc_intro reference page.)
If a server exports an interface to the same entry in the name
service database more than once, the second and subsequent calls
to this routine add the binding information and object UUIDs only
if they differ from the ones 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 rpc_ns_binding_unexport() and
a management application calls rpc_ns_mgmt_binding_unexport().
For an explanation of how a server can establish a client/server
relationship without using the name service database, see the
explanation of a string binding in the rpc_intro reference page.
In addition to calling this routine, a server that called either
rpc_server_use_all_protseqs() or rpc_server_use_protseq() must also
register with the local endpoint map by calling rpc_ep_register() or
rpc_ep_register_no_replace().
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target name service entry). If the entry does not exist,
you also need insert permission to the parent directory.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_unexport
rpc_ns_mgmt_binding_unexport
rpc_ns_mgmt_entry_create
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