3.3.4.2 BuildContext (Opnum 1)

The BuildContext method is invoked by either a primary partner or a secondary partner. When invoked by a primary partner, the BuildContext method requests that the secondary partner begin the next step of establishing a session. When invoked by a secondary partner, the BuildContext method requests that the primary partner complete the establishment of the session.

 HRESULT BuildContext(
   [in] handle_t hBinding,
   [in] SESSION_RANK sRank,
   [in] BIND_VERSION_SET BindVersionSet,
   [in, string, range(GUID_LENGTH,GUID_LENGTH)] 
     unsigned char pszCalleeUuid[],
   [in, string, range(1,MAX_COMPUTERNAME_LENGTH+1)] 
     unsigned char pszHostName[],
   [in, string, range(GUID_LENGTH,GUID_LENGTH)] 
     unsigned char pszUuidString[],
   [in, string, range(GUID_LENGTH,GUID_LENGTH)] 
     unsigned char pszGuidIn[],
   [in, out, string, range(GUID_LENGTH,GUID_LENGTH)] 
     unsigned char pszGuidOut[],
   [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 for the connection, as specified in [C706] part 3.

sRank: The session rank of the partner making the call. It MUST be one of the following values.

Value	Meaning
SRANK_PRIMARY 1	The caller is the primary partner in this session.
SRANK_SECONDARY 2	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, as specified by the Minimum Level 1 Version Number, Maximum Level 1 Version Number, Minimum Level 2 Version Number, Maximum Level 2 Version Number, Minimum Level 3 Version Number, and Maximum Level 3 Version Number ADM elements (see section 3.2.1.1).

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

pszHostName: 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].

If this is the primary partner call, this value is used by the called secondary partner to establish the RPC binding handle for its corresponding call to BuildContext.

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

If this is the primary participant's call, this value is used by the called secondary participant to establish the RPC binding handle for its corresponding call to BuildContext.

pszGuidIn: A string form of a GUID that represents a unique identifier for this bind attempt. The GUID MUST be formatted as a string.

For the primary participant's call to BuildContext, this is a new GUID generated by the primary partner to uniquely identify the session. For the secondary partner's call back to the primary partner, this MUST be the parameter value from the primary partner's call to the secondary partner.

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

pBoundVersionSet: A pointer to a BOUND_VERSION_SET structure. This structure is filled in by the callee. If any error is returned, this structure MUST be filled with zeros before returning. On successful completion, the caller receives a BOUND_VERSION_SET on return.

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

rguchBlob: A byte array containing the BIND_INFO_BLOB structure specifying the supported transport protocols. This information is used to build the RPC binding for the reverse connection.

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

Return Values: This method MUST return zero (0x00000000) on success. On failure, it MUST return either one of the values described in the following table of return values or an implementation-specific HRESULT. A client MUST NOT depend on implementation-specific failure HRESULT values. For more information about how the client SHOULD behave based on the possible return values, see section 3.4.6.1.1. Standard errors are defined in [MS-ERREF] section 2.2.

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.
0x80000124 E_CM_S_TIMEDOUT	The return value indicates that the callee timed out while waiting for the caller to complete the bind. This 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 of the Session Setup Timer (section 3.2.2.1) interval.
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 are supported by the partner.
0x80070057 E_INVALIDARG	The return value indicates that one of the specified arguments is invalid.

The following table of return values describes the possible 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 BuildContext is called and an existing session object is not found, the call SHOULD return this value.<21>
0x80000123 E_CM_SERVER_NOT_READY	The session object is not in the Connecting state.<22>

The opnum field value for this method is 1. For more information, see [C706].

This method has different effects depending on the value of the sRank parameter.

For the structure and sequence of data on the wire, see [C706] Transfer Syntax Network Data Representation (NDR) topics.