3.3.4.1 Poke (Opnum 0)

  • Article

The Poke method is used by a secondary partner to request the primary partner session initiation. The parameter values specified in the call identify both participants.

 HRESULT Poke(
   [in] handle_t hBinding,
   [in] SESSION_RANK sRank,
   [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, range(sizeof(BIND_INFO_BLOB),sizeof(BIND_INFO_BLOB))] 
     DWORD dwcbSizeOfBlob,
   [in, size_is(dwcbSizeOfBlob)] unsigned char rguchBlob[]
 );

hBinding: The RPC primitive binding handle of the partner receiving the call, as specified in [C706] part Binding Handle.

sRank: The session rank of the partner making the call. This parameter MUST be set to 0x02 (SRANK_SECONDARY).

Value

Meaning

SRANK_SECONDARY

0x02

The caller is the secondary participant.

pszCalleeUuid: A string containing the primary partner's contact identifier (CID) in the form of a GUID. The contact identifier (CID) MUST match the CID in the primary partner'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 on which the caller's instance of the MSDTC Connection Manager: OleTx Transports Protocol is running. This value is used by the primary participant to establish the RPC binding handle for its subsequent call to BuildContext. This MUST be a NetBIOS name. For NetBIOS, see [NETBEUI], [RFC1001], and [RFC1002].

pszUuidString: The string form of the caller's contact identifier (CID) in the form of a GUID. This contact identifier (CID) identifies the caller's instance of the MSDTC Connection Manager: OleTx Transports Protocol. It MUST match the CID in the caller's local name object, and MUST be formatted into a string. This value is used by the primary participant to establish the RPC binding handle for its subsequent call to BuildContext.

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

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

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 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.2. Standard errors are defined in [MS-ERREF] section 2.2.

Return value/code

Description

0x00000000

ERROR_STATUS

The return value indicates success.

0x80000123

E_CM_SERVER_NOT_READY

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

0x80070057

E_INVALIDARG

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

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.

The opnum field value for this method is zero.

Poke SHOULD NOT be invoked on a secondary partner. If it is, the secondary partner SHOULD respond by making a Poke callback on the primary partner.<18> In this case, the parameters to the Poke call MUST be calculated from the incoming parameters and the secondary partner's local name object; specifically, the pszCalleeUuid parameter MUST be set to the value of the pszUuidString parameter; the pszHostName parameter MUST be the Hostname field of the secondary partner's local name object; and the pszUuidString parameter MUST be the string form of the CID field of the secondary partner's local name object. The secondary partner MAY return from the Poke method before this call has completed.

When Poke is invoked on a primary partner, the primary partner MUST construct a name object using the host name specified in the pszHostName parameter, the contact identifier (CID) specified in the pszUuidString parameter, and the RPC protocols specified in the grbitComProtocols field of the BIND_INFO_BLOB structure.

The primary partner MUST use this name object to check whether or not an existing session with a matching name object already exists in the session table.

If an existing session is found, the primary partner MUST check the State field of the session object.

  • If the value is set to Connecting, the existing session will be used during the rest of the call.

  • Otherwise, the primary partner MUST return an implementation-specific error code.<19>

If an existing session is not found, a new session object MUST be created and added to the session table. The new session object MUST be initialized with the created name object. An RPC binding handle to the secondary partner MUST be created and stored in the session object. For binding handles, see [C706]. The State field MUST be set to Connecting.

At this point, the primary partner does not have to wait until the entire process is completed. It SHOULD return success from the method, while it continues to perform the following actions.<20>

After identifying a valid existing session or initializing a new session object and adding it to the session table, the primary partner MUST attempt to call either the BuildContextW method or the BuildContext method on the secondary partner with the RPC binding handle stored in the session object. For details on making BuildContext calls to a partner, see section 3.3.4.2 and section 3.4.6.1.1.

To determine whether the secondary partner supports BuildContextW, the primary partner calls BuildContextW on the secondary partner and waits for a return value.

If the secondary partner does not support the BuildContextW method, the primary partner MUST call the BuildContext method.

If the secondary partner does support the BuildContextW method, the primary partner MUST NOT call the BuildContext method. During this call, the secondary partner will make a nested synchronous callback to the primary partner to complete the session establishment. See section 3.4.6.1.1.

If the call completes successfully, the primary partner MUST examine the State field of the session object; if the value is "Confirming Connection", it MUST set the state of the session object to Active and cancel the Session Setup timer associated with that session object.

If the call completes unsuccessfully, the primary partner SHOULD behave according to the error code that was returned:

  • If the error code is 0x80000712 (E_CM_VERSION_SET_NOTSUPPORTED), or 0x800000173 (E_CM_S_PROTOCOL_NOT_SUPPORTED), or it retried the nested call for more than the number of times specified in the Session Setup Retry Count ADM element, or if the State field of the session object is not "Confirming Connection", the primary partner MUST remove the session object from the session table and clean it up. For instructions on cleaning up a session object, see section 3.2.1.3.

  • If the error code is ox800000123 (E_CM_SERVER_NOT_READY) or 0x000006BB (RPC_S_SERVER_TOO_BUSY), or any other implementation-specific error code, the primary partner SHOULD retry the call for the number of times specified in the Session Setup Retry Count ADM element.