Application-Initiated Binding

Applications bind to the server and obtain a handle that is used by the stubs to make remote procedure calls. When the client is finished making remote calls, the application can unbind from the server and invalidate the handle. A client application that manages its own binding and handles can obtain a handle in two ways:

• Call RpcBindingFromStringBinding
• Call the name-service functions RpcNsBindingImportBegin, RpcNsBindingImportNext, and RpcNsBindingImportDone

When the client explicitly calls RpcBindingFromStringBinding, the client must supply the following information to identify the server:

• The globally unique identifier (GUID) or UUID of the object.
• The transport type to communicate over, such as named pipes or TCP/IP.
• The network address, which is the server name for the named-pipe transport.
• The endpoint, which contains the pipe name for the named-pipe transport.

(The object UUID and the endpoint information are optional.)

The client or client stub communicates this identifying information to the RPC run-time library by means of a data structure called the string binding, which combines these elements using a specified syntax.

In the following examples, the pszNetworkAddress parameter and other parameters that include embedded backslashes can appear strange at first glance. Because the backslash is an escape character in the C programming language, two backslashes are needed to represent each single literal backslash character. The string-binding data structure must contain four backslash characters to represent the two literal backslash characters that precede the server name. The following example shows eight backslashes so four literal backslash characters will appear in the string-binding data structure after processing by the sprintf function. For example:

/* client application */

char * pszUuid = "6B29FC40-CA47-1067-B31D-00DD010662DA";
char * pszProtocol = "ncacn_np";
char * pszNetworkAddress = "\\\\\\\\servername";
char * pszEndpoint = "\\\\pipe\\\\pipename";
char * pszString;

int len = 0;

len  = sprintf(pszString, "%s", pszUuid);
len += sprintf(pszString + len, "@%s:", pszProtocolSequence);
if (pszNetworkAddress != NULL)
    len += sprintf(pszString + len, "%s", pszNetworkAddress);
len += sprintf(pszString + len, "[%s]", pszEndpoint);
 

In the following example, the string binding appears as:

6B29FC40-CA47-1067-B31D-00DD010662DA@ncacn_np:\\\\servername[\\pipe\\pipename]
 

The client then obtains the binding handle by calling RpcBindingFromStringBinding:

RPC_BINDING_HANDLE hBinding;
 
status = RpcBindingFromStringBinding(pszString, &hBinding);
...
 

A convenience function, RpcStringBindingCompose, assembles the object UUID, protocol sequence, network address, and endpoint into the correct syntax for the call to RpcBindingFromStringBinding. You do not have to worry about putting the ampersand, colon, and the various components for each protocol sequence in the right place; you just supply the strings as parameters to the function. The run-time library even allocates the memory needed for the string binding. For example:

char * pszNetworkAddress = "\\\\server";
char * pszEndpoint = "\\pipe\\pipename";
status = RpcStringBindingCompose(
            pszUuid,
            pszProtocolSequence,
            pszNetworkAddress,
            pszEndpoint,
            pszOptions,
            &pszString);
...
status = RpcBindingFromStringBinding(
            pszString,
            &hBinding);
...
 

Another convenience function, RpcBindingToStringBinding, takes a binding handle as input and produces the corresponding string binding.