Windows API Reference

RpcBindingCreate Function

Defined in: Rpcrt4.dll

The RpcBindingCreate function creates a binding handle for the specified protocol sequence and endpoint.

Syntax

RPC_STATUS RpcBindingCreate(
      [in] handle_t      ObjectUuid,
      [in] unsigned char *ProtocolSequence,
      [in] unsigned char *NetworkAddress,
      [in] unsigned char *Endpoint,
      [in] unsigned char *Options,
      [out] RPC_BINDING_HANDLE *BindingHandle
    );
    

Parameters

• ObjectUuid
  A pointer to an UUID that identifies the object to bind to. Can be NULL.
• ProtocolSequence
  A pointer to a null-terminated string that contains the protocol sequence to use for the binding. The protocol sequence specifies the transport protocol and, optionally, the network. For example, "ncacn_ip_tcp".
• NetworkAddress
  A pointer to a null-terminated string that contains the network address of the server. This parameter is optional and can be NULL.
• Endpoint
  A pointer to a null-terminated string that contains the endpoint on the server. This parameter is optional and can be NULL.
• Options
  A pointer to a null-terminated string that contains options for the binding. This parameter is reserved and must be NULL.
• BindingHandle
  A pointer to a variable of type RPC_BINDING_HANDLE that receives the RPC binding handle.

Return Value

The function returns RPC_S_OK on success, or one of the following error codes on failure:

• RPC_S_INVALID_BINDING: The binding was invalid.
• RPC_S_OUT_OF_MEMORY: There was not enough memory to complete the operation.
• RPC_S_INVALID_STRING_EXPECTED: The provided string parameter was invalid.
• RPC_S_UNKNOWN_PRINCIPAL: The specified principal was unknown.

Remarks

The RpcBindingCreate function is used to create a client-side binding handle. This handle represents a connection to a remote procedure call server. The function takes various parameters to specify how the connection should be established, including the protocol sequence, network address, and endpoint.

The ProtocolSequence parameter is crucial and defines the transport layer used for communication. Common examples include:

• "ncacn_ip_tcp": TCP/IP using connection-oriented communication.
• "ncadg_udpnd": UDP using connectionless communication.
• "ncalrpc": Local RPC, used for interprocess communication on the same machine.

The NetworkAddress and Endpoint parameters are used to locate the server. If they are NULL, the RPC runtime may use default values or rely on other mechanisms like name resolution services.

After successfully creating a binding handle, it should be released using the RpcBindingFree function when it is no longer needed to prevent resource leaks.

Example

#include <windows.h>
#include <rpcdce.h>
#include <stdio.h>

#pragma comment(lib, "rpcrt4.lib")

int main() {
    RPC_STATUS status;
    RPC_BINDING_HANDLE hBinding = NULL;
    unsigned char *pszProtocolSequence = (unsigned char *)"ncacn_ip_tcp";
    unsigned char *pszNetworkAddress = NULL; // Use default or DNS resolution
    unsigned char *pszEndpoint = (unsigned char *)"8080"; // Example endpoint
    unsigned char *pszOptions = NULL;

    printf("Creating binding handle...\n");

    // Create the binding handle
    status = RpcBindingCreate(
        NULL,                 // ObjectUuid (not used for basic binding)
        pszProtocolSequence,
        pszNetworkAddress,
        pszEndpoint,
        pszOptions,
        &hBinding
    );

    if (status == RPC_S_OK) {
        printf("Binding handle created successfully.\n");
        // Now you can use hBinding to make RPC calls
        // For example: RpcStringBindingInvoke, etc.

        // Free the binding handle when done
        status = RpcBindingFree(&hBinding);
        if (status == RPC_S_OK) {
            printf("Binding handle freed successfully.\n");
        } else {
            fprintf(stderr, "Error freeing binding handle: %lu\n", status);
        }
    } else {
        fprintf(stderr, "Failed to create binding handle. Error: %lu\n", status);
    }

    return 0;
}
        

See Also

RpcBindingFree
RpcStringBindingCompose
RpcBindingFromStringBinding