Share via

3.1.4.9 R_QMGetObjectProperties (Opnum 10)

  • Article

A client calls R_QMGetObjectProperties to retrieve properties from a private queue located on a supporting server.

 HRESULT R_QMGetObjectProperties(
   [in] handle_t hBind,
   [in] struct OBJECT_FORMAT* pObjectFormat,
   [in, range(1, 128)] DWORD cp,
   [in, size_is(cp )] DWORD aProp[],
   [in, out, size_is(cp )] PROPVARIANT apVar[]
 );

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

pObjectFormat:  MUST point to an OBJECT_FORMAT structure which identifies an existing local private queue on the supporting server. MUST NOT be NULL. The ObjType member of the structure MUST be 0x00000001. The pQueueFormat member MUST NOT be NULL.

cp:  MUST be set to the size (in elements) of the arrays aProp and apVar. The arrays aProp and apVar MUST have an identical number of elements and MUST contain at least one element.

aProp:  MUST be an array of queue property identifiers of properties to retrieve. Each element MUST specify a value from the queue property identifiers table defined in [MS-MQMQ] section 2.3.1. Each element MUST specify the queue property identifier for the corresponding queue property value at the same element index in apVar. MUST contain at least one element.

apVar: MUST contain at least one element. On input, each element MUST be initialized to the appropriate VARTYPE for the associated property specified by the same element in aProp, or VT_NULL. Otherwise, the server SHOULD return the failure HRESULT MQ_ERROR_PROPERTY (0xc00e0002).<36> On success, the server MUST populate the elements of this array with property values for the properties identified by the corresponding elements of aProp.

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT,<37><38> 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 identified by the pObjectFormat parameter.

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

  • Copy the values of the Queue ADM element instance attributes indicated by aProp into apVar. Queue property identifiers and their associated Queue ADM element attributes are specified in section 3.1.1.12.

  • Return MQ_OK (0x00000000).