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_syntaxAn integer value that specifies the syntax of argument entry_name.  To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX environment variable, provide the value rpc_c_ns_syntax_default. 

entry_nameSpecifies the entry name to which binding handles and object UUIDs are exported.  This can be either the global or cell-relative name. 

if_handleSpecifies 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 argument is ignored. 

binding_vecSpecifies a vector of server bindings to export. Specify the value NULL for this argument in cases where there are no binding handles to export (only object UUIDs are exported). 

object_uuid_vecIdentifies 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

statusReturns 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_okSuccess. 

rpc_s_incomplete_nameIncomplete name. 

rpc_s_invalid_bindingInvalid binding handle. 

rpc_s_invalid_if_handleInvalid interface handle. 

rpc_s_invalid_name_syntaxInvalid name syntax. 

rpc_s_name_service_unavailable
Name service unavailable.

rpc_s_no_ns_permissionNo permission for name service operation. 

rpc_s_nothing_to_exportNothing 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 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 argument does not exist, the rpc_ns_binding_export routine 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 the rpc_ns_mgmt_entry_create routine 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 the rpc_binding_from_string_binding routine to create a binding handle for making remote procedure calls to a server. 

Before calling the rpc_ns_binding_export routine 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 the rpc_server_use_protseq, rpc_server_use_protseq_if, rpc_server_use_protseq_ep, rpc_server_use_all_protseqs, or rpc_server_use_all_protseqs_if routine. 

       •Obtain a list of server bindings by calling the rpc_server_inq_bindings routine.  The vector returned from the rpc_server_inq_bindings routine becomes the binding_vec argument 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(3) 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 the rpc_ns_binding_unexport routine and a management application calls the rpc_ns_mgmt_binding_unexport routine. 

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(3) reference page. 

In addition to calling this routine, a server that called either of the routines rpc_server_use_all_protseqs or rpc_server_use_protseq must also register with the local endpoint map by calling the rpc_ep_register or rpc_ep_register_no_replace routine. 

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. 

NOTE:

For this release, the RPC naming service (rpc_ns) routines are not implemented, nor is an independent naming service provided. 

RETURN VALUES

None. 

RELATED INFORMATION

Functions: rpc_ep_register(3), rpc_ep_register_no_replace(3), rpc_ns_binding_unexport(3), rpc_ns_mgmt_binding_unexport(3), rpc_ns_mgmt_entry_create(3), rpc_server_inq_bindings(3), rpc_server_use_all_protseqs(3), rpc_server_use_all_protseqs_if(3), rpc_server_use_protseq(3), rpc_server_use_protseq_ep(3), rpc_server_use_protseq_if(3)