String Binding

ObjectUUID@ProtocolSequence:NetworkAddress[Endpoint,Option]

ObjectUUID

Specifies the UUID of the object operated on by the remote procedure call. At the server, the RPC run-time library maps the object type to a manager entry-point vector (an array of function pointers) to invoke the correct manager routine. For a discussion of how to map object UUIDs to manager entry-point vectors, see RpcServerRegisterIfEx.

Protocol Sequence

Specifies a character string that represents a valid combination of an RPC protocol (such as "ncacn"), a transport protocol (such as "tcp"), and a network protocol (such as "ip"). Microsoft RPC supports the following protocol sequences:

Protocol sequence	Description	Supporting Platforms
ncacn_nb_tcp	Connection-oriented NetBIOS over TCP	client only: MS-DOS, Windows 3.x client and server: Windows NT
ncacn_nb_ipx	Connection-oriented NetBIOS over IPX	client only: MS-DOS, Windows 3.x client and server: Windows NT
ncacn_nb_nb	Connection-oriented NetBEUI	client only: MS-DOS, Windows 3.x client and server: Windows NT, Windows 95
ncacn_ip_tcp	Connection-oriented TCP/IP	client only: MS-DOS, Windows 3.x, and Apple Macintosh client and server: Windows 95 and Windows NT
ncacn_np	Connection-oriented named pipes	client only: MS-DOS, Windows 3.x, Windows 95 client and server: Windows NT
ncacn_spx	Connection-oriented SPX	client only: MS-DOS, Windows 3.x client and server: Windows NT, Windows 95
ncacn_dnet_nsp	Connection-oriented DECnet transport	client only: MS-DOS, Windows 3.x

NetworkAddress

Specifies the network address of the system to receive remote procedure calls. The format and content of the network address depend on the specified protocol sequence as follows:

