rpc_ns_binding_export(3rpc)

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 environment variable, 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.

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 rpc_intro(3rpc) .)

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 rpc_intro(3rpc).

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.

Errors

The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

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.

Related Information
Functions: rpc_ep_register(3rpc)

rpc_ep_register_no_replace(3rpc)

rpc_ns_binding_unexport(3rpc)