3.13.4.1.3 LookupQueue (Opnum 9)

  • Article

The LookupQueue method is received by the server in an RPC_REQUEST packet. In response, the server MUST return a pointer to an IMSMQQueueInfos4 interface pointer. The returned interface allows the client to enumerate over a collection of Queues. The queue query represents search criteria based on any combination of Queue.Identifier, Queue.Type, Queue.Label, Queue.CreateTime, Queue.ModifyTime, or Queue.MulticastAddress properties.

 HRESULT LookupQueue(
   [in, optional] VARIANT* QueueGuid,
   [in, optional] VARIANT* ServiceTypeGuid,
   [in, optional] VARIANT* Label,
   [in, optional] VARIANT* CreateTime,
   [in, optional] VARIANT* ModifyTime,
   [in, optional] VARIANT* RelServiceType,
   [in, optional] VARIANT* RelLabel,
   [in, optional] VARIANT* RelCreateTime,
   [in, optional] VARIANT* RelModifyTime,
   [in, optional] VARIANT* MulticastAddress,
   [in, optional] VARIANT* RelMulticastAddress,
   [out, retval] IMSMQQueueInfos4** ppqinfos
 );

QueueGuid: Pointer to a VARIANT containing a BSTR that contains a string representation of a Queue.Identifier. The string MUST adhere to the following format, specified using ABNF.

 guid = "{" dword-part "-" word-part "-" word-part "-"
                   2byte-part "-" 6byte-part "}"
 dword-part = 2word-part
 word-part  = 2byte-part
 byte-part  = 2hex-digit
 hex-digit  = %x30-39 / %x41-46 / %x61-66

ServiceTypeGuid: Pointer to a VARIANT containing a BSTR that contains a string representation of a Queue.Type. The string MUST adhere to the same format defined for QueueGuid.

Label: Pointer to a VARIANT containing a BSTR that is used to query against Queue.Label.

CreateTime: Pointer to a VARIANT that contains a DATE that is used to query against Queue.CreateTime.

ModifyTime: Pointer to a VARIANT that contains a DATE that is used to query against Queue.ModifyTime.

RelServiceType: Pointer to a VARIANT that contains a VT_I4 that specifies a logical comparison operator against the ServiceTypeGuid input parameter. This parameter corresponds to the RELOPS (section 2.2.2.20) enum. If this value is not specified by the client, the server MUST use the default value REL_EQ (0x00000001) in place of the unspecified value.

RelLabel: Pointer to a VARIANT that contains a VT_I4 that specifies a logical comparison operator against the Label input parameter. This parameter corresponds to the RELOPS enum. If this value is not specified by the client, the server MUST use the default value REL_EQ (0x00000001) in place of the unspecified value.

RelCreateTime: Pointer to a VARIANT that contains a VT_I4 that specifies a logical comparison operator against the CreateTime input parameter. This parameter corresponds to the RELOPS enum. If this value is not specified by the client, the server MUST use the default value REL_EQ (0x00000001) in place of the unspecified value.

RelModifyTime: Pointer to a VARIANT that contains a VT_I4 that specifies a logical comparison operator against the ModifyTime input parameter. This parameter corresponds to the RELOPS enum. If this value is not specified by the client, the server MUST use the default value REL_EQ (0x00000001) in place of the unspecified value.

MulticastAddress: Pointer to a VARIANT that contains a BSTR that is used to query against the Queue.MulticastAddress. If this value is not specified or an empty string is passed in, the server MUST create a query restriction that matches all queues that do not have a MulticastAddress property defined.

RelMulticastAddress: Pointer to a VARIANT that contains a VT_I4 that specifies a logical comparison operator against the MulticastAddress input parameter. This parameter corresponds to the RELOPS enum. If this value is not specified by the client, the server MUST use the default value REL_EQ (0x00000001) in place of the unspecified value.

ppqinfos: Pointer to an IMSMQQueueInfos4 interface pointer, which upon successful completion contains a pointer to a MSMQQueueInfos instance containing the query definition that can be used by the client to enumerate a collection of Queues that match the specified criteria.

Return Values: The method MUST return S_OK (0x00000000) on success or an implementation-specific error HRESULT on failure.

When processing this call, the server MUST follow these guidelines:

  • Define queryFilter as an array of attribute-filter expressions as described in [MS-MQDMPR] section 3.1.7.1.20.

  • Define the operation variables RelServiceTypeOp, RelLabelOp, RelCreateTimeOp, RelModifyTimeOp, and RelMulticastAddressOp. These operation variables are related to the input parameter that matches the variable name (RelServiceTypeOp is related to RelServiceType and so on).

  • Set each of the operation variables to the appropriate attribute-filter expression operator, which maps to the RELOPS enum contained in its related input parameter.

  • Add attribute-filter expressions to queryFilter as follows:

    • If QueueGuid is not unspecified (VT_ERROR):

      • Add: " Identifier" EQUALS QueueGuid.

    • If ServiceTypeGuid is not unspecified (VT_ERROR) AND RelServiceType is not REL_NOP:

      • Add: " Type" RelServiceTypeOpServiceTypeGuid.

    • If Label is not unspecified (VT_ERROR) AND RelLabel is not REL_NOP:

      • Add: " Label" RelLabelOpLabel.

    • If CreateTime is not unspecified (VT_ERROR) AND RelCreateTime is not REL_NOP:

      • Add: " CreateTime" RelCreateTimeOpCreateTime.

    • If ModifyTime is not unspecified (VT_ERROR) AND RelModifyTime is not REL_NOP:

      • Add: " ModifyTime" RelModifyTimeOpModifyTime.

    • If MulticastAddress is not unspecified (VT_ERROR) AND RelMulticastAddress is not REL_NOP:

      • Add: " MulticastAddress" RelMulticastAddressOpMulticastAddress.

  • Create and initialize a new MSMQQueueInfos instance object, and pass queryFilter to the initialization of the MSMQQueueInfos instance object. For information about the initialization process, refer to section 3.14.3. These values are referred to as query constraints.

  • If initialization of the MSMQQueueInfos object instance succeeds:

    • Obtain a pointer to the IMSMQQueueInfos4 interface by calling IUnknown:QueryInterface (see section 3.1) on the newly-created MSMQQueueInfos object with the interface identifier of IMSMQQueueInfos4.

    • Set the ppqinfos output parameter to the previously-obtained IMSMQQueueInfos4 interface pointer.

  • Else:

    • Return an error HRESULT, and take no further action.