Previous section.

CDE 1.1: Remote Procedure Call
Copyright © 1997 The Open Group

RPC API Manual Pages

RPC Data Types

The descriptions of the data types used by RPC API routines include C-language bindings, where appropriate.

The data type declarations given here fall into three categories:

Applications that refer to the data types described here must include the C header file <dce/rpc.h>.

Unsigned Integer Types

Some of RPC API function declarations and the remaining definitions given here make use of a set of unsigned integer data types. Each type holds an unsigned integer within a specified range, as shown in the following table.


Type Declaration Range
unsigned8 0 to 28-1
unsigned16 0 to 216-1
unsigned32 0 to 232-1





The C-language bindings for these types are implementation-dependent.

Signed Integer Type

The rpc_mgmt_set_cancel_timeout() routine uses the signed32 data type. This is an integer in the range -231 to 231-1.

Unsigned Character String

RPC treats all characters in strings as unsigned characters. The C-language binding of the unsigned character string type is implementation-dependent. The unsigned character data type must be able to encode the characters of the portable character set, as specified in Portable Character Set . Routines that require character string arguments specify the data type unsigned_char_t.

Binding Handle

A binding handle is an opaque data type that applications use to reference binding information maintained by the RPC run-time system. Depending on the binding information that it references, a binding handle is considered a server binding handle or a client binding handle.

A server binding handle references binding information for a server. Server binding handles appear as arguments to many RPC API routines, and they are used both by clients and servers to manipulate the bindings required for remote procedure calls.

A client binding handle references binding information for a client that has made an RPC to a server. A client binding handle may be provided to the server application as the first argument to the call. (See Interface Definition Language for further information.) Servers can use the routine rpc_binding_server_from_client() to convert a client binding handle to a server binding handle that can be used to make a remote procedure call to the calling client.

As described in Introduction to the RPC API , a binding handle refers to several components of binding information. When this binding information lacks an endpoint, the binding handle is said to be partially bound. When the binding information includes an endpoint, the binding handle is said to be fully bound. Both fully and partially bound binding handles can be used to make remote procedure calls.

RPC API routines requiring a binding handle as an argument specify the data type rpc_binding_handle_t. Binding handle arguments are passed by value.

The following table lists RPC API routines that operate on binding handles, specifying the type of binding handle required by each routine.


Routine Input Argument Output Argument
cs_byte_from_netcs() Server or client None
cs_byte_local_size() Server or client None
cs_byte_net_size() Server or client None
cs_byte_to_netcs() Server or client None
rpc_binding_copy() Server Server
rpc_binding_free() Server None
rpc_binding_from_string_binding() None Server
rpc_binding_inq_auth_caller() 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_cs_binding_set_tags() Server Server
rpc_cs_get_tags() Server or client None
rpc_ep_resolve_binding() Server None
rpc_mgmt_ep_elt_inq_begin() Server None
rpc_mgmt_ep_elt_inq_next() None Server
rpc_mgmt_ep_unregister() Server None
rpc_mgmt_inq_com_timeout() Server None
rpc_mgmt_inq_if_ids() Server or client None
rpc_mgmt_inq_server_princ_name() Server None
rpc_mgmt_inq_stats() Server None
rpc_mgmt_is_server_listening() Server None
rpc_mgmt_set_com_timeout() Server None
rpc_mgmt_stop_server_listening() Server None
rpc_ns_binding_import_next() None Server
rpc_ns_binding_inq_entry_name() Server None
rpc_ns_binding_select() Server Server
rpc_ss_bind_authn_client() Server Server
rpc_tower_to_binding() None Server or client
rpc_tower_vector_to_binding() Server or client None
wchar_t_from_netcs() Server or client None
wchar_t_local_size() Server or client None
wchar_t_net_size() Server or client None
wchar_t_to_netcs() Server or client None


Table: Client and Server Binding Handles

An application can share a single binding handle across multiple threads of execution. The application must provide concurrency control for operations that read or modify a shared binding handle. The related routines are:

rpc_binding_free() rpc_binding_reset() rpc_binding_set_auth_info() rpc_binding_set_object() rpc_ep_resolve_binding() rpc_mgmt_set_com_timeout()

Binding Vector

The binding vector data structure contains a list of binding handles over which a server application can receive remote procedure calls.

The C-language declaration is:

typedef struct { unsigned32 count; rpc_binding_handle_t binding_h[1]; } rpc_binding_vector_t;

(The [1] subscript is a placeholder in the binding vector declaration. Applications use the count member to find the actual size of a returned binding vector.)

The RPC run-time system 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 the rpc_ns_binding_lookup_next() routine. In both cases, the RPC run-time system allocates memory for the binding vector. An application calls the rpc_binding_vector_free() routine to free the binding vector.

To remove an individual binding handle from the vector, the application sets its value in the vector to NULL. When setting a vector element to NULL the application must:

Calling the rpc_binding_free() routine allows an application both to free the unwanted binding handle and to set the vector entry to NULL.

