Share via

3.3.4.7 PokeW (Opnum 6)

  • Article

The PokeW method is equivalent in all ways to the Poke method except that its string parameters are encoded in UTF-16.

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

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

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.

pwszCalleeUuid: The string form of the primary partner contact identifier (CID). The contact identifier (CID) MUST match the contact identifier (CID) in the primary partner 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; it MUST match the contact identifier (CID) in the caller's local name object and MUST be formatted into a string.

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 that contains a BIND_INFO_BLOB structure.

Return Values: This method MUST return zero (0x00000000) on success. On failure, it MUST return an implementation-specific HRESULT. A client MUST NOT depend on implementation-specific failure HRESULT values. From an over-the-wire communication point of view, the client MUST implement only a behavior for the case when the call succeeds and another behavior for the case when the call does not succeed, (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.

0x000006D1

RPC_S_PROCNUM_OUT_OF_RANGE

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

0x80000123

E_CM_SERVER_NOT_READY

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

0x80070057

E_INVALIDARG

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

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.

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