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.
ObjectUUID@ProtocolSequence:NetworkAddress[Endpoint,Option]
Parameters
ObjectUUID
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 Registering Interfaces.
ProtocolSequence
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 protocols specified in Protocol Sequence Constants.
NetworkAddress
Network address of the system to receive remote procedure calls.
Note:
The following protocol sequences are not supported as of Windows XP:
The format and content of the network address depend on the specified protocol sequence as follows.
| Protocol sequence | Network address | Examples |
|---|---|---|
| ncacn_nb_tcp | Computer name | myserver |
| ncacn_nb_ipx | Computer name | myserver |
| ncacn_nb_nb | Computer name | myserver |
| ncacn_ip_tcp | Four-octet Internet address, or host name. If the IPv6 network stack is installed, IPv6 is fully supported and an IPv6 address is also accepted. | 128.10.2.30 anynode.microsoft.com |
| ncacn_np | Server name (leading double backslashes are optional) | myserver \\myotherserver |
| ncacn_spx | IPX Internet address, or server name | ~0000000108002B30612C myserver |
| ncacn_dnet_nsp | Area and node syntax | 4.120 |
| ncacn_at_dsp | Computer 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 | Server name | myserver |
| ncacn_http | Internet address (either four-octet or friendly name, or local 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 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 computer when you use the ncalrpc protocol sequence, however doing so is completely unnecessary.
Endpoint
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 following Endpoint/Option Table.
Option
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 following Endpoint/Option table.
| 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 | Named pipe. Name must start with "\\pipe". | \\pipe\\pipename | Security |
| 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, HttpConnection option |
| ncadg_ip_udp | Internet port number. | 1025 | None |
| ncadg_ipx | Integer between 1 and 65535. | 5000 | None |
| ncalrpc | String specifying application or service name. The string cannot include any backslash characters. | my_printer | Security |
The HttpConnectionOption option name, supported for the ncacn_http protocol sequence, takes the following value.
| Option name | Value |
|---|---|
| HttpConnectOption | UseHttpProxy |
The HttpConnectionOption allows you to direct RPC s behavior when making HTTP connections. The UseHttpProxy value instructs RPC to route its traffic through the Http proxy at all times, including when the client has the Internet Options set in Internet Explorer to Bypass proxy server for local addresses. This option directs the client to forcefully connect to the RPC proxy through the Http proxy. This speeds up the time to establish a connection since it bypasses any delay searching for the RPC server directly prior to using the HTTP proxy.
If this HttpConnectionOption option is used and Internet Explorer on the client is not configured to use that Http proxy, connections may fail with RPC_S_INVALID_NETWORK_OPTIONS.
HttpConnectOption=UseHttpProxy
For more information about the HttpConnectionOption, see Using HTTP as an RPC Transport.
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 | Changes in the client security identity are seen by the server when the server uses transport security. This is the default mode for LRPC (ncalrpc) transport level security, and for local named pipe (ncacn_np) transport level security. |
| False | Effective = FALSE; all token privileges settings, including those set to OFF, are included in the token on the server and can be enabled by the server. Privileges are relevant for same-machine RPC calls only. |
| Identification | The server has information about the client but cannot impersonate. |
| Impersonation | The server can act on behalf of the client within the local system (transport-level security does not support delegation). |
| Static | Changes in the client security identity are not seen by the server when the server uses transport security. This is the only mode available to remote named pipe (ncacn_np) transport level security. The identity of the caller is saved during the first remote procedure call on that binding handle, not at the time the binding handle is created. |
| True | Effective = TRUE; only token privileges settings set to ON are included in the token on the server. Privileges set to OFF cannot be turned on by the server if this option is used. Privileges are relevant for same-machine RPC calls only. |
For more information about security options, Security.
Remarks
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 member.
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 (\\).
A string binding contains the character representation of a binding handle and occasionally 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 RpcBindingFromStringBinding.
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.
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.
Examples
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.microsoft.com[2225]
obj_uuid@ncacn_http:major7.microsoft.com[,HttpProxy=proxysvr:80,
RpcProxy=websvr1.microsoft.com:80]
obj_uuid@ncacn_http:major7.microsoft.com[,HttpProxy=proxysvr:80,
RpcProxy=websvr1.microsoft.com:80,HttpConnectOption=UseHttpProxy]
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
Related topics
Using HTTP as an RPC Transport
Source: Microsoft Learn / Windows Win32 documentation by Microsoft and contributors. Documentation licensed CC BY 4.0. Code samples are covered by the MIT License. Converted from Markdown, with links normalized and embedded media omitted.
