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.
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.
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()
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 – 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.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.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;
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()
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.
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.
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()
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()
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.
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.
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.
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.
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.
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.
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]
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()
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 *.
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()