Edit

RpcBindingCreateA function (rpcdce.h)

  • Article

The RpcBindingCreate function creates a new fast RPC binding handle based on a supplied template.

Syntax

RPC_STATUS RpcBindingCreateA(
  [in]           RPC_BINDING_HANDLE_TEMPLATE_V1_A *Template,
  [in, optional] RPC_BINDING_HANDLE_SECURITY_V1_A *Security,
  [in, optional] RPC_BINDING_HANDLE_OPTIONS_V1    *Options,
  [out]          RPC_BINDING_HANDLE               *Binding
);

Parameters

[in] Template

RPC_BINDING_HANDLE_TEMPLATE structure that describes the binding handle to be created by this call. This data may be overwritten during the call, so the API does not maintain a reference to this data. The caller must free the memory used by this structure when the API returns.

[in, optional] Security

RPC_BINDING_HANDLE_SECURITY structure that describes the security options for this binding handle. This data may be overwritten during the call, so the API does not maintain a reference to this data. The caller must free the memory used by this structure when the API returns.

This parameter is optional. If this parameter is set to NULL, the default security settings for RPC_BINDING_HANDLE_SECURITY will be used.

[in, optional] Options

RPC_BINDING_HANDLE_OPTIONS structure that describes additional options for the binding handle. This data may be overwritten during the call, so the API does not maintain a reference to this data. The caller must free the memory used by this structure when the API returns.

This parameter is optional. If this parameter is set to NULL, the default options for RPC_BINDING_HANDLE_OPTIONS will be used.

[out] Binding

RPC_BINDING_HANDLE structure that contains the newly-created binding handle. If this function did not return RPC_S_OK, then the contents of this structure are undefined. For non-local RPC calls, this handle must be passed to RpcBindingBind.

Return value

This function returns RPC_S_OK on success; otherwise, an RPC_S_* error code is returned. For information on these error codes, see RPC Return Values.

Return code Description
RPC_S_OK
 The binding handle was successfully created.
RPC_S_CANNOT_SUPPORT
 An obsolete feature of RPC was requested for this binding handle.
Note  The only supported protocol sequences for this API is ncalrpc; choosing another protocol sequence results in the return of this error status code.
 
 
Note  For a list of valid error codes, see RPC Return Values.
 

Remarks

The RPC binding handle returned by this API can be used with any other functions that accepts a binding handle as a parameter.

However, before any calls can be made on the binding handle, RpcBindingBind must be called to make the binding handle available for remote calls. The RpcBindingCreate API does not touch the network or attempt to communicate with the RPC server -- rather, it simply builds an internal data structure based on the values supplied in the template. A successful return does not indicate that the RPC server is available, accessible, or correctly specified.

Note

The rpcdce.h header defines RpcBindingCreate as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps | UWP apps]
Minimum supported server Windows Server 2008 [desktop apps | UWP apps]
Target Platform Windows
Header rpcdce.h (include Rpc.h)
Library Rpcrt4.lib
DLL Rpcrt4.dll

See also

RPC_BINDING_HANDLE

RpcBindingBind