Share via

3.1.7.15 Send Administration Acknowledgment

  • Article

Administration acknowledgment messages are system-generated UserMessage Packets ([MS-MQMQ] section 2.2.20) that are sent to administration queues specified in the packets. An administration acknowledgment can indicate whether a message has reached its destination queue or whether the message has been retrieved. When a message is rejected, an administration acknowledgment message can indicate the reason for its loss.

The Send Administration Acknowledgment event MUST be generated with the following arguments:

  • iReceivedUserMessagePacket: The UserMessage Packet ([MS-MQMQ] section 2.2.20) that triggers the sending of the acknowledgment. Can be NULL if iReceivedMessage is provided.

  • iMessageClass: A message class identifier as specified in [MS-MQMQ] section 2.2.18.1.6.

  • iReceivedMessage: Optional. A Message ([MS-MQDMPR] section 3.1.1.12) ADM element instance that triggers the sending of the acknowledgment. If this argument is supplied, iReceivedUserMessagePacket is ignored.

Return Value:

  • None.

The protocol MUST perform the following actions to process this event:

  • If iReceivedMessage is provided and the iReceivedMessage.AdministrationQueueFormatName ADM attribute is empty, take no further action. If iReceivedMessage is not provided and the iReceivedUserMessagePacket.UserHeader.Flags.AQ field is 0x0, take no further action.

  • If iMessageClass is one of MQMSG_CLASS_NACK_BAD_DST_Q, MQMSG_CLASS_NACK_BAD_ENCRYPTION, MQMSG_CLASS_NACK_BAD_SIGNATURE, MQMSG_CLASS_NACK_ACCESS_DENIED, or MQMSG_CLASS_NACK_UNSUPPORTED_CRYPTO_PROVIDER, as defined in [MS-MQMQ] section 2.2.18.1.6, and the SendInsecureNacks ADM element is FALSE, take no further action.

  • Create a Message ([MS-MQDMPR] section 3.1.1.12) ADM element instance adminAcknowledgment to use as the acknowledgment message.

  • Set the adminAcknowledgment.Class ADM attribute to a value based the iMessageClass argument according to the following table.

    iMessageClass

    enumeration value for adminAcknowledgment.Class

    MQMSG_CLASS_ACK_REACH_QUEUE ([MS-MQMQ] section 2.2.18.1.6)

    AckReachQueue

    MQMSG_CLASS_ACK_RECEIVE ([MS-MQMQ] section 2.2.18.1.6)

    AckReceive

    MQMSG_CLASS_NACK_BAD_DST_Q ([MS-MQMQ] section 2.2.18.1.6)

    NackBadDestQueue

    MQMSG_CLASS_NACK_DELETED ([MS-MQMQ] section 2.2.18.1.6)

    NackPurged

    MQMSG_CLASS_NACK_REACH_QUEUE_TIMEOUT ([MS-MQMQ] section 2.2.18.1.6)

    NackReachQueueTimeout

    MQMSG_CLASS_NACK_Q_EXCEED_QUOTA ([MS-MQMQ] section 2.2.18.1.6)

    NackQueueExceedQuota

    MQMSG_CLASS_NACK_ACCESS_DENIED ([MS-MQMQ] section 2.2.18.1.6)

    NackAccessDenied

    MQMSG_CLASS_NACK_BAD_SIGNATURE ([MS-MQMQ] section 2.2.18.1.6)

    NackBadSignature

    MQMSG_CLASS_NACK_BAD_ENCRYPTION ([MS-MQMQ] section 2.2.18.1.6)

    NackBadEncryption

    MQMSG_CLASS_NACK_NOT_TRANSACTIONAL_Q ([MS-MQMQ] section 2.2.18.1.6)

    NackNotTransactionalQueue

    MQMSG_CLASS_NACK_NOT_TRANSACTIONAL_MSG ([MS-MQMQ] section 2.2.18.1.6)

    NackNotTransactionalMessage

    MQMSG_CLASS_NACK_UNSUPPORTED_CRYPTO_PROVIDER ([MS-MQMQ] section 2.2.18.1.6)

    NackUnsupportedCryptoProvider

    MQMSG_CLASS_NACK_Q_DELETED ([MS-MQMQ] section 2.2.18.1.6)

    NackQueueDeleted

    MQMSG_CLASS_NACK_Q_PURGED ([MS-MQMQ] section 2.2.18.1.6)

    NackQueuePurged

    MQMSG_CLASS_NACK_RECEIVE_TIMEOUT ([MS-MQMQ] section 2.2.18.1.6)

    NackReceiveTimeout

    MQMSG_CLASS_NACK_RECEIVE_REJECTED ([MS-MQMQ] section 2.2.18.1.6)

    NackReceiveRejected

  • Let DestinationForAck be a Unicode string to contain a format name, as defined in [MS-MQMQ] section 2.1, initialized to be empty. If iReceivedMessage is provided, set DestinationForAck to the iReceivedMessage.AdministrationQueueFormatName ADM attribute. If iReceivedMessage is not provided, set DestinationForAck based on the value of the iReceivedUserMessagePacket.UserHeader.Flags.AQ field:

    • If the iReceivedUserMessagePacket.UserHeader.Flags.AQ field is 0x2, set DestinationForAck to a Private Format Name ([MS-MQMQ] section 2.1.4), where ComputerGuid is the value of the iReceivedUserMessagePacket.UserHeader.SourceQueueManager field and the queue is identified by the hexadecimal representation of the PrivateQueueIdentifier field of the PrivateQueueFormatNameId ([MS-MQMQ] section 2.2.18.1.5.1) found in the iReceivedUserMessagePacket.UserHeader.AdminQueue field.

    • If the iReceivedUserMessagePacket.UserHeader.Flags.AQ field is 0x3, set DestinationForAck to a Private Format Name ([MS-MQMQ] section 2.1.4), where ComputerGuid is the value of the iReceivedUserMessagePacket.UserHeader.QueueManagerAddress field and the queue is identified by the hexadecimal representation of the PrivateQueueIdentifier field of the PrivateQueueFormatNameId found in the iReceivedUserMessagePacket.UserHeader.AdminQueue field.

    • If the iReceivedUserMessagePacket.UserHeader.Flags.AQ field is 0x5, set DestinationForAck to a Public Format Name ([MS-MQMQ] section 2.1.3), where QueueGuid is the value of the PublicQueueIdentifier field of the PublicQueueFormatName ([MS-MQMQ] section 2.2.18.1.7.1) found in the iReceivedUserMessagePacket.UserHeader.AdminQueue field.

    • If the iReceivedUserMessagePacket.UserHeader.Flags.AQ field is 0x6, set DestinationForAck to a Private Format Name ([MS-MQMQ] section 2.1.4), where ComputerGuid is the value of the SourceQueueManager field of the  PrivateQueueFormatName ([MS-MQMQ] section 2.2.18.1.7.1) found in the iReceivedUserMessagePacket.UserHeader.AdminQueue field, and the queue is identified by the hexadecimal representation of the PrivateQueueIdentifier field of that PrivateQueueFormatName.

    • If the iReceivedUserMessagePacket.UserHeader.Flags.AQ field is 0x7, set DestinationForAck to the Direct Format Name ([MS-MQMQ] section 2.1.2) that is the value of the DirectFormatName field of the DirectQueueFormatName ([MS-MQMQ] section 2.2.18.1.5.2) found in the iReceivedUserMessagePacket.UserHeader.AdminQueue field.

  • If iReceivedMessage is provided, set the adminAcknowledgment.CorrelationIdentifier ADM attribute to the iReceivedMessage.Identifier ADM attribute. If iReceivedMessage is not provided, construct an OBJECTID ([MS-MQMQ] section 2.2.8) and set the Uniquifier field to the value of the iReceivedUserMessagePacket.UserHeader.MessageID field and the Lineage field to the value of the iReceivedUserMessagePacket.UserHeader.SourceQueueManager field. Set the adminAcknowledgment.CorrelationIdentifier ADM attribute to the constructed OBJECTID.

  • If iReceivedMessage is provided, set the adminAcknowledgment.ResponseQueueFormatName ADM attribute to the iReceivedMessage.DestinationQueueFormatName ADM attribute. If iReceivedMessage is not provided, set the adminAcknowledgment.ResponseQueueFormatName ADM attribute based on the value of the iReceivedUserMessagePacket.UserHeader.Flags.DQ field:

    • If the iReceivedUserMessagePacket.UserHeader.Flags.DQ field is 0x3, set the adminAcknowledgment.ResponseQueue ADM attribute to a Private Format Name ([MS-MQMQ] section 2.1.4), where ComputerGuid is the value of the iReceivedUserMessagePacket.UserHeader.QueueManagerAddress field and the queue is identified by the hexadecimal representation of the PrivateQueueIdentifier field of the PrivateQueueFormatNameId found in the iReceivedUserMessagePacket.UserHeader.DestinationQueue field.

    • If the iReceivedUserMessagePacket.UserHeader.Flags.DQ field is 0x5, set the adminAcknowledgment.ResponseQueue ADM attribute to a Public Format Name ([MS-MQMQ] section 2.1.3), where QueueGuid is the value of the PublicQueueIdentifier field of the PublicQueueFormatName found in the iReceivedUserMessagePacket.UserHeader.DestinationQueue field.

    • If the iReceivedUserMessagePacket.UserHeader.Flags.DQ field is 0x7, set the adminAcknowledgment.ResponseQueue ADM attribute to the direct format name ([MS-MQMQ] section 2.1.2) that is the value of the DirectFormatName field of the DirectQueueFormatName found in the iReceivedUserMessagePacket.UserHeader.DestinationQueue field.

  • If iReceivedMessage is provided, set the adminAcknowledgment.DeliveryGuarantee ADM attribute to the iReceivedMessage.DeliveryGuarantee ADM attribute. If iReceivedMessage is not provided, if the iReceivedUserMessagePacket.UserHeader.Flags.DM flag is set, set the adminAcknowledgment.DeliveryGuarantee ADM attribute to Recoverable; otherwise, set the adminAcknowledgment.DeliveryGuarantee ADM attribute to Express.

  • Set the additional ADM attributes of adminAcknowledgment as shown in the following table.

    ADM Attribute

    Value

    AcknowledgementRequested

    None

    TimeToReachQueue

    0xFFFFFFFF

    TimeToBeReceived

    0xFFFFFFFF

    PositiveJournalingRequested

    FALSE

    NegativeJournalingRequested

    FALSE

    PrivacyLevel

    None

    AuthenticationLevel

    None

  • If iMessageClass is not one of MQMSG_CLASS_ACK_REACH_QUEUE, MQMSG_CLASS_ACK_RECEIVED, or MQMSG_CLASS_NACK_MESSAGE_TOO_LARGE:

    • If iReceivedMessage is provided and the iReceivedMessage.PrivacyLevel ADM attribute is None, set the adminAcknowledgment.Body ADM attribute to the iReceivedMessage.Body ADM attribute.

    • If iReceivedMessage is not provided and the iReceivedUserMessagePacket.SecurityHeader.Flags.EB bit field is not set, set the adminAcknowledgment.Body ADM attribute to the bytes contained in the iReceivedUserMessagePacket.MessagePropertiesHeader.MessageBody field.

  • The protocol MUST generate an Open Queue ([MS-MQDMPR] section 3.1.7.1.5) event with the following arguments:

    • iFormatName := DestinationForAck

    • iRequiredAccess := QueueAccessType.SendAccess

    • iSharedMode := QueueShareMode.DenyNone

  • If the rStatus returned by the Open Queue event is not MQ_OK (0x00000000), the protocol MUST discard adminAcknowledgment; otherwise, the protocol MUST generate an Enqueue Message To An Open Queue ([MS-MQDMPR] section 3.1.7.1.27) event with the following arguments:

    • iOpenQueueDescriptor := the rOpenQueueDescriptor returned by the Open Queue event

    • iMessage := adminAcknowledgment