String Binding

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 authentication 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 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 Binding Handle in RPC Data Types and Structures.

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