RPC API Manual Pages

RPC Data Types

The data type declarations given here fall into three categories:

• The declarations make use of a set of primitive unsigned integer data types. The C-language bindings for these types are implementation-dependent. Only the ranges of these types are given here.

• Certain data types are intended to be opaque to applications. The C-language bindings of opaque types are not given here.

• The remaining data types are defined explicitly here with C-language bindings that make use of the unsigned integer types, opaque types and other defined types.

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.

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 -2³¹ to 2³¹-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.

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:

• free the individual binding

• not change the value of count.

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:

• if-name is the interface identifier specified in the IDL file.

• major-version is the interface's major-version number specified in the IDL file.

• minor-version is the interface's minor-version number specified in the IDL file.

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.