The following routines require a binding vector argument:

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()

Boolean Type

Routines that require a Boolean-valued argument or return a Boolean value specify the data type boolean32. RPC implementations define the Boolean constants TRUE and FALSE.

Endpoint Map Inquiry Handle

An endpoint map inquiry handle is an opaque data type that references inquiry state information used by a series of endpoint inquiry operations. The endpoint inquiry handle data type is rpc_ep_inq_handle_t. Applications obtain an endpoint map inquiry handle by calling rpc_mgmt_ep_elt_inq_begin() and use the handle for one or more calls to rpc_mgmt_ep_elt_inq_next(). Applications call rpc_mgmt_ep_elt_inq_done() to free an endpoint map handle.

Interface Handle

Each stub declares an interface handle that can be used by application code to reference interface-related data maintained by the stub. The interface handle data type is rpc_if_handle_t. Applications refer to a stub-declared interface handle using a well-known name constructed 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:

Implementations must support a maximum if-name length of at least 17 characters.

The following routines specify an interface handle argument:

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() rpc_ss_bind_authn_client() rpc_tower_vector_from_binding()

Interface Identifier

An interface identifier (interface ID) data structure contains the interface UUID and major-version and minor-version numbers of an interface. The C-language declaration is:

typedef struct { uuid_t uuid; unsigned16 vers_major; unsigned16 vers_minor; } rpc_if_id_t;

Applications can obtain an interface identifier by calling rpc_if_inq_id() with an interface handle. The following routines also require interface identifier arguments:

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()

Interface Identifier Vector

The interface identifier (ID) vector data structure holds a list of interface identifiers.

The C-language declaration is:

typedef struct { unsigned32 count; rpc_if_id_t *if_id[1]; } rpc_if_id_vector_t;

(The [1] subscript is a placeholder in the interface ID vector declaration. Applications use the count member to find the actual size of a returned vector.)

To obtain a vector of the interface IDs registered by a server with the RPC run-time system, an application calls the rpc_mgmt_inq_if_ids() routine. To obtain a vector of the interface IDs exported by a server to a name service database, an application calls the rpc_ns_mgmt_entry_inq_if_ids() routine.

The RPC run-time system allocates memory for the interface ID vector. The application calls the rpc_if_id_vector_free() routine to free the interface ID vector.

Manager Entry Point Vector

The server stub declares a default manager entry point vector (EPV), which it uses to call the operations that implement an interface. A manager EPV consists of a vector of pointers to the operations of the interface. To declare the default manager EPV, the stub defines an interface-specific manager EPV data type with the following type name:

<if-name>_v<major-version>_<minor-version>_epv_t

The data type is defined as a C struct whose elements are pointers to the manager routines for the interface, with the same names and in the same order in which they appear in the IDL interface specification.

The stub declares the default manager EPV with the name NIDL_manager_epv.

Applications can use the stub-declared manager EPV data type to declare non-default manager EPVs. Applications initialise non-default manager EPVs with a vector of addresses of alternate manager routines. Applications that declare non-default manager EPVs must avoid the default name.

See tagmref_rpc_server_register_if for further information on non-default manager EPVs.

Name Service Handle

RPC API routines that obtain information from a name service use opaque name service handles to refer to search state information maintained by the run-time system. Applications obtain a name service handle by calling one of the name service begin routines and use the handle for one or more calls to the corresponding next routine. Applications free a name service handle by calling one of the name service done routines. For more information on name service handles and operations, refer to Introduction to the RPC API .

The name service handle data type is rpc_ns_handle_t.

The following routines require a name service handle argument:

rpc_ns_binding_import_begin() rpc_ns_binding_import_done() rpc_ns_binding_import_next() 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_import_ctx_add_eval() 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()

Protocol Sequence String

A protocol sequence string is a character string that identifies a protocol sequence. Protocol sequences are used to establish a relationship between a client and server. Valid protocol sequence strings are listed in Protocol Sequence Strings . RPC applications should use only these strings.

Routines that require a protocol sequence string argument specify the data type unsigned_char_t.

Not all valid protocol sequences are supported by all implementations. An application can use a specific protocol sequence only if the implementation supports that protocol.

A server chooses to accept remote procedure calls over some or all of the supported protocol sequences. The following routines allow server applications to register protocol sequences with the run-time system:

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()

Applications can use protocol sequence strings to construct string bindings using the rpc_string_binding_compose() routine.

Protocol Sequence Vector

The protocol sequence vector data structure contains a list of protocol sequence strings. The protocol sequence vector contains a count member followed by an array of pointers to protocol sequence strings.

The C-language declaration is:

typedef struct { unsigned32 count; unsigned_char_t *protseq[1]; } rpc_protseq_vector_t;

(The [1] subscript is a placeholder in the protocol sequence vector declaration. Applications use the count member to find the actual size of a returned binding vector.)

To obtain a protocol sequence vector, an application calls the rpc_network_inq_protseqs() routine. The RPC run-time system allocates memory for the protocol sequence vector. The application calls the rpc_protseq_vector_free() routine to free the protocol sequence vector.

