MQSendMessage

The MQSendMessage function sends a message to the queue corresponding to the handle hDestinationQueue.

HRESULT APIENTRY MQSendMessage(
  QUEUEHANDLE hDestinationQueue,  
  MQMSGPROPS *pMessageProps,      
  ITransaction *pTransaction      
);

Parameters

hDestinationQueue

[in] Handle to the queue where you want to send the message.

pMessageProps

[in] Pointer to an MQMSGPROPS structure describing the message to send.

pTransaction

[in] Must be a pointer to a transaction object, a constant, or NULL.

Transaction object can be obtained internally from MSMQ (by calling MQBeginTransaction) or externally from Microsoft® Distributed Transaction Coordinator (MS DTC).

Constants include:

MQ_NO_TRANSACTION: Specifies that the call is not part of a transaction.
MQ_MTS_TRANSACTION: Specifies that the current Microsoft Transaction Server (MTS) transaction is used to send the message.
MQ_SINGLE_MESSAGE: Sends a single message as a transaction. Messages sent as a single-message transaction must be sent to a transaction queue.
MQ_XA_TRANSACTION: Specifies that the call is part of an externally coordinated, XA-compliant transaction.

NULL indicates the message is not sent as part of a transaction.

Return Values

MQ_OK: Indicates success.
MQ_ERROR_ACCESS_DENIED: The queue was not opened with MQ_SEND_ACCESS rights.
MQ_ERROR_BAD_SECURITY_CONTEXT: The security context buffer (PROPID_M_SECURITY_CONTEXT) is corrupted.
MQ_ERROR_CORRUPTED_INTERNAL_CERTIFICATE: The internal security certificate provided by MSMQ is corrupted. Register the internal certificate again using MSMQ Control Panel.
MQ_ERROR_CORRUPTED_PERSONAL_CERT_STORE: The Microsoft® Internet Explorer personal certificate store is corrupted.
MQ_ERROR_CORRUPTED_SECURITY_DATA: The operating system encountered an error when calling one of the cryptographic functions (CryptoAPI).
MQ_ERROR_COULD_NOT_GET_USER_SID: MQSendMessage could not retrieve the user identifier specified by PROPID_M_SENDERID.
MQ_ERROR_DTC_CONNECT: MSMQ was unable to connect to MS DTC.
MQ_ERROR_ILLEGAL_FORMATNAME: Format name specified in PROPID_M_ADMIN_QUEUE or PROPID_M_RESP_QUEUE is illegal.
MQ_ERROR_INSUFFICIENT_RESOURCES: Insufficient resources to complete operation (for example, an attempt was made to send a message whose body contained more than 4 MB of data). Operation failed.
MQ_ERROR_INVALID_CERTIFICATE: The external security certificate passed in PROPID_M_SENDER_CERT is not valid. The certificate is corrupted or not placed in the Microsoft Internet Explorer personal certificate store.
MQ_ERROR_INVALID_HANDLE: The queue handle specified in hDestinationQueue is not valid.
MQ_ERROR_MESSAGE_STORAGE_FAILED: A recoverable message (PROPID_M_DELIVERY is set to MQMSG_DELIVERY_RECOVERABLE) could not be stored on the local computer.
MQ_ERROR_NO_INTERNAL_USER_CERT: The internal security certificate provided by MSMQ is not registered. Register the internal certificate using MSMQ Control Panel.
MQ_ERROR_PROPERTY: One or more properties resulted in an error.
MQ_ERROR_SERVICE_NOT_AVAILABLE: Cannot connect to the Queue Manager.
MQ_ERROR_STALE_HANDLE: The specified queue handle was obtained in a previous session of the Queue Manager service. Close the queue and open it again to obtain a fresh handle.
MQ_ERROR_TRANSACTION_USAGE: Transaction error. An attempt was made to open a remote queue for read access from within a transaction, or an attempt was made to read a message from a non-transaction queue from within a transaction.
MQ_INFORMATION_PROPERTY: One or more of the properties resulted in a warning even though the function completed.

Remarks

All message properties can be attached to a message. Some are attached by MSMQ, and others can be attached by the sending application. For a complete list of all the message properties, see Sending Messages to a Queue.

Note Each MSMQ message can have no more than 4 MB of data.

The PROPID_M_BODY property is a CAUI1 structure that contains the message body. The caui1.cElems field of this structure represents the size of the message body.

The sending application can receive two types of messages in response to the messages it sends:

If PROPID_M_RESP_QUEUE is passed to MQSendMessage, the receiving application can send application-defined response messages back to the specified queue. For information on response queues, see Response Queues.
If PROPID_M_ADMIN_QUEUE and PROPID_M_ACKNOWLEDGE are passed to MQSendMessage, MSMQ can return acknowledgment messages back to the administration queue.

You can use the same queue for the response queue (PROPID_M_RESP_QUEUE) and administration queue (PROPID_M_ADMIN_QUEUE).

To save a copy of a message after it is successfully sent, set PROPID_M_JOURNAL to MQMSG_JOURNAL or MQMSG_JOURNAL | MQMSG_DEADLETTER and attach it to the message. This tells MSMQ to save a copy of the message in the sending computer's machine journal after the message is successfully sent. For more information, see Journal Queues.

To save a copy of a message if it does not reach its destination, set PROPID_M_JOURNAL to MQMSG_DEADLETTER or MQMSG_JOURNAL | MQMSG_DEADLETTER and attach it to the message. This tells MSMQ to save a copy of the message in the dead letter queue. For non-transaction messages, the message is saved on the computer that could not deliver the message. This could be the sending machine or any MSMQ server used to route the message to its destination. For transaction messages, the message is saved on the source machine where it originated. For information on dead letter queues, see Dead Letter Queues.

When impersonating another user, MQGetSecurityContext must be called. Typically, MQGetSecurityContext is only needed when sending authenticated messages.

PROPID_M_RESP_QUEUE can be used to send the format name of a private queue to another application. This is typically done when the sending application wants to make a private queue available to other applications.

Sending Messages Within a Transaction

If the send is part of a transaction (pTransaction is not set to MQ_NO_TRANSACTION or NULL), the hDestinationQueue parameter must refer to a transaction queue.

During a transaction, MSMQ performs the following tasks:

The message's priority property (PROPID_M_PRIORITY) is set to 0.
The message's delivery property (PROPID_M_DELIVERY) is set to MQMSG_DELIVERY_RECOVERABLE.
The time-to-be-received and time-to-reach-queue timers are set by the first message sent in the transaction. All subsequent messages use the first message's timer settings.
As part of a transaction, messages are not sent until the Commit time frame. For information on lTransaction::Commit, see the Platform SDK.

Requesting a Response

The sending application can pass PROPID_M_RESP_QUEUE to MQSendMessage to indicate that it expects a response from the receiving application. The messages returned to the response queue specified by this property are application-defined.

Examples

For examples of using MQSendMessage, see:

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in mq.h.
  Import Library: Use mqrt.lib.
  Unicode: Defined only as Unicode.