3.1.4.11 R_QMObjectPathToObjectFormat (Opnum 12)

  • Article

A client calls R_QMObjectPathToObjectFormat to determine a format name for a queue identified by a given path name.

 HRESULT R_QMObjectPathToObjectFormat(
   [in] handle_t hBind,
   [in, string] const WCHAR* lpwcsPathName,
   [in, out] struct OBJECT_FORMAT* pObjectFormat
 );

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

lpwcsPathName:  MUST be a pointer to a null-terminated path name string, as defined by [MS-MQMQ] section 2.1.1. The path name MUST identify an existing private queue located on a supporting server.

pObjectFormat:  MUST be a pointer to an OBJECT_FORMAT structure, as specified in section 2.2.3.5. On success, this structure MUST be populated with a direct format name or private format name for the queue identified by lpwcsPathName. This specification does not mandate the process through which a server produces a format name for a given path name.

On input, pObjectFormat MUST NOT be NULL, the ObjType member MUST be 0x00000001, and the m_qft member MUST be QUEUE_FORMAT_TYPE_UNKNOWN (0x00000000).

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT,<41><42> and the client MUST treat all failure HRESULTs identically. Additionally, if a failure HRESULT is returned, the client MUST disregard all out-parameter values.

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:

  • Determine if input parameter values violate constraints specified above. If an invalid parameter is detected, the server MUST take no further action and return a failure HRESULT.

  • Locate a Queue ([MS-MQDMPR] section 3.1.1.2) ADM element instance in the QueueCollection attribute of the server's LocalQueueManager ([MS-MQDMPR] section 3.1.1) ADM element instance where the value of the Pathname attribute of the Queue ADM element instance matches the lpwcsPathName parameter.

  • If no entry is located, return a failure HRESULT.

  • Set the pObjectFormat parameter to a private format name, as specified in [MS-MQMQ] section 2.1.4, which resolves to the Queue ADM element instance located preceding.

  • Return MQ_OK (0x00000000).