3.3.4.8 BuildContextW (Opnum 7)

  • Article

The BuildContextW method is equivalent in all ways to the BuildContext method, except that its string parameters are encoded in UTF-16. The MIDL syntax of the method is as follows.

 HRESULT BuildContextW(
   [in] handle_t hBinding,
   [in] SESSION_RANK sRank,
   [in] BIND_VERSION_SET BindVersionSet,
   [in, string, range(GUID_LENGTH, GUID_LENGTH)] 
     wchar_t pwszCalleeUuid[],
   [in, string, range(1, MAX_COMPUTERNAME_LENGTH+1)] 
     wchar_t pwszHostName[],
   [in, string, range(GUID_LENGTH, GUID_LENGTH)] 
     wchar_t pwszUuidString[],
   [in, string, range(GUID_LENGTH, GUID_LENGTH)] 
     wchar_t pwszGuidIn[],
   [in, out, string, range(GUID_LENGTH, GUID_LENGTH)] 
     wchar_t pwszGuidOut[],
   [in, out] BOUND_VERSION_SET* pBoundVersionSet,
   [in, range(sizeof(BIND_INFO_BLOB), sizeof(BIND_INFO_BLOB))] 
     DWORD dwcbSizeOfBlob,
   [in, size_is(dwcbSizeOfBlob)] unsigned char rguchBlob[],
   [out] PPCONTEXT_HANDLE ppHandle
 );

hBinding: RPC primitive binding handle, as specified in [C706] part 3.

sRank: The rank of the caller.

Value

Meaning

SRANK_PRIMARY

0x01

The caller is the primary partner in this session.

SRANK_SECONDARY

0x02

The caller is the secondary partner in this session.

BindVersionSet: A BIND_VERSION_SET structure that contains the minimum and maximum versions supported by the partner.

pwszCalleeUuid: The string form of the callee's contact identifier (CID). The contact identifier (CID) MUST match the contact identifier (CID) in the callee's local name object and MUST be formatted into a string.

pwszHostName: The string form of the caller's host name. This host name identifies the machine in which the caller's instance of the MSDTC Connection Manager: OleTx Transports Protocol is running. This MUST be a NetBIOS name. For NetBIOS, see [NETBEUI], [RFC1001], and [RFC1002].

pwszUuidString: The string form of the caller's contact identifier (CID). This contact identifier (CID) identifies the caller's instance of the MSDTC Connection Manager: OleTx Transports Protocol. This MUST match the contact identifier (CID) in the caller's local name object and MUST be formatted into a string.

pwszGuidIn: A string form of a UUID that represents a unique identifier for this bind attempt. The UUID MUST be formatted into a string.

pwszGuidOut: A string form of a UUID that represents a unique identifier for this bind attempt. On input, the pwszGuidOut parameter MUST be set to 00000000-0000-0000-0000-000000000000. On return, if the bind attempt is ultimately successful, the pwszGuidOut parameter MUST be equal to the value of the pszGuidIn parameter. Otherwise, if the bind attempt is ultimately unsuccessful, the pwszGuidOut parameter MUST be set to 00000000-0000-0000-0000-000000000000 on return.

pBoundVersionSet: A pointer to a BOUND_VERSION_SET structure. When the method is called, every field of the BOUND_VERSION_SET structure MUST be initialized to zero. This parameter receives a BOUND_VERSION_SET on successful completion and also on return.

dwcbSizeOfBlob: The count in bytes of the size of the binding info structure. This parameter MUST be set to the size of BIND_INFO_BLOB, 8.

rguchBlob: A byte array that contains a BIND_INFO_BLOB structure.

ppHandle: On successful return, an RPC context handle (see [C706]) that correlates with the session object created by, or referenced by, this method.

Return Values: This method MUST return zero (0x00000000) on success. On failure, it MUST return either 0x80000172 (E_CM_VERSION_SET_NOTSUPPORTED) or an implementation-specific HRESULT. A client SHOULD distinguish between 0x80000172 and other error codes, as specified in sections 3.3.4.2.1 and 3.3.4.2.2, but MUST NOT depend on implementation-specific failure HRESULT values. From an over-the-wire communication point of view, the client MUST implement only behaviors for the errors described in the following table.

Standard errors are defined in [MS-ERREF] section 4.

Return value/code

Description

0x00000000

ERROR_STATUS

The return value indicates success.

0x80000172

E_CM_VERSION_SET_NOTSUPPORTED

The return value indicates that the callee partner does not support the caller's BindVersionSet parameter and will not execute the requested operation.

0x000006D1

RPC_S_PROCNUM_OUT_OF_RANGE

The return value indicates that the caller does not support this call.

0x80000124

E_CM_S_TIMEDOUT

The return value indicates that the callee timed out while waiting for the caller to complete the bind. This value is returned by a secondary partner to a primary partner if the primary partner does not return from the secondary partner's call to BuildContext within half the amount of time specified in the Session Setup Timer (section 3.2.2.1).

0x000006BB

RPC_S_SERVER_TOO_BUSY

The return value indicates that the partner is too busy to complete this operation. For more information, see [MS-RPCE] section 3.1.1.5.5.

0x80000173

E_CM_S_PROTOCOL_NOT_SUPPORTED

The return value indicates that none of the protocols described in the rguchBlob parameter is supported by the partner.

0x80070057

E_INVALIDARG

The return value indicates that one of the specified arguments is invalid.

The following table describes the possible implementation-specific errors that SHOULD be returned by this method.

Return value/code

Description

0x80000120

E_CM_SESSION_DOWN

In a scenario where the value of the sRank parameter is SRANK_SECONDARY, if BuildContextW is called and an existing session object is not found, the call SHOULD return this value.<30>

0x80000123

E_CM_SERVER_NOT_READY

The session object is not in the Connecting state.<31>

When a partner calls BuildContextW on another partner, an error code of RPC_S_PROCNUM_OUT_OF_RANGE means that the callee does not support BuildContextW.