MQSendMessage

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function sends a message to the queue corresponding to the handle hDestinationQueue.

Syntax

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 Value

• MQ_OK
  Indicates success.

• MQ_ERROR_ACCESS_DENIED
  The queue was not opened with MQ_SEND_ACCESS rights.

• MQ_ERROR_DTC_CONNECT
  MSMQ could not 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.

  To obtain a fresh handle, close the queue and open it again.

• 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 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 embedded implementation of MSMQ does not support the following properties and returns 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 the 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.

You can use PROPID_M_RESP_QUEUE 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.

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

See Also

Reference

PROPID_M_ACKNOWLEDGE
PROPID_M_ADMIN_QUEUE
PROPID_M_AUTH_LEVEL
PROPID_M_BODY
PROPID_M_DELIVERY
PROPID_M_DEST_QUEUE
PROPID_M_JOURNAL
PROPID_M_RESP_QUEUE
MQMSGPROPS