3.1.4.14 R_SetUserAcknowledgementClass (Opnum 14)

  • Article

The R_SetUserAcknowledgementClass method sets the acknowledgment class property of a message in the queue. This allows marking the message as rejected.<30> This method MUST be called subsequent to calls to R_StartTransactionalReceive and R_EndTransactionalReceive (Opnum 15) (section 3.1.4.15) and before the transaction is committed or aborted.

 HRESULT R_SetUserAcknowledgementClass(
   [in] handle_t hBind,
   [in] QUEUE_CONTEXT_HANDLE_NOSERIALIZE phContext,
   [in] ULONGLONG LookupId,
   [in] USHORT usClass
 );

hBind: MUST be an RPC binding handle parameter, as specified in [MS-RPCE] section 2.

phContext: MUST be set by the client to a QUEUE_CONTEXT_HANDLE_NOSERIALIZE handle representing the queue containing the message on which to set the acknowledgment class. The handle MUST have been returned by the server in the pphQueue output parameter of a prior call to the R_OpenQueue (Opnum 2) (section 3.1.4.2) method with the dwAccess parameter set to MQ_RECEIVE_ACCESS and MUST NOT have been closed through a prior call to the R_CloseQueue (Opnum 3) (section 3.1.4.3) method. This value MUST NOT be NULL.

LookupId: MUST be set by the client to the lookup identifier of the message on which to set the acknowledgment class.

usClass: The acknowledgment class to set. It MUST be set by the client to one of the following values.

Value

Meaning

0x0000

No-op. No change is made to the acknowledgment class.

MQMSG_CLASS_NACK_RECEIVE_REJECTED

0xC004

Marks the message as rejected.

Return Values: On success, this method MUST return MQ_OK (0x00000000).

If an error occurs, the server MUST return a failure HRESULT, and the client MUST treat all failure HRESULTs identically.

MQ_OK (0x00000000)

MQ_ERROR_INVALID_HANDLE (0xC00E0007)

MQ_ERROR_TRANSACTION_USAGE (0xC00E0050)

MQ_ERROR_MESSAGE_NOT_FOUND (0xC00E0088)

Exceptions Thrown:

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

When processing this call, the server MUST do the following:

  • Find the corresponding OpenQueueDescriptor ADM element instance fOpenQueueDescriptor by comparing the phContext parameter with the Handle ADM attribute for all OpenQueueDescriptor ADM element instances maintained by the local QueueManager ADM element instance.

  • If not found, return a failure HRESULT.

  • Find the corresponding MessagePosition ([MS-MQDMPR] section 3.1.1.11) ADM element instance fMessagePosition by comparing the LookupId parameter with rMessagePosition.MessageReference.Identifier for each MessagePosition ADM element instance rMessagePosition in the fOpenQueueDescriptor.QueueReference.MessagePositionList.

  • If not found, then return MQ_ERROR_MESSAGE_NOT_FOUND (0xC00E0088).

  • Find the corresponding TransactionOperation ADM element instance fTransactionOperation by comparing the MessagePosition ADM element instance fMessagePosition with rTransaction.TransactionalOperationCollection.MessagePositionReference for each Transaction ADM element instance rTransaction in the TransactionCollection ADM attribute of the local QueueManager ADM element instance.

  • If not found, then return MQ_ERROR_TRANSACTION_USAGE (0xC00E0050).

  • If the usClass parameter is not 0x0000, set the DequeueReason ADM attribute of the TransactionOperation ADM element instance fTransactionOperation to NackReceiveRejected, as specified in [MS-MQDMPR] section 3.1.1.12.

  • Return MQ_OK (0x00000000).