Statistics Vector

A statistics vector is used to store statistics from the RPC run-time system for a server instance. The statistics vector contains a count member followed by an array of statistics.

The C-language declaration is:

typedef struct { unsigned32 count; unsigned32 stats[1]; } rpc_stats_vector_t, *rpc_stats_vector_p_t;

(The [1] subscript is a placeholder in the statistics vector declaration. Applications use the count member to find the actual size of a returned binding vector.)

The X/Open DCE specifies four statistics that are returned in a statistics vector. The following constants are used to index the statistics array to extract specific statistics:

rpc_c_stats_calls_in
The number of remote procedure calls received by the server.

rpc_c_stats_calls_out
The number of remote procedure calls initiated by the server.

rpc_c_stats_pkts_in
The number of RPC PDUs received by the server.

rpc_c_stats_pkts_out
The number of RPC PDUs sent by the server.

To obtain run-time statistics, an application calls the rpc_mgmt_inq_stats() routine. The RPC run-time system allocates memory for the statistics vector. The application calls the rpc_mgmt_stats_vector_free() routine to free the statistics vector.

String Binding

A string binding contains the character representation of a binding handle.

The two formats of a string binding are shown below. The four italicised fields represent the object UUID, RPC protocol sequence, network address and endpoint and network options of the binding. A delimiter character such as an @ (at sign) or a : (colon) separates each field. A string binding does not contain any white space.

object-uuid @ rpc-protocol-sequence : network-address [endpoint , option ...

or

object-uuid @ rpc-protocol-sequence : network-address [endpoint = endpoint , option ...

object-uuid
This field specifies an object UUID.

This field is optional. If it is not provided the RPC run-time system assumes a nil type UUID.

@
This symbol is the delimiter character for the object UUID field. If an object UUID is specified, it must be followed by this symbol.

rpc-protocol-sequence
This field specifies a protocol sequence. Valid protocol sequence strings are listed in Protocol Sequence Strings .

This field is required.

:
This symbol is the delimiter character for the RPC protocol sequence field.

network-address
This field specifies the address (address) of a host on a network (network) 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. For the internet protocols, the format for the network address is an optional # (number sign) character followed by four integers separated by periods.

The network address field is optional. If an application does not supply this field, the string binding refers to the 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 an endpoint, this symbol is required.

endpoint
This field specifies an endpoint of a specific server instance. Optionally the keyword endpoint= can precede the endpoint specifier.

The format and content of the endpoint depends on the specified protocol sequence. For the internet protocols, the format of the endpoint field is a single integer.

The endpoint field is optional.

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

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 an endpoint, this symbol is required.

The \ (backslash) character is treated as an escape character for all string binding fields. It can be used to include one of the string delimiters in the value of a field.

String UUID

A string UUID contains the character representation of a UUID. A string UUID consists of multiple fields of hexadecimal characters. Dashes separate the fields and each field has a fixed length, as follows:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

For a detailed specification of string UUIDs, see Universal Unique Identifier .

The following routines require a string UUID argument:

rpc_string_binding_compose() rpc_string_binding_parse() uuid_from_string() uuid_to_string()

UUIDs

Universal Unique Identifiers (UUIDs) are opaque data structures that are widely used by the RPC mechanism. The RPC API provides a series of routines to manipulate UUIDs. Routines that take a UUID argument declare the data type as uuid_t. (See Universal Unique Identifier for a detailed specification of UUIDs.)

UUID Vector

The UUID vector data structure contains a list of UUIDs. The UUID vector contains a count member, followed by an array of pointers to UUIDs.

The C-language declaration is:

typedef struct { unsigned32 count; uuid_t *uuid[1]; } uuid_vector_t;

The [1] subscript is a placeholder in the UUID vector declaration. Applications use the count member to find the actual size of a returned binding vector.

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 argument:

rpc_ep_register() rpc_ep_register_no_replace() rpc_ep_unregister() rpc_ns_binding_export() rpc_ns_binding_unexport() rpc_ns_mgmt_binding_unexport()

Code Set Types

Some RPC internationalisation support routines identify and convert between code sets. The C-language declaration 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. The C-language declaration of a code set structure is as follows:

typedef struct { unsigned32 version; long count; [size_is(count)] rpc_cs_c_set_t codesets[]; } rpc_codeset_mgmt_t, *rpc_codeset_mgmt_p_t;

The array of code set data structures is declared as 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 following routines require code set data structure arguments:

rpc_ns_mgmt_free_codesets() rpc_ns_mgmt_read_codesets() rpc_rgy_get_codesets()

Server applications that use the rpc_ns_mgmt_set_attribute() routine 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*.

The conversion type data structure is an enumerated type returned by international character conversion buffer sizing routines. The C-language declaration 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;

The following routines require conversion type data structure arguments:

cs_byte_local_size() cs_byte_net_size() wchar_t_local_size() wchar_t_net_size()

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.

Contents Next section Index