Protocol sequence	Network address	Examples
ncacn_nb_tcp	Windows NT machine name	myserver
ncacn_nb_ipx	Windows NT machine name	myserver
ncacn_nb_nb	Windows NT or Windows 95 machine name	myserver
ncacn_ip_tcp	four-octet internet address, or host name	128.10.2.30 anynode.microsoft.com
ncacn_np	Windows NT server name (leading double backslashes are optional)	myserver \\myotherserver
ncacn_spx	IPX internet address, or Windows NT server name	~0000000108002B30612C myserver
ncacn_dnet_nsp	Area and node syntax	4.120
ncacn_at_dsp	Windows NT machine name, optionally followed by @ and the AppleTalk zone name. Defaults to @*, the client's zone, if no zone provided	servername@zonename servername
ncacn_vns_spp	StreetTalk server name of the form item@group@organization	printserver@sdkdocs@microsoft
ncadg_mq	Windows NT server name	myserver
ncacn_http	Internet address (either four-octet or friendly name, or local Windows NT server name	128.10.2.30 somesvr@anywhere.com mylocalsvr
ncadg_ip_udp	four-octet internet address, or host name	128.10.2.30 anynode.microsoft.com
ncadg_ipx	IPX internet address, or Windows NT server name	~0000000108002B30612C myserver
ncalrpc	Machine name	thismachine

The network-address field is optional. When you do not specify a network address, the string binding refers to your local host. It is possible to specify the name of the local machine when you use the ncalrpc protocol sequence, however doing so is completely unnecessary.

Endpoint

Specifies the endpoint, or address, of the process to receive remote procedure calls. An endpoint can be preceded by the keyword endpoint=. Specifying the endpoint is optional if the server has registered its bindings with the endpoint mapper. See RpcEpRegister.

The format and content of an endpoint depend on the specified protocol sequence as shown in the Endpoint/Option Table, below.

Option

Specifies protocol-specific options.. The option field is not required. Each option is specified by a {name, value} pair that uses the syntax option name=option value. Options are defined for each protocol sequence as shown in the Endpoint/Option Table, below.

Protocol sequence	Endpoint	Examples	Option name
ncacn_nb_tcp	Integer between 1 and 254. Many values between 0 and 32 are reserved by Microsoft.	100	None
ncacn_nb_ipx	(as above)	(as above)	None
ncacn_nb_nb	(as above)	(as above)	None
ncacn_ip_tcp	Internet port number	1025	None
ncacn_np	Windows NT named pipe. Name must start with "\\pipe".	\\pipe\\pipename	Security (NT only)
ncacn_spx	Integer between 1 and 65535.	5000	None
ncacn_dnet_nsp	DECnet phase IV object number (must be preceded by the # character), or object name	mailserver #17	None
ncacn_at_dsp	A character string, up to 22 bytes long	myservicesendpoint	None
ncacn_vns_spp	Vines SPP port number between 250 and 511	500	None
ncadg_mq	Integer between 1 and 65535.	5000	None
ncacn_http	Internet port number	2215	HTTP and RPC proxy server names
ncadg_ip_udp	Internet port number	1025	Security (32-bit only)
ncadg_ipx	Integer between 1 and 65535.	5000	Security (32-bit only)
ncalrpc	String specifying application or service name. The string cannot include any backslash characters.	my_printer	Security (NT only)

The Security option name, supported for the ncalrpc, ncacn_np, ncadg_ip_udp, and ncadg_ipx protocol sequences, takes the following option values:

Option name	Option value
Security	{identification | anonymous | impersonation} {dynamic | static} {true | false}

If the Security option name is specified, one entry from each of the sets of Security option values must also be supplied. The option values must be separated by a single-space character. For example, the following Option fields are valid:

Security=identification dynamic true
Security=impersonation static true
 

The Security option values have the following meanings:

Security option value	Description
Anonymous	The client is anonymous to the server.
Dynamic	A pointer to the security token is maintained. Security settings represent current settings and include changes made after the endpoint was created.
False	Effective = FALSE; all Windows NT security settings, including those set to OFF, are included in the token.
Identification	The server has information about client but cannot impersonate.
Impersonation	The server is the client on the client's behalf.
Static	Security settings associated with the endpoint represent a copy of the security information at the time the endpoint was created. The settings do not change.
True	Effective = TRUE; only Windows NT security settings set to ON are included in the token.

For more information about Microsoft Windows NT security options, see your Microsoft Windows NT programming documentation.

Remarks

The string binding is an unsigned character string composed of strings that represent the binding object UUID, the RPC protocol sequence, the network address, and the endpoint and endpoint options. White space is not allowed in string bindings except where required by the Option syntax.

Default settings for the NetworkAddress, Endpoint, and Option fields vary according to the value of the ProtocolSequence field.

For all string-binding fields, a single backslash character (\) is interpreted as an escape character. To specify a single literal backslash character, you must supply two backslash characters (\\).

The following are examples of valid string bindings. In these examples, obj-uuid is used for convenience to represent a valid UUID in string form. Instead of showing the UUID 308FB580-1EB2-11CA-923B-08002B1075A7, the examples show obj-uuid.

obj-uuid@ncadg_mq:mymqserver
obj-uuid@ncacn_http:major7.somewhere.com[2225]
obj_uuid@ncacn_http:major7.somewhere.com[,HttpProxy=proxysvr:80,
    RpcProxy=websvr1.somewhere.com:80]
obj-uuid@ncacn_ip_tcp:16.20.16.27[2001]
obj-uuid@ncacn_ip_tcp:16.20.16.27[endpoint=2001]
obj-uuid@ncacn_nb_nb:
obj-uuid@ncacn_nb_nb:[100]
obj-uuid@ncacn_np:
obj-uuid@ncacn_np:[\\pipe\\p3,Security=impersonation static true]
obj-uuid@ncacn_np:\\\\marketing[\\pipe\\p2\\p3\\p4]
obj-uuid@ncacn_np:\\\\marketing[endpoint=\\pipe\\p2\\p3\\p4]
obj-uuid@ncacn_np:\\\\sales
obj-uuid@ncacn_np:\\\\sales[\\pipe\\p1,Security=identification dynamic true]
obj-uuid@ncalrpc:
obj-uuid@ncalrpc:[object1_name_demonstrating_that_these_can_be_lengthy]
obj-uuid@ncalrpc:[object2_name,Security=anonymous static true]
obj-uuid@ncacn_vns_spp:server@group@org[500]
obj-uuid@ncacn_dnet_nsp:took[elf_server]
obj-uuid@ncacn_dnet_nsp:took[endpoint=elf_server]
obj-uuid@ncadg_ip_udp:128.10.2.30
obj-uuid@ncadg_ip_udp:maryos.microsoft.com[1025]
obj-uuid@ncadg_ipx: ~0000000108002B30612C[5000]
obj-uuid@ncadg_ipx:printserver
obj-uuid@ncacn_spx:annaw[4390]
obj-uuid@ncacn_spx:~0000000108002B30612C
 

A string binding contains the character representation of a binding handle and sometimes portions of a binding handle. String bindings are convenient for representing portions of a binding handle, but they can't be used for making remote procedure calls. They must first be converted to a binding handle by calling the RpcBindingFromStringBinding routine.

Additionally, a string binding does not contain all of the information from a binding handle. For example, the authentication information, if any, associated with a binding handle is not translated into the string binding returned by calling the RpcBindingToStringBinding routine.

During the development of a distributed application, servers can communicate their binding information to clients using string bindings to establish a client-server relationship without using the endpoint-map database or name-service database. To establish such a relationship, use the function RpcBindingToStringBinding to convert one or more binding handles from a binding-handle vector to a string binding, and provide the string binding to the client.

See Also

RpcBindingFromStringBinding, RpcBindingToStringBinding, RpcEpRegister