NAME
rpc_intro - Introduction to the DCE RPC API runtime
DESCRIPTION
This introduction gives general information about the DCE RPC
Application Programming Interface (API) and an overview of the
following parts of the DCE RPC API runtime:
+ Runtime services
+ Environment variables
+ Data types and structures
+ Permissions required
+ Frequently used routine arguments
1 – General Information
The following subsections contain topics, beyond those directly
related to the RPC API, that application programmers need to know.
IDL-to-C Mappings
The Interface Definition Language (IDL) compiler converts an
interface definition into output files. The rpc_intro reference
page in the OSF DCE Command Reference contains a summary of the
idl command, which invokes the IDL compiler.
Additional information about the IDL compiler appears in the
following table, which shows the IDL base types and the IDL-to-C
mappings. The following table lists the IDL base data type
specifiers. Where applicable, the table shows the size of the
corresponding transmittable type and the type macro emitted by
the IDL compiler for resulting declarations.
Base Data Type Specifiers - rpc_intro
___________________________________________________________
Specifier Type Macro
(sign) (size) (type) Size Emitted by idl
___________________________________________________________
small int 8 bits idl_small_int
short int 16 bits idl_short_int
long int 32 bits idl_long_int
hyper int 64 bits idl_hyper_int
unsigned small int 8 bits idl_usmall_int
unsigned short int 16 bits idl_ushort_int
unsigned long int 32 bits idl_ulong_int
unsigned hyper int 64 bits idl_uhyper_int
float 32 bits idl_short_float
double 64 bits idl_long_float
char 8 bits idl_char
boolean 8 bits idl_boolean
byte 8 bits idl_byte
void - idl_void_p_t
handle_t - -
Note that you can use the idl_ macros in the code you write for an
application to ensure that your type declarations are consistent
with those in the stubs, even when the application is ported to
another platform. The idl_ macros are especially useful when
passing constant values to RPC calls. For maximum portability,
all constants passed to RPC calls declared in your network
interfaces should be cast to the appropriate type because the size
of integer constants (like the size of the int data type) is
unspecified in the C language. The idl_ macros are defined in
SYS$COMMON:[DCE$LIBRARY]IDLBASE.H, which is included by header
files that the IDL compiler generates.
Management Commands for Programmers
In addition to the idl command for programmers, DCE RPC provides
two management commands for the RPC control program and the DCE
Host daemon, as follows:
+ The rpccp control program accesses RPCCP, the RPC control
program. This program provides a set of commands for
accessing the operations of the RPC Name Service Interface
(NSI operations). RPCCP also supports showing the elements
of the local endpoint map and removing elements from it.
You can manage the name service with RPCCP commands or with DCE
RPC runtime routines. For example, suppose you want to obtain
the members of a group. You can give the show group command to
RPCCP or you can write an application program that calls the
following DCE RPC runtime routines:
- rpc_ns_group_mbr_inq_begin()
- rpc_ns_group_mbr_inq_next()
- rpc_ns_group_mbr_inq_done()
+ The dced command starts the DCE Host daemon. The daemon
maintains the local endpoint map for RPC servers and looks
up endpoints for RPC clients.
See the OSF DCE Administration Reference for more information about
these two management commands.
2 – Overview of DCE RPC Runtime Services
The RPC runtime services consist of RPC routines that perform a
variety of operations.
Note that the RPC API is thread safe and synchronous cancel safe (in
the context of POSIX threads). However, the RPC API is not
asynchronous cancel safe. For more information about threads and
their cancellation, see the OSF DCE Application Development Guide -
Core Components.
The rest of this overview consists of the following items:
+ An explanation of abbreviations in the names of the RPC runtime
routines
+ An alphabetical list of DCE RPC runtime routines. With each
routine name is its description and the type of application
program that most likely calls the routine.
An alphabetical list of abbreviations in the names of the DCE RPC
routines follows. The list can help you remember the names more
easily. For example, consider the routine name
rpc_mgmt_ep_elt_inq_begin(). Use the next list to expand the name
to "RPC management endpoint element inquiry begin", which summarizes
the description "Creates an inquiry context for viewing the elements
in a local or remote endpoint map. (Management)."
auth - authentication, authorization
com - communications
cs - character/code set interoperability
dce - distributed computing environment
dflt - default
elt - element
ep - endpoint
exp - expiration
fn - function
id - identifier
idl_es - IDL encoding services
if - interface
inq - inquiry
mbr - member
mgmt - management
ns - name service
protseq - protocol sequence
rgy - DCE character and code set registry
rpc - remote procedure call
stats - statistics
An alphabetical list of the RPC runtime routines follows. With each
routine name is its description and the type of application program
that most likely calls the routine.
cs_byte_from_netcs()
Converts international character data from a network code set
to a local code set. (Client, server).
cs_byte_local_size()
Calculates the necessary buffer size for a code set conversion
from a network code set to a local code set. (Client, server).
cs_byte_net_size()
Calculates the necessary buffer size for a code set conversion
from a local code set to a network code set. (Client, server).
cs_byte_to_netcs()
Converts international character data from a local code set to a
network code set. (Client, server).
dce_cs_loc_to_rgy()
Maps a local name for a code set to a code set value in the code
set registry. (Client, server).
dce_cs_rgy_to_loc()
Maps a code set value in the code set registry to a the local
name for a code set. (Client, server).
idl_es_decode_buffer()
Returns a buffer decoding handle. (Client, server).
idl_es_decode_incremental()
Returns an incremental decoding handle. (Client, server).
idl_es_encode_dyn_buffer()
Returns a dynamic buffer encoding handle. (Client, server).
idl_es_encode_fixed_buffer()
Returns a fixed buffer encoding handle. (Client, server).
idl_es_encode_incremental()
Returns an incremental encoding handle. (Client, server).
idl_es_handle_free()
Frees an IDL encoding services handle. (Client, server).
idl_es_inq_encoding_id()
Identifies an application encoding operation. (Client, server).
rpc_binding_copy()
Returns a copy of a binding handle. (Client or server).
rpc_binding_free()
Releases binding handle resources. (Client or server).
rpc_binding_from_string_binding()
Returns a binding handle from a string representation of a
binding handle. (Client or management).
rpc_binding_inq_auth_client()
Returns authentication and authorization information from the
binding handle for an authenticated client. (Server).
rpc_binding_inq_auth_info()
Returns authentication and authorization information from a
server binding handle. (Client).
rpc_binding_inq_object()
Returns the object UUID from a binding handle. (Client or server).
rpc_binding_reset()
Resets a server binding handle so the host remains specified,
but the server instance on that host is unspecified. (Client
or management).
rpc_binding_server_from_client()
Converts a client binding handle to a server binding handle.
(Server).
rpc_binding_set_auth_info()
Sets authentication and authorization information into a server
binding handle. (Client).
rpc_binding_set_object()
Sets the object UUID value into a server binding handle. (Client).
rpc_binding_to_string_binding()
Returns a string representation of a binding handle. (Client,
server, or management).
rpc_binding_vector_free()
Frees the memory used to store a vector and binding handles.
(Client or server).
rpc_cs_binding_set_tags()
Places code set tags into a server binding handle. (Client).
rpc_cs_char_set_compat_check()
Evaluates character set compatibility between a client and a
server. (Client).
rpc_cs_eval_with_universal()
Evaluates a server's supported character sets and code sets during
the server binding selection process. (Client).
rpc_cs_eval_without_universal()
Evaluates a server's supported character sets and code sets during
the server binding selection process. (Client).
rpc_cs_get_tags()
Retrieves code set tags from a binding handle. (Client, server).
rpc_ep_register()
Adds to, or replaces, server address information in the local
endpoint map. (Server).
rpc_ep_register_no_replace()
Adds to server address information in the local endpoint map.
(Server).
rpc_ep_resolve_binding()
Resolves a partially bound server binding handle into a fully
bound server binding handle. (Client or management).
rpc_ep_unregister()
Removes server address information from the local endpoint map.
(Server).
rpc_if_id_vector_free()
Frees a vector and the interface identifier structures it
contains. (Client, server, or management).
rpc_if_inq_id()
Returns the interface identifier for an interface specification.
(Client or server).
rpc_mgmt_ep_elt_inq_begin()
Creates an inquiry context for viewing the elements in a local
or remote endpoint map. (Management).
rpc_mgmt_ep_elt_inq_done()
Deletes the inquiry context for viewing the elements in a local
or remote endpoint map. (Management).
rpc_mgmt_ep_elt_inq_next()
Returns one element at a time from a local or remote endpoint
map. (Management).
rpc_mgmt_ep_unregister()
Removes server address information from a local or remote
endpoint map. (Management).
rpc_mgmt_inq_com_timeout()
Returns the communications time-out value in a binding handle.
(Client).
rpc_mgmt_inq_dflt_protect_level()
Returns the default protection level for an authentication
service. (Client or server).
rpc_mgmt_inq_if_ids()
Returns a vector of interface identifiers of interfaces a server
offers. (Client, server, or management).
rpc_mgmt_inq_server_princ_name()
Returns a server's principal name. (Client, server, or
management).
rpc_mgmt_inq_stats()
Returns RPC runtime statistics. (Client, server, or management).
rpc_mgmt_is_server_listening()
Tells whether a server is listening for remote procedure calls.
(Client, server, or management).
rpc_mgmt_set_authorization_fn()
Establishes an authorization function for processing remote calls
to a server's management routines. (Server).
rpc_mgmt_set_cancel_timeout()
Sets the lower bound on the time to wait before timing out after
forwarding a cancel. (Client).
rpc_mgmt_set_com_timeout()
Sets the communications time-out value in a binding handle.
(Client).
rpc_mgmt_set_server_stack_size()
Specifies the stack size for each server thread. (Server).
rpc_mgmt_stats_vector_free()
Frees a statistics vector. (Client, server, or management).
rpc_mgmt_stop_server_listening()
Tells a server to stop listening for remote procedure calls.
(Client, server, or management).
rpc_network_inq_protseqs()
Returns all protocol sequences supported by both the RPC runtime
and the operating system. (Client or server).
rpc_network_is_protseq_valid()
Tells whether the specified protocol sequence is supported by
both the RPC runtime and the operating system. (Client or
server).
rpc_ns_binding_export()
Establishes a name service database entry with binding handles
or object UUIDs for a server. (Server).
rpc_ns_binding_import_begin()
Creates an import context for an interface and an object in the
name service database. (Client).
rpc_ns_binding_import_done()
Deletes the import context for searching the name service
database. (Client).
rpc_ns_binding_import_next()
Returns a binding handle of a compatible server (if found) from
the name service database. (Client).
rpc_ns_binding_inq_entry_name()
Returns the name of an entry in the name service database from
which the server binding handle came. (Client).
rpc_ns_binding_lookup_begin()
Creates a lookup context for an interface and an object in the
name service database. (Client).
rpc_ns_binding_lookup_done()
Deletes the lookup context for searching the name service
database. (Client).
rpc_ns_binding_lookup_next()
Returns a list of binding handles of one or more compatible
servers (if found) from the name service database. (Client).
rpc_ns_binding_select()
Returns a binding handle from a list of compatible server binding
handles. (Client).
rpc_ns_binding_unexport()
Removes the binding handles for an interface, or object UUIDs,
from an entry in the name service database. (Server).
rpc_ns_entry_expand_name()
Expands the name of a name service entry. (Client, server, or
management).
rpc_ns_entry_object_inq_begin()
Creates an inquiry context for viewing the objects of an entry
in the name service database. (Client, server, or management).
rpc_ns_entry_object_inq_done()
Deletes the inquiry context for viewing the objects of an entry
in the name service database. (Client, server, or management).
rpc_ns_entry_object_inq_next()
Returns one object at a time from an entry in the name service
database. (Client, server, or management).
rpc_ns_group_delete()
Deletes a group attribute. (Client, server, or management).
rpc_ns_group_mbr_add()
Adds an entry name to a group; if necessary, creates the entry.
(Client, server, or management).
rpc_ns_group_mbr_inq_begin()
Creates an inquiry context for viewing group members. (Client,
server, or management).
rpc_ns_group_mbr_inq_done()
Deletes the inquiry context for a group. (Client, server, or
management).
rpc_ns_group_mbr_inq_next()
Returns one member name at a time from a group. (Client, server,
or management).
rpc_ns_group_mbr_remove()
Removes an entry name from a group. (Client, server, or
management).
rpc_ns_import_ctx_add_eval()
Adds an evaluation routine to an import context. (Client).
rpc_ns_mgmt_binding_unexport()
Removes multiple binding handles, or object UUIDs, from an entry
in the name service database. (Management).
rpc_ns_mgmt_entry_create()
Creates an entry in the name service database. (Management).
rpc_ns_mgmt_entry_delete()
Deletes an entry from the name service database. (Management).
rpc_ns_mgmt_entry_inq_if_ids()
Returns the list of interfaces exported to an entry in the name
service database. (Client, server, or management).
rpc_ns_mgmt_free_codesets()
Frees a code sets array that has been allocated in memory.
(Client).
rpc_ns_mgmt_handle_set_exp_age()
Sets a handle's expiration age for local copies of name service
data. (Client, server, or management).
rpc_ns_mgmt_inq_exp_age()
Returns the application's global expiration age for local copies
of name service data. (Client, server, or management).
rpc_ns_mgmt_read_codesets()
Reads the code sets attribute associated with an RPC server
entry in the name service database. (Client).
rpc_ns_mgmt_remove_attribute()
Removes an attribute from an RPC server entry in the name
service database. (Server, management).
rpc_ns_mgmt_set_attribute()
Adds an attribute to an RPC server entry in the name service
database. (Server, management).
rpc_ns_mgmt_set_exp_age()
Modifies the application's global expiration age for local copies
of name service data. (Client, server, or management).
rpc_ns_profile_delete()
Deletes a profile attribute. (Client, server, or management).
rpc_ns_profile_elt_add()
Adds an element to a profile. If necessary, creates the entry.
(Client, server, or management).
rpc_ns_profile_elt_inq_begin()
Creates an inquiry context for viewing the elements in a profile.
(Client, server, or management).
rpc_ns_profile_elt_inq_done()
Deletes the inquiry context for a profile. (Client, server, or
management).
rpc_ns_profile_elt_inq_next()
Returns one element at a time from a profile. (Client, server,
or management).
rpc_ns_profile_elt_remove()
Removes an element from a profile. (Client, server, or
management).
rpc_object_inq_type()
Returns the type of an object. (Server).
rpc_object_set_inq_fn()
Registers an object inquiry function. (Server).
rpc_object_set_type()
Assigns the type of an object. (Server).
rpc_protseq_vector_free()
Frees the memory used by a vector and its protocol sequences.
(Client or server).
rpc_rgy_get_codesets()
Gets supported code sets information from the local host.
(Client, server).
rpc_rgy_get_max_bytes()
Gets the maximum number of bytes that a code set uses to encode
one character. (Client, server).
rpc_server_inq_bindings()
Returns binding handles for communication with a server.
(Server).
rpc_server_inq_if()
Returns the manager entry point vector registered for an
interface. (Server).
rpc_server_listen()
Tells the RPC runtime to listen for remote procedure calls.
(Server).
rpc_server_register_auth_info()
Registers authentication information with the RPC runtime.
(Server).
rpc_server_register_if()
Registers an interface with the RPC runtime. (Server).
rpc_server_unregister_if()
Unregisters an interface from the RPC runtime. (Server).
rpc_server_use_all_protseqs()
Tells the RPC runtime to use all supported protocol sequences
for receiving remote procedure calls. (Server).
rpc_set_local_float_drep()
Sets the float type in the runtime to the one with which
the application is being compiled.
rpc_server_use_all_protseqs_if()
Tells the RPC runtime to use all the protocol sequences and
endpoints specified in the interface specification for receiving
remote procedure calls. (Server).
rpc_server_use_protseq()
Tells the RPC runtime to use the specified protocol sequence
for receiving remote procedure calls. (Server).
rpc_server_use_protseq_ep()
Tells the RPC runtime to use the specified protocol sequence
combined with the specified endpoint for receiving remote
procedure calls. (Server).
rpc_server_use_protseq_if()
Tells the RPC runtime to use the specified protocol sequence
combined with the endpoints in the interface specification for
receiving remote procedure calls. (Server).
rpc_sm_allocate()
Allocates memory within the RPC stub memory management scheme.
(Usually server, possibly client).
rpc_sm_client_free()
Frees memory allocated by the current memory allocation and
freeing mechanism used by the client stubs. (Client).
rpc_sm_destroy_client_context()
Reclaims the client memory resources for a context handle, and
sets the context handle to NULL. (Client).
rpc_sm_disable_allocate()
Releases resources and allocated memory within the RPC stub
memory management scheme. (Client).
rpc_sm_enable_allocate()
Enables the stub memory management environment. (Client).
rpc_sm_free()
Frees memory allocated by the rpc_sm_allocate() routine.
(Usually server, possibly client).
rpc_sm_get_thread_handle()
Gets a thread handle for the stub memory management environment.
(Usually server, possibly client).
rpc_sm_set_client_alloc_free()
Sets the memory allocation and freeing mechanism used by the
client stubs. (Client).
rpc_sm_set_thread_handle()
Sets a thread handle for the stub memory management environment.
(Usually server, possibly client).
rpc_sm_swap_client_alloc_free()
Exchanges the current memory allocation and freeing
mechanism used by the client stubs with one supplied by
the client. (Client).
rpc_string_binding_compose()
Combines the components of a string binding into a string
binding. (Client or server).
rpc_string_binding_parse()
Returns, as separate strings, the components of a string
binding. (Client or server).
rpc_string_free()
Frees a character string allocated by the runtime. (Client,
server, or management).
uuid_compare()
Compares two UUIDs and determines their order. (Client,
server, or management).
uuid_create()
Creates a new UUID. (Client, server, or management).
uuid_create_nil()
Creates a nil UUID. (Client, server, or management).
uuid_equal()
Determines if two UUIDs are equal. (Client, server, or
management).
uuid_from_string()
Converts a string UUID to its binary representation. (Client,
server, or management).
uuid_hash()
Creates a hash value for a UUID. (Client, server, or
management).
uuid_is_nil()
Determines if a UUID is nil. (Client, server, or management).
uuid_to_string()
Converts a UUID from a binary representation to a string
representation. (Client, server, or management).
wchar_t_from_netcs()
Converts international character data from a network code set
to a local code set. (Client, server).
wchar_t_local_size()
Calculates the necessary buffer size for a code set conversion
from a network code set to a local code set. (Client, server).
wchar_t_net_size()
Calculates the necessary buffer size for a code set conversion
from a local code set to a network code set. (Client, server).
wchar_t_to_netcs()
Converts international character data from a local code set to
a net work code set. (Client, server).
3 – Logical Names
The RPC Name Service Interface (NSI) routines uses the following
logical names:
+ RPC_DEFAULT_ENTRY
Designates the default entry in the name service database that
the import and lookup routines use as the starting point to
search for binding information for a compatible server.
Normally, the starting entry is a profile.
An application that uses a default entry name must define this
logical name. The RPC runtime does not provide a default.
For example, suppose that a client application needs to search
the name service database for a server binding handle. The
application can use the rpc_ns_binding_import_begin() routine
as part of the search. If so, the application must specify, to
the routine's entry_name parameter, the name of the entry in the
name service database at which to begin the search. If the
search is to begin at the entry that the RPC_DEFAULT_ENTRY
logical name specifies, then the application must specify the
value NULL to parameter entry_name in
rpc_ns_binding_import_begin().
+ RPC_DEFAULT_ENTRY_SYNTAX
Specifies the syntax of the name provided in the
RPC_DEFAULT_ENTRY logical name. In addition, provides the
syntax for those RPC NSI routines that allow a default value
for the name syntax argument. If the RPC_DEFAULT_ENTRY_SYNTAX
logical name is not defined, the RPC runtime uses the
rpc_c_ns_syntax_dce name syntax. (For the valid name syntaxes
in this reference page and for the valid syntax values, see the
table in the description of the frequently used routine argument
name_syntax, which appears later in this reference page.)
Optionally, each application defines either or both of the first two
logical names. The application can change the value of either one,
or both, at any time during runtime.
4 – RPC Data Types and Structures
The following subsections contain the data types and structures used by client, server, and management application programs. Much of the information in this section is derived from the Application Development Guide. You may want to refer to this book as you read this section. For example, this section contains a brief description of a binding handle. The RPC section of the Application Development Guide explains binding handles in detail. It also explains concepts related to binding handles, such as binding information and string bindings.
4.1 – Binding Handle
A binding handle is a pointer-size opaque variable containing
information the RPC runtime uses to manage binding information.
The RPC runtime uses binding information to establish a client/
server relationship that allows the execution of remote procedure
calls.
Based on the context where it is created, a binding handle is
considered a server binding handle or a client binding handle.
A server binding handle is a reference to the binding information
necessary for a client to establish a relationship with a specific
server. Many RPC API runtime routines return a server binding
handle that you can use to make a remote procedure call.
A server binding handle refers to several components of binding
information. One is the network address of a server's host system.
Each server instance has one or more transport addresses
(endpoints). A well-known endpoint is a stable address on the host,
while a dynamic endpoint is an address that the RPC runtime requests
for the server. Some transport protocols provide fewer well-known
endpoints than dynamic endpoints.
If binding information contains an endpoint, the corresponding
binding handle is a fully bound binding handle. If the information
lacks an endpoint, the binding handle is a partially bound binding
handle.
The RPC runtime creates and provides a client binding handle to a
called remote procedure as the handle_t parameter. The client
binding handle contains information about the calling client. A
client binding handle cannot be used to make a remote procedure
call. A server uses the client binding handle. The
rpc_binding_server_from_client() routine converts a client binding
handle to a server binding handle. You can use the resulting server
binding handle to make a remote procedure call.
For an explanation of making a remote procedure call with
a partially bound binding handle, see the OSF DCE Application
Development Guide - Core Components. For an explanation of failures
associated with such a call, see the explanation of status code
rpc_s_wrong_boot_time in the OSF DCE Problem Determination Guide.
Binding information can contain an object UUID. The default object
UUID associated with a binding handle is a nil UUID. Clients can
obtain a non-nil UUID in various ways, such as from a string
representation of binding information (a string binding), or by
importing it.
The following table contains the RPC runtime routines that operate
on binding handles. The table also specifies the type of binding
handle, client or server, allowed.
Client and Server Binding Handles
__________________________________________________________________
Routine Input Argument Output Argument
__________________________________________________________________
rpc_binding_copy() Server Server
rpc_binding_free() Server None
rpc_binding_from_string_binding() None Server
rpc_binding_inq_auth_client() Client None
rpc_binding_inq_auth_info() Server None
rpc_binding_inq_object() Server or client None
rpc_binding_reset() Server None
rpc_binding_server_from_client() Client Server
rpc_binding_set_auth_info() Server None
rpc_binding_set_object() Server None
rpc_binding_to_string_binding() Server or client None
rpc_binding_vector_free() Server None
rpc_ns_binding_export() Server None
rpc_ns_binding_import_next() None Server
rpc_ns_binding_inq_entry_name() Server None
rpc_ns_binding_lookup_next() None Server
rpc_ns_binding_select() Server Server
rpc_server_inq_bindings() None Server
If the input argument type is only a client or only a server, the
routines return the status code rpc_s_wrong_kind_of_binding when an
application provides the incorrect binding handle type.
An application can share a single binding handle across multiple
threads of execution. The RPC runtime, instead of the application,
manages binding handle concurrency control across concurrent remote
procedure calls that use a single binding handle. However, the
client application has responsibility for binding handle concurrency
control for operations that read or modify a binding handle. The
related routines are as follows:
+ rpc_binding_free()
+ rpc_binding_reset()
+ rpc_binding_set_auth_info()
+ rpc_binding_set_object()
+ rpc_ep_resolve_binding()
+ rpc_mgmt_set_com_timeout()
For example, suppose an application shares a binding handle across
two threads of execution and it resets the binding handle endpoint
in one of the threads (by calling rpc_binding_reset()). The binding
handle in the other thread is then also reset. Similarly, freeing
the binding handle in one thread (by calling rpc_binding_free())
frees the binding handle in the other thread.
If you do not want this effect, your application can create a copy
of a binding handle by calling rpc_binding_copy(). An operation on
one binding handle then has no effect on the second binding handle.
Clients and servers can access and set object UUIDs using the
rpc_binding_inq_object() and rpc_binding_set_object() routines.
Routines requiring a binding handle as an argument show a data type
of rpc_binding_handle_t. Binding handle arguments are passed by
value.
4.2 – Binding Vector
The binding vector data structure contains a list of binding handles
over which a server application can receive remote procedure calls.
The binding vector contains a count member (count), followed by an
array of binding handle (binding_h) elements.
The C language representation of a binding vector is as follows:
typedef struct {
unsigned32 count;
rpc_binding_handle_t binding_h[1];
} rpc_binding_vector_t;
The RPC runtime creates binding handles when a server application
registers protocol sequences. To obtain a binding vector, a server
application calls the rpc_server_inq_bindings() routine.
A client application obtains a binding vector of compatible servers
from the name service database by calling
rpc_ns_binding_lookup_next(). In both routines, the RPC runtime
allocates memory for the binding vector. An application calls the
rpc_binding_vector_free() routine to free the binding vector.
An application, when it is finished with an individual binding
handle in a binding vector, frees the binding handle by calling
rpc_binding_free(). This routine also sets the corresponding
pointer in the binding vector to NULL.
Note that you should not decrement the count field in a binding
vector structure when you call the rpc_binding_free() routine to
free an individual binding handle.
The following routines require a binding vector and show an argument
data type of rpc_binding_vector_t:
+ rpc_binding_vector_free()
+ rpc_ep_register()
+ rpc_ep_register_no_replace()
+ rpc_ep_unregister()
+ rpc_ns_binding_export()
+ rpc_ns_binding_lookup_next()
+ rpc_ns_binding_select()
+ rpc_server_inq_bindings()
4.3 – Boolean
Routines that require a Boolean-valued argument or return a Boolean value show a data type of boolean32. DCE RPC provides the integer constants TRUE (1) and FALSE (0) for use as Boolean values.
4.4 – Code Set
A code set is a mapping of the members of a character set to
specific numeric code values. Different code sets use different
numeric code values to represent the same character. In general,
operating systems use string names to refer to the code sets that
the system supports. It is common for different operating systems
to use different string names to refer to the same code set.
Distributed applications that run in a network of heterogeneous
operating systems need to be able to identify the character sets
and code sets that client and server machines are using to avoid
losing data during communications between each other. DCE RPC
supports transparent automatic conversion for characters that are
members of the DCE Portable Character Set (DCE PCS) and which are
encoded in the ASCII and U.S. EBCDIC code sets. The RPC runtime
automatically converts DCE PCS characters encoded in ASCII or U.S.
EBCDIC, if necessary, when they are passed over the network between
client and server.
DCE RPC applications that need to transfer character data that is
outside the DCE PCS character set and ASCII and U.S. EBCDIC
encodings (international characters) can use special IDL constructs
and a set of DCE RPC routines to set up their applications so that
they can pass this "international" character data with minimal or no
loss between client and server applications. An example of such an
application would be one that used European, Chinese, or Japanese
characters mapped to EUC, Big5, or SJIS encodings. Together, the
IDL constructs and the DCE RPC routines provide a method of
automatic code set conversion for applications that transfer
international character data in heterogeneous code set environments.
DCE provides a mechanism to uniquely identify a code set; this
mechanism is the code set registry. The code set registry assigns
a unique identifier to each character set and code set. Because
the registry provides code set identifiers that are consistent
across a network of heterogeneous operating systems, it provides a
method for clients and servers in a heterogeneous environment to
use to identify code sets without having to rely on operating
system specific string names.
The code set data structure contains a 32-bit hexadecimal value
(c_set) that uniquely identifies the code set followed by a 16-bit
decimal value (c_max_bytes) that indicates the maximum number of
bytes this code set uses to encode one character in this code set.
The value for c_set is one of the registered values in the code set
registry.
The following routines require a code set value:
+ cs_byte_from_netcs()
+ cs_byte_local_size()
+ cs_byte_net_size()
+ cs_byte_to_netcs()
+ dce_cs_loc_to_rgy()
+ dce_cs_rgy_to_loc()
+ rpc_cs_get_tags()
+ rpc_cs_binding_set_tags()
+ rpc_rgy_get_max_bytes()
+ wchar_t_from_netcs()
+ wchar_t_local_size()
+ wchar_t_net_size()
+ wchar_t_to_netcs()
In these routines, the code set value shows a data type of
unsigned32. The RPC stub buffer sizing routines *Lnet_size() and
*_local_size use the value of c_max_bytes to calculate the size of
a buffer for code set conversion.
The C language representation of a code set structure is as follows:
typedef struct {
long c_set;
short c_max_bytes;
} rpc_cs_c_set_t;
The code set data structure is a member of the code sets array.
4.4.1 – Code Sets Array
The code sets array contains the list of the code sets that a
client or server supports. The structure consists of a version
number member (version), followed by a count member (count),
followed by an array of code set data structures (rpc_cs_c_set_t).
This array is declared to be a conformant array so that its size
will be determined at runtime. The count member indicates the
number of code sets contained in the array. The first element in
the code sets array represents the client or server process's
local code set.
The second element through the nth element represents one or more
intermediate code sets that the process can use to transmit
character data over the network. Client or server processes can
convert into an intermediate code set when their host system does
not provide a converter for the other's local code set but does
provide a converter for the intermediate code set.
DCE RPC routines for character/code sets compatibility evaluation
and code set conversion support one intermediate code set, which
is the ISO 10646 Universal character/code set. Consequently, DCE
requires host systems running applications that transfer
international characters to provide converters for this code set.
System administrators for machines in internationalized DCE cells
(that is, cells of machines that run applications that use the DCE
character/code sets compatibility evaluation and conversion
functionality) and who want to use other intermediate code sets
can run the csrc utility and specify that their intermediate code
set(s) be used in preference to ISO 10646.
The remaining elements in the array represent other code sets that
the process's host supports (that is, code sets for which the
system provides converters).
The C language representation of a code set structure is as
follows:
typedef struct rpc_codeset_mgmt_t {
unsigned32 version;
long count;
[size_is(count)] rpc_cs_c_set_t codesets[];
} rpc_codeset_mgmt_t, *rpc_codeset_mgmt_p_t;
Client and server applications and DCE RPC routines for automatic
code set conversion obtain a code sets array by calling the
routine rpc_rgy_get_codesets(). Server applications user the code
sets array as input to the rpc_ns_mgmt_set_attribute() routine,
which registers their supported code sets in the name service
database. Client applications look up a server's supported code
sets in the name service database by calling the routine
rpc_ns_mgmt_read_codesets() and then use their code sets array to
evaluate their supported code sets against the code sets that the
server supports.
The following DCE RPC routines require a code sets array and show
an argument data type of rpc_codeset_mgmt_t:
+ rpc_ns_mgmt_read_codesets()
+ rpc_rgy_get_codesets()
Server applications that use the routine
rpc_ns_mgmt_set_attribute() to register their supported code sets
in the name service database also specify the code sets array, but
show an argument data type of void.
4.4.2 – Conversion Type
The conversion type data structure is an enumerated type that RPC
stub buffer sizing routines return to indicate whether character
data conversion is necessary and whether or not existing storage
is sufficient for the stub to store the results of the conversion.
The conversion type can be one of the following values:
idl_cs_no_convert
No code set conversion is required.
idl_cs_in_place_convert
Code set conversion can be performed in a single
storage area.
idl_cs_new_buffer_convert
The converted data must be written to a new
storage area.
The C language representation of a conversion type structure is as
follows:
typedef enum {
idl_cs_no_convert,
idl_cs_in_place_convert,
idl_cs_new_buffer_convert,
} idl_cs_convert_t;
4.5 – Endpoint Map Inquiry Handle
An endpoint map inquiry handle is a pointer-size opaque variable
containing information the RPC runtime uses to access the elements
in a local or remote endpoint map. The description of the
rpc_ep_register() routine lists the contents of an element.
The following routines require an endpoint map inquiry handle and
show an argument data type of rpc_ep_inq_handle_t:
+ rpc_mgmt_ep_elt_inq_begin()
+ rpc_mgmt_ep_elt_inq_done()
+ rpc_mgmt_ep_elt_inq_next()
4.6 – Global Name
The Name Service Interface (NSI) uses global names for the names of name service entries. A global name includes both a cell name and a cell-relative name composed of a directory pathname and a leaf name. For a description of global names, see the OSF DCE Administration Guide. The cell name is assigned to a cell root at its creation. When you specify only a cell-relative name to an NSI operation, the NSI automatically expands the name into a global name by inserting the local cell name. Thus, the name of a member in a group or in a profile element is always stored as a global name. When returning the name of a name service entry or a member, NSI operations return global names. For example, even when you specify a cell-relative name as the member_name parameter to routine rpc_ns_group_mbr_add(), when you read that group member (by calling rpc_ns_group_mbr_inq_next()), you will receive the corresponding global name.
4.7 – IDL Encoding Service Handle
An IDL encoding service handle is a pointer-size opaque variable
that points to functions that control how data encoding or decoding
is performed. The following routines return an IDL encoding service
handle and show an argument data type of idl_es_handle_t:
+ idl_es_encode_incremental()
+ idl_es_decode_buffer()
+ idl_es_decode_incremental()
+ idl_es_encode_dyn_buffer()
+ idl_es_encode_fixed_buffer()
The idl_es_handle_free() and idl_es_inq_encoding_id() routines
require an IDL encoding service handle.
Note that in order to use the IDL encoding services, you must
include a header file that has been generated for an application
that has used the encode and decode ACF attributes on one or more
of its operations.
4.8 – Interface Handle and Specification
An interface handle is a pointer-size opaque variable containing
information the RPC runtime uses to access the interface
specification data structure.
The DCE IDL compiler automatically creates an interface
specification data structure from each IDL file and creates
a global variable of type rpc_if_handle_t for the interface
specification.
The DCE IDL compiler places an interface handle declaration in
the generated interface-name.h file. The compiler generates this
include file for each interface.
Routines requiring the interface handle as an argument show a
data type of rpc_if_handle_t.
The form of each interface handle name is as follows:
+ For the client:
if-name_vmajor-version_minor-version_c_ifspec
+ For the server:
if-name_vmajor-version_minor-version_s_ifspec
where
+ The if-name variable is the interface identifier specified
in the IDL file.
+ The major-version variable is the interface's major-version
number specified in the IDL file.
+ The minor-version variable is the interface's minor-version
number specified in the IDL file.
An example is notes_v1_2_c_ifspec
The maximum combined length of the interface identifier and
interface version number is 19 characters.
Since the major-version and minor-version numbers must each be at
least 1 character, the interface name can be no more than 17
characters. This limits the interface handle name to 31 or fewer
characters.
No concurrency control is required for interface handles.
The following routines require an interface handle and show an
argument data type of rpc_if_handle_t:
+ rpc_ep_register()
+ rpc_ep_register_no_replace()
+ rpc_ep_resolve_binding()
+ rpc_ep_unregister()
+ rpc_if_inq_id()
+ rpc_ns_binding_export()
+ rpc_ns_binding_import_begin()
+ rpc_ns_binding_lookup_begin()
+ rpc_ns_binding_unexport()
+ rpc_server_inq_if()
+ rpc_server_register_if()
+ rpc_server_unregister_if()
+ rpc_server_use_all_protseqs_if()
+ rpc_server_use_protseq_if()
4.9 – Interface Identifier
The interface identifier (id) data structure contains the interface
UUID and major-version and minor-version numbers of an interface.
The interface identifier is a subset of the data contained in the
interface specification structure.
The C language representation of an interface identifier structure
is as follows:
typedef struct {
uuid_t uuid;
unsigned16 vers_major;
unsigned16 vers_minor;
} rpc_if_id_t;
Routines that require an interface identifier structure show a data
type of rpc_if_id_t. In those routines, the application is
responsible for providing memory for the structure.
The rpc_if_inq_id() routine returns the interface identifier from an
interface specification. The following routines require an
interface identifier:
+ rpc_mgmt_ep_elt_inq_begin()
+ rpc_mgmt_ep_elt_inq_next()
+ rpc_mgmt_ep_unregister()
+ rpc_ns_mgmt_binding_unexport()
+ rpc_ns_profile_elt_add()
+ rpc_ns_profile_elt_inq_begin()
+ rpc_ns_profile_elt_inq_next()
+ rpc_ns_profile_elt_remove()
4.10 – Interface Identifier Vector
The interface identifier (id) vector data structure contains a list
of interfaces offered by a server. The interface identifier vector
contains a count member (count), followed by an array of pointers to
interface identifiers (rpc_if_id_t).
The C language representation of an interface identifier vector is
as follows:
typedef struct {
unsigned32 count;
rpc_if_id_t *if_id[1];
} rpc_if_id_vector_t;
The interface identifier vector is a read-only vector. To obtain a
vector of the interface identifiers registered by a server with the
RPC runtime, an application calls the rpc_mgmt_inq_if_ids() routine.
To obtain a vector of the interface identifiers exported by a server
to a name service database, an application calls the
rpc_ns_mgmt_entry_inq_if_ids() routine.
The RPC runtime allocates memory for the interface identifier
vector. The application calls the rpc_if_id_vector_free() routine
to free the interface identifier vector.
4.11 – Manager Entry Point Vector
The manager Entry Point Vector (EPV) is an array of pointers to
remote procedures.
The DCE IDL compiler automatically generates a manager EPV data
type, into the header file generated by the IDL compiler, for use
in constructing manager EPVs. The data type is named as follows:
if-name_vmajor-version_minor-version_epv_t
where
+ The if-name variable is the interface identifier specified
in the IDL file.
+ The major-version variable is the interface's major-version
number specified in the IDL file.
+ The minor-version variable is the interface's minor-version
number specified in the IDL file.
By default, the DCE IDL compiler automatically creates and
initializes a manager EPV. DCE IDL creates this EPV assuming
that a manager routine of the same name exists for each
procedure in the interface (as specified in the IDL file).
The DCE IDL compiler can define a client Entry Point Vector with
addresses of local routines. Client applications can call these
routines. For more information about client entry point vectors,
see the explanation of the -cepv argument in the idl reference
page.
If the server offers multiple implementations of the same interface,
the server must create additional manager EPVs, one for each
implementation. Each EPV must contain exactly one entry point
(address of a function) for each procedure defined in the IDL file.
The server application declares and initializes one manager EPV
variable of type if-name_vmajor-version_minor-version_epv_t for each
implementation of the interface.
The rpc_server_register_if() and rpc_server_inq_if() routines use
the manager EPV data type and show the manager EPV argument as
having an rpc_mgr_epv_t data type.
4.12 – Name Service Handle
A name service handle is a pointer-size opaque variable containing
information the RPC runtime uses to return the following RPC data
from the name service database:
+ Server binding handles
+ UUIDs of resources offered by a server
+ Profile members
+ Group members
The following routines require a name service handle and show an
argument data type of rpc_ns_handle_t:
+ rpc_ns_binding_import_begin()
+ rpc_ns_binding_import_next()
+ rpc_ns_binding_import_done()
+ rpc_ns_binding_lookup_begin()
+ rpc_ns_binding_lookup_next()
+ rpc_ns_binding_lookup_done()
+ rpc_ns_entry_object_inq_begin()
+ rpc_ns_entry_object_inq_next()
+ rpc_ns_entry_object_inq_done()
+ rpc_ns_group_mbr_inq_begin()
+ rpc_ns_group_mbr_inq_next()
+ rpc_ns_group_mbr_inq_done()
+ rpc_ns_profile_elt_inq_begin()
+ rpc_ns_profile_elt_inq_next()
+ rpc_ns_profile_elt_inq_done()
+ rpc_ns_mgmt_handle_set_exp_age()
The scope of a name service handle is from a *_begin() routine
through the corresponding *_done() routine.
Applications have responsibility for concurrency control of name
service handles across threads.
4.13 – Protocol Sequence
A protocol sequence is a character string identifying the network
protocols used to establish a relationship between a client and
server. The protocol sequence contains a set of options that the
RPC runtime must know about. The following options are in this set:
+ The RPC protocol used for communications (choices are ncacn
and ncadg).
+ The format used in the network address supplied in the
binding (choice is ip).
+ The transport protocol used for communications (choices are
tcp and udp).
Because only certain combinations of these options are valid (are
useful for interoperation), RPC provides predefined strings that
represent the valid combinations. RPC applications use only these
strings. The following table contains predefined strings
representing valid protocol sequences. In the descriptions NCA is
an abbreviation of Network Computing Architecture.
Valid Protocol Sequences
___________________________________________________________
Protocol Sequence Description
___________________________________________________________
ncacn_ip_tcp NCA Connection over Internet Protocol:
Transmission Control Protocol
ip or ncadg_ip_udp NCA Datagram over Internet Protocol:
User Datagram Protocol
ncacn_dnet_nsp NCA Connection over DECnet Phase IV
ncacn_osi_dna NCA Connection over DECnet/OSI
A server application can use a particular protocol sequence only if
the operating system software supports that protocol. A server
chooses to accept remote procedure calls over some or all of the
supported protocol sequences.
Client and server applications can determine if a protocol sequence
is supported by both the RPC runtime and the operating system. The
applications make this determination by calling the following
routines:
+ rpc_network_inq_protseqs()
+ rpc_network_is_protseq_valid()
The following routines allow server applications to register
protocol sequences with the runtime:
+ 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()
Those routines requiring a protocol sequence argument show a data
type of unsigned_char_t *.
A client can use the protocol sequence strings to construct a string
binding using the rpc_string_binding_compose() routine.
4.14 – Protocol Sequence Vector
The protocol sequence vector data structure contains a list of
protocol sequences over which the RPC runtime can send or receive
remote procedure calls. The protocol sequence vector contains a
count member (count), followed by an array of pointers to protocol
sequence strings (protseq). The C language representation of a
protocol sequence vector is as follows:
typedef struct {
unsigned32 count;
unsigned_char_t *protseq[1];
} rpc_protseq_vector_t;
The protocol sequence vector is a read-only vector. To obtain a
protocol sequence vector, a server application calls the
rpc_network_inq_protseqs() routine. The RPC runtime allocates
memory for the protocol sequence vector. The server application
calls the rpc_protseq_vector_free() routine to free the protocol
sequence vector.
4.15 – Statistics Vector
The statistics vector data structure contains statistics from the
RPC runtime on a per address space basis. The statistics vector
contains a count member (count), followed by an array of
statistics. Each array element contains an unsigned32 value.
The following list describes the statistics indexed by the
specified constant:
rpc_c_stats_calls_in
The number of remote procedure calls received by the
runtime.
rpc_c_stats_calls_out
The number of remote procedure calls initiated by the
runtime.
rpc_c_stats_pkts_in
The number of network packets received by the runtime.
rpc_c_stats_pkts_out
The number of network packets sent by the runtime.
The C language representation of a statistics vector is as follows:
typedef struct {
unsigned32 count;
unsigned32 stats[1];
} rpc_stats_vector_t;
To obtain runtime statistics, an application calls the
rpc_mgmt_inq_stats() routine. The RPC runtime allocates memory
for the statistics vector. The application calls the
rpc_mgmt_stats_vector_free() routine to free the statistics vector.
4.16 – String Binding
A string binding contains the character representation of a binding
handle.
String bindings are a convenient way of representing portions of a
binding handle. However, you cannot use string bindings directly
to make remote procedure calls. You must first call the routine
rpc_binding_from_string_binding(), which converts a string binding
to a binding handle.
A string binding does not contain all the information from a binding
handle. For example, a call to the routine
rpc_binding_to_string_binding() does not translate the authenti-
cation information sometimes associated with a binding handle into
the resulting string binding.
You can begin the development of a distributed application by having
its servers communicate their binding information to clients by
using string bindings. This communication allows a server to
establish a client/server relationship without using the local
endpoint map or the name service database.
In this case, the server calls none of the rpc_ep_register(),
rpc_ep_register_no_replace(), and rpc_ns_binding_export() routines.
Instead, the server calls only routine rpc_server_inq_bindings() to
obtain a vector of binding handles. The server obtains binding
handles one at a time from the vector and calls routine
rpc_binding_to_string_binding() to convert each binding handle into
a string binding. The resulting string binding is always fully bound
and may contain a non-nil object UUID. The server then makes some or
all of its string bindings available to clients. One way is placing
the string bindings in a file to be read by clients or users or
both. Another way is delivering the string bindings to clients or
users by means of a file, mail, or paper.
You can continue the distributed application's development by
changing the application so that servers use the local endpoint
map and the name service database to communicate their binding
information.
To find the server, a client obtains a string binding containing a
protocol sequence that the client runtime supports and, optionally,
an object UUID that the client requires. The client then calls
routine rpc_binding_from_string_binding() to convert the string
binding into a server binding handle.
Other useful routines for working with string bindings are
rpc_string_binding_compose(), which creates a string binding from
its component parts, and rpc_string_binding_parse(), which
separates a string binding into its component parts.
The two formats of a string binding follow. The four fields
represent the object UUID, RPC protocol sequence, network address,
and endpoint and network options of the binding. A delimiter
character such as @ (at sign) or : (colon) separates each field.
A string binding does not contain any white space.
object-uuid @ rpc-protocol-sequence : nw-addr [endpoint, option ...]
or
object-uuid @ rpc-protocol-sequence : nw-addr [endpoint = endpoint,
option ...]
object-uuid
This field specifies the UUID of the object operated on
by the remote procedure that is called with this string
binding. The RPC runtime, at the server, maps the
object's type to a manager Entry Point Vector (EPV) to
invoke the correct manager routine. The explanation of
the routine rpc_server_register_if() discusses mapping
object UUIDs to manager EPVs.
This field is optional. If you do not provide it the RPC
runtime assumes a nil UUID.
@ This symbol is the delimiter character for the object UUID
field. If you specify an object UUID you must follow it
with this symbol.
rpc-protocol-sequence
This field specifies the protocol sequence used for making
remote procedure calls. The valid protocol sequences are
as follows:
ncacn_ip_tcp
ncadg_ip_udp
More information about these valid protocol sequences
appears in the table in the entry on Protocol_Sequence.
This field is required.
: This symbol is the delimiter character for the RPC
protocol sequence field.
nw-addr This field specifies the address (addr) of a host on a
network (nw) that receives remote procedure calls made
with this string binding. The format and content of the
network address depends on the value of rpc-protocol-
sequence as follows:
ncacn_ip_tcp and ncadg_ip_udp
Specify an Internet address using the common Internet
address notation or hostname.
Two examples with common Internet address notation are
128.10.2.30 and #126.15.1.28. The second example shows
the use of the optional # (number sign) character.
An example with a host name is ko.
If the specified hostname is multihomed, the binding
handle returned from routine
rpc_binding_from_string_binding() contains a host address.
It is the first host address returned from the system
library call that translates a hostname to a host address
for the network address format in the protocol sequence.
To control the host address used, specify the network
address using the common Internet address notation instead
of a hostname.
The network address field is optional. If you do not
supply this field, the string binding refers to your
local host.
[ This symbol is the delimiter character specifying that
one endpoint and zero or more options follow. If the
string binding contains at least one endpoint, this
symbol is required.
endpoint This field specifies the endpoint, or address of a
specific server instance on a host, to receive remote
procedure calls made with this string binding.
Optionally the keyword endpoint= can precede the
endpoint specifier.
The format and content of the endpoint depends on the
specified protocol sequence as follows:
ncacn_ip_tcp and ncadg_ip_udp
Specify an Internet port number.
An example of an Internet port number is 1025.
The endpoint field is optional. For more information
about endpoints, see the information on binding handles
in this reference page.
, This symbol is the delimiter character specifying that
option data follows. If an option follows, this
delimiter is required.
option This field specifies any options. Each option is
specified as option name=option value.
The format and content of the option depends on the
specified protocol sequence as follows:
ncacn_ip_tcp and ncadg_ip_udp
There are no Internet options.
The option field is optional.
] This symbol is the delimiter character specifying that
one endpoint and zero or more options precede. If the
string binding contains at least one endpoint, this
symbol is required.
The \ (backslash) character is treated as an escape character for
all string binding fields.
Examples of valid string bindings follow. In each example obj-uuid
represents a UUID in string form. In other words, the symbol
obj-uuid can represent the UUID
308fb580-1eb2-11ca-923b-08002b1075a7.
obj-uuid@ncacn_ip_tcp:16.20.16.27[2001]
obj-uuid@ncacn_ip_tcp:16.20.16.27[endpoint=2001]
4.16.1 – String UUID
A string UUID contains the character representation of a UUID.
A string UUID consists of multiple fields of hexadecimal
characters.
Each field has a fixed length, and dashes separate the fields.
An example of a string UUID follows:
989c6e5c-2cc1-11ca-a044-08002b1bb4f5
When you supply a string UUID as an input argument to an RPC
runtime routine, you can enter the alphabetic hexadecimal
characters in either uppercase or lowercase letters. The RPC
runtime routines that return a string UUID always return the
hexadecimal characters in lowercase letters.
The following routines require a string UUID:
+ rpc_string_binding_compose()
+ uuid_from_string()
The following routines return a string UUID:
+ rpc_string_binding_parse()
+ uuid_to_string()
4.16.2 – Unsigned Character String
DCE RPC treats all characters in strings as unsigned characters. Those routines with character string arguments show a data type of unsigned_char_t *.
4.16.3 – UUID Vector
The UUID vector data structure contains a list of UUIDs. The
UUID vector contains a count member (count), followed by an
array of pointers to UUIDs.
The C language representation of a UUID vector is as follows:
typedef struct
{
unsigned32 count;
uuid_t *uuid[1];
} uuid_vector_t;
An application constructs a UUID vector to contain object UUIDs
to be exported or unexported from the name service database. The
following routines require a UUID vector and show an argument data
type of uuid_vector_t:
+ rpc_ep_register()
+ rpc_ep_register_no_replace()
+ rpc_ep_unregister()
+ rpc_ns_binding_export()
+ rpc_ns_binding_unexport()
+ rpc_ns_mgmt_binding_unexport()
5 – Permissions Required
To use the Name Service Interface (NSI) routines to access entries
in a Cell Directory Service (CDS) database, you need Access Control
List (ACL) permissions. Depending on the NSI operation, you need
ACL permissions to the parent directory or the CDS object entry
(the name service entry) or both.
The ACL permissions are as follows:
+ To create an entry, you need insert permission to the parent
directory.
+ To read an entry, you need read permission to the CDS object
entry.
+ To write to an entry, you need write permission to the CDS
object entry.
+ To delete an entry, you need delete permission either to the
CDS object entry or to the parent directory.
+ To test an entry, you need either test permission or read
permission to the CDS object entry.
Note that write permission does not imply read permission.
To find the ACL permissions for the NSI routines whose names begin
with rpc_ns, see these routines' reference pages.
The non-NSI routines whose names do not begin with rpc_ns do not
need ACL permissions, so their reference pages do not specify any.
6 – Frequently Used Routine Parameters
A few parameters are common to many of the DCE RPC routines. These parameters are described fully here and again briefly on the specific routine reference pages.
6.1 – binding
Used as an input or output parameter.
Returns a binding handle for making remote procedure calls to a
server.
A client obtains a binding handle by calling one of the following
routines:
+ rpc_binding_copy()
+ rpc_binding_from_string_binding()
+ rpc_ns_binding_import_next()
+ rpc_ns_binding_select()
Creating a binding handle establishes a relationship between a
client and a server. However, the relationship does not involve
any communications between the client and server. The
communications occur when a client makes a remote procedure call.
As an input parameter to a remote procedure call, binding specifies
a binding handle that refers to binding information. The client's
RPC runtime uses this binding information to make a remote procedure
call to a server. Server manager routines can extract client
information from a client binding handle by using the following
routines:
+ rpc_binding_inq_auth_client()
+ rpc_binding_inq_object()
+ rpc_binding_to_string_binding()
+ rpc_string_binding_parse()
6.2 – name
Used as an input/output parameter. When used as an input parameter, the value of this parameter depends on the syntax selected in the name_syntax parameter. If it is allowed by the called routine, the value NULL specifies that the routine uses the name specified in the RPC_DEFAULT_ENTRY environment variable. Specifying NULL also has the called routine use the name syntax that the environment variable RPC_DEFAULT_ENTRY_SYNTAX specifies. For a name_syntax value of rpc_c_ns_syntax_dce, use the DCE naming rules to specify parameter name. As an output parameter, returns an entry in the name service database in the form of a character string that includes a terminating null character. The value of this parameter depends on the syntax selected in name_syntax. For a name_syntax value of rpc_c_ns_syntax_dce, name is returned using the DCE naming syntax. The DCE RPC runtime allocates memory for the returned string. The application is responsible for calling the rpc_string_free() routine to deallocate the string. If an application does not want a returned name string, the application usually specifies NULL for this parameter. The one exception is routine rpc_ns_entry_expand_name(); it always returns a name string.
6.3 – name_syntax
Used as an input parameter, an integer value that specifies the
syntax of an entry name. When allowed by the called routine, a
value of rpc_c_ns_syntax_default specifies that the routine uses
the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX environment
variable. The following table lists the valid syntaxes that
applications can use in DCE RPC for entries in the name service
database.
Valid Name Syntaxes
________________________________________________
Constant Value Description
________________________________________________
rpc_c_ns_syntax_default 0 Default syntax
rpc_c_ns_syntax_dce 3 DCE
The name_syntax parameter tells routines how to parse the entry
name specified in an input name parameter or specifies the syntax
to use when returning an entry name as an output name parameter.
If the RPC_DEFAULT_ENTRY_SYNTAX environment variable is not
defined, the RPC runtime uses the rpc_c_ns_syntax_dce name syntax.
6.4 – string
Used as an input or output parameter. Returns a character string, which always includes the terminating null character \0. The DCE RPC runtime allocates memory for the returned string. The application calls the rpc_string_free() routine to deallocate the memory occupied by the string. If there is no data for the requested string, the routine returns the string \0. For example, if the string binding passed to routine rpc_string_binding_parse() does not contain an object UUID, the routine returns \0 as the value of the object UUID string. The application must call the rpc_string_free() routine to deallocate the memory occupied by this string. If an application does not require a returned output string, the application specifies NULL for this parameter.
6.5 – status
Each routine in the RPC API returns a DCE status code indicating whether the routine completed successfully or, if not, why not. A return value of rpc_s_ok indicates success. All other return values signify routine failure. The status codes listed for each RPC runtime routine are the most likely, but not necessarily all, the status codes that the routine can return. The status code argument has a data type of unsigned32. To translate a DCE status code to a text message, call the routine dce_error_inq_text(). Note that RPC exceptions are equivalent to RPC status codes. To identify the status code that corresponds to a given exception, replace the _x_ string of the exception with the string _s_; for example, the exception rpc_x_already_listening is equivalent to the status code rpc_s_already_listening. For more information about the RPC status codes, see the OSF DCE Problem Determination Guide.
6.6 – uuid
Used as an input or output parameter. When you need to specify a nil UUID to a uuid input parameter in any of the DCE RPC routines, you can supply the value NULL.
7 – RELATED_INFORMATION
Books: OSF DCE Application Development Guide-Introduction & Style
Guide
OSF DCE Application Development Guide-Core Components
OSF DCE Application Development Guide-Directory Services
OSF DCE Command Reference