A client calls R_QMGetTmWhereabouts to obtain transaction manager whereabouts, as specified in [MS-DTCO], from the supporting server. The whereabouts enable callers to generate exported transaction cookies, which are required to enlist the supporting server's resource manager (RM) in an external transaction.

 HRESULT R_QMGetTmWhereabouts(
   [in] handle_t hBind,
   [in, range(0,131072)] DWORD cbBufSize,
   [out, size_is(cbBufSize)] unsigned char* pbWhereabouts,
   [out] DWORD* pcbWhereabouts
 );

hBind:  MUST be set to an RPC binding handle as described in [MS-RPCE] section 2.

cbBufSize:  MUST be set to the byte length of the buffer pointed to by pbWhereabouts. If this value is 0x00000000, the server MUST ignore the pbWhereabouts parameter.

pbWhereabouts:  On success, points to an array of bytes containing a Distributed Transaction Coordinator (DTC) SWhereabouts structure, as specified in [MS-DTCO] section 2.2.5.11.

pcbWhereabouts:  On success, or ifMQ_ERROR_USER_BUFFER_TOO_SMALL (0xc00e0028) is returned, pcbWhereabouts points to a DWORD containing the byte length of the SWhereabouts structure retrieved from the DTC; otherwise, this parameter MUST be ignored.

Return Values: On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT. The client MUST treat all failure HRESULTs identically and disregard all out-parameter values, with the following exception:

If cbBufSize is less than the size of the SWhereabouts structure returned by the DTC, the server MUST return  MQ_ERROR_USER_BUFFER_TOO_SMALL (0xc00e0028).

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

This method is invoked at the dynamically assigned endpoint returned by the R_QMGetRTQMServerPort method when IP_HANDSHAKE (0x00000000) or IPX_HANDSHAKE (0x00000002) is the interface specified by the fIP parameter.

When processing this call, the server MUST:

• If input parameter values violate the constraints specified above, the server MUST take no further action and return a failure HRESULT.

• Raise the Obtaining Extended Whereabouts Using CONNTYPE_TXUSER_EXTENDEDWHEREABOUTS event as specified in [MS-DTCO] section 3.3.4.10 to obtain an SWhereabouts structure from the DTC.

• If the server successfully retrieves the SWhereabouts structure from the DTC, but the size of the buffer provided by the caller (as indicated by the cbBufSize parameter) is too small to contain the entire SWhereabouts structure, the server MUST take the following actions:

  • The server MUST ignore the pbWhereabouts pointer.

  • The server MUST set the pcbWhereabouts parameter to the size of the SWhereabouts structure retrieved from the DTC.

  • The server MUST return MQ_ERROR_USER_BUFFER_TOO_SMALL (0xc00e0028). This return value indicates to the caller that a larger buffer is required for this function to succeed.

• If any other error occurs, the server MUST return a failure HRESULT.

• Place the entire SWhereabouts structure retrieved from the DTC into the pbWhereabouts buffer provided by the caller. The server MUST also return the byte length of the SWhereabouts structure in the pcbWhereabouts parameter.

• Return MQ_OK (0x00000000).