MQSendMessage

Article
06/30/2006

This 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 NULL or the constant MQ_SINGLE_MESSAGE. NULL indicates that the message is not sent as part of a transaction. Messages sent as a single message transaction must be sent to a transactional queue.

Return Values

MQ_OK
Indicates success.
MQ_ERROR_ACCESS_DENIED
The queue was not opened with MQ_SEND_ACCESS rights.
MQ_ERROR_DTC_CONNECT
MSMQ was unable to connect to MS DTC.
MQ_ERROR_ILLEGAL_FORMATNAME
The 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_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_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 from within a transaction to read a message from a nontransactional queue.
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.

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

The PROPID_M_AUTH_LEVEL property can only be MQMSG_AUTH_LEVEL_NONE.

When a message is sent to an OutFRS queue, PROPID_M_DEST_QUEUE is supported providing it uses the format name of an actual target queue.

The Windows CE implementation of MSMQ does not support the following properties and return MQ_ERROR_PROPERTY if specified:

PROPID_M_XACT_STATUS_QUEUE
PROPID_M_XACT_STATUS_QUEUE_LEN
PROPID_M_SIGNATURE
PROPID_M_SIGNATURE_LEN
PROPID_M_SENDERID_LEN
PROPID_M_SENDERID_TYPE
PROPID_M_SENDERID
PROPID_M_SENDER_CERT_LEN
PROPID_M_SENDER_CERT
PROPID_M_SECURITY_CONTEXT
PROPID_M_PROV_TYPE
PROPID_M_PROV_NAME_LEN
PROPID_M_PROV_NAME
PROPID_M_PRIV_LEVEL
PROPID_M_HASH_ALG
PROPID_M_ENCRYPTION_ALG
PROPID_M_DEST_SYMM_KEY
PROPID_M_DEST_SYMM_KEY_LEN
PROPID_M_CONNECTOR_TYPE
PROPID_M_AUTHENTICATED

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.
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.

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 nontransactional 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 transactional messages, the message is saved on the source machine where it originated.

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 NULL), the hDestinationQueue parameter must refer to a transactional queue.

If the send operation is part of a transaction (pTransaction is not set to r NULL), the hDestinationQueue parameter must refer to a transactional queue. As part of a transaction, messages are not sent until Commit is called.

Transaction objects cannot be reused after you commit to or abort the transaction. If you release the transaction object without calling Commit or Abort, the transaction is aborted for you.

Responding to Messages

The sending application can request a response by providing the format name of a response queue when it sends the message. The format name is specified in the PROPID_M_RESP_QUEUE property when the message is sent.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	2.0 and later. Versions prior to 2.12 require the MSMQ add-on pack.	Mq.h	Mq.h	Msmqrt.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

Last updated on Tuesday, July 13, 2004

MQSendMessage

Additional resources