MQSendMessage

Article
10/19/2016

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

The MQSendMessage function sends a message to the queue corresponding to the handle hDestinationQueue. If this handle is obtained by opening queues using a distribution list format name, a multiple-element format name, or a multicast address format name (introduced in MSMQ 3.0), this function sends the message to all the queues referenced by the format name. For more information, see Multiple-Destination Messaging.

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 an ITransaction interface, a constant, or NULL.

Transaction object can be obtained internally from Message Queuing (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. This constant cannot be used to send a message to a transactional queue.

MQ_MTS_TRANSACTION

Instructs Message Queuing to verify that a COM+ object is running and that the current COM+ object is participating in a transaction. If Message Queuing finds that the application is running in the context of a COM+ (Component Services) transaction, the message is sent within the current COM+ transaction. Otherwise, the message is sent outside of a transaction. For more information, see COM+ Transactions.

MQ_SINGLE_MESSAGE

Specifies that the message is sent in a single-message transaction. Messages sent in a single-message transaction must be sent to a transactional 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

The message was placed in an outgoing queue ready for delivery to its destination. Information on errors that occur after the message is placed in an outgoing queue is provided by acknowledgment messages. For more information on error handling using acknowledgment messages, see Acknowledgment Messages.

MQ_ERROR_ACCESS_DENIED (0xC00E0025)

The queue was not opened with a request for MQ_SEND_ACCESS rights.

MQ_ERROR_BAD_SECURITY_CONTEXT (0xC00E0035)

The security context structure (PROPID_M_SECURITY_CONTEXT) is corrupted.

MQ_ERROR_CERTIFICATE_NOT_PROVIDED (0xC00E006D)

The message contains a request for authentication, but no certificate was attached to it or the security context attached to it does not include a certificate.

MQ_ERROR_CORRUPTED_INTERNAL_CERTIFICATE (0xC00E002D)

(Only in MSMQ 1.0.) The internal certificate provided by Message Queuing is corrupted. Register the internal certificate again using MSMQ Control Panel.

MQ_ERROR_CORRUPTED_PERSONAL_CERT_STORE (0xC00E0031)

The Microsoft® Internet Explorer personal certificate store is corrupted.

MQ_ERROR_CORRUPTED_SECURITY_DATA (0xC00E0030)

The operating system encountered an error when calling one of the cryptographic (CryptoAPI) functions.

MQ_ERROR_COULD_NOT_GET_USER_SID (0xC00E0036)

Message Queuing could not retrieve the SID for setting PROPID_M_SENDERID from the thread access token.

MQ_ERROR_DTC_CONNECT (0xC00E004C)

Message Queuing was unable to connect to MS DTC.

MQ_ERROR_ILLEGAL_FORMATNAME (0xC00E001E)

Format name specified in PROPID_M_ADMIN_QUEUE or PROPID_M_RESP_QUEUE is illegal.

MQ_ERROR_INSUFFICIENT_RESOURCES (0xC00E0027)

There are insufficient resources to complete operation (for example, an attempt was made to send a message containing more than 4 MB of data).

Note

In MSMQ 4.0, all messages contain additional internal headers that are not present in MSMQ 3.0 messages. The maximum size for an MSMQ 4.0 message is slightly less than 4 MB. If you try to send a message that exceeds the maximum size, MQ_ERROR_INSUFFICIENT_RESOURCES (0xC00E0027) will be returned.

MQ_ERROR_INVALID_CERTIFICATE (0xC00E002C)

The external 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 (0xC00E0007)

The queue handle specified in hDestinationQueue is not valid.

MQ_ERROR_INVALID_PARAMETER (0xC00E0006)

One or more of the input parameters are not valid (for MSMQ 1.0, this error is returned if authentication is requested but there is no internal certificate registered).

Note

MQSendMessage will return MQ_ERROR_INVALID_PARAMETER if you try to send a transactional message, with a PROPID_M_JOURNAL property of MQMSG_DEADLETTER (that is, with negative source journaling enabled), to a distribution list or multi-queue format name. To correct this, either send the message to a single queue at a time, or disable negative source journaling.

MQ_ERROR_MESSAGE_STORAGE_FAILED (0xC00E002A)

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 (0xC00E002F)

No internal certificate is registered, or the registered certificate is corrupted.

MQ_ERROR_PROPERTY (0xC00E0002)

One or more properties resulted in an error.

MQ_ERROR_SERVICE_NOT_AVAILABLE (0xC00E000B)

The Message Queuing service is not available.

MQ_ERROR_STALE_HANDLE (0xC00E0056)

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 (0xC00E0050)

(Only in MSMQ 1.0 and MSMQ 2.0.) Transaction error. Either the message is sent as part of a transaction and the destination queue is a nontransactional queue, or the message is not sent as part of a transaction and the destination queue is a transactional queue. In MSMQ 3.0, the loss of transactional messages sent to nontransactional queues or of nontransactional messages sent to transactional queues is reported in negative acknowledgment messages.

MQ_ERROR_TRANSACTION_ENLIST (0xC00E0058)

Message Queuing could not enlist in the transaction.

MQ_ERROR_UNSUPPORTED_FORMATNAME_OPERATION (0xC00E0020)

An attempt was made to send an encrypted message using a queue handle that was created by opening the destination queue with a direct format name.

MQ_INFORMATION_PROPERTY (0x400E0001)

One or more of the properties resulted in a warning even though the function completed.

Remarks

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

The PROPID_M_BODY property is a CAUB structure that contains the message body. The cElems member of this structure indicates the size of the message body.

All message properties can be attached to a message. Some are attached by Message Queuing, and others can be attached by the sending application. For a complete list of all the message properties, see Message Properties.

When sending messages, you should always specify the body type of the message that is being sent. Set PROPID_M_BODY_TYPE to one of the Variant types supported by Message Queuing. These types are listed in the PROPID_M_BODY_TYPE reference topic.

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.

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.

When sending authenticated messages or impersonating another user, you must call MQGetSecurityContextEx and MQSendMessage in the same user context.

When a message is sent to a remote private queue designated by a private format name in domain mode, access to the directory service is needed to convert the computer GUID to a computer name. The directory service is also queried before a message is placed in a remote private queue designated by a private format name, but offline operation is supported.

In MSMQ 3.0, when a message is sent to a local nontransactional queue within a transaction or a message is sent to a local transactional queue outside of a transaction, the send operation succeeds, but the message is not placed in the destination queue. If the sending application requests negative acknowledgment messages and specifies an administration queue, Message Queuing returns a negative acknowledgment message of the MQMSG_CLASS_NACK_NOT_TRANSACTIONAL_MSG or MQMSG_CLASS_NACK_NOT_TRANSACTIONAL_Q class, respectively.

In MSMQ 1.0 and MSMQ 2.0, the send operation fails, and the error code MQ_ERROR_TRANSACTION_USAGE is returned.

If the send operation is part of a transaction (pTransaction is not set to MQ_NO_TRANSACTION or 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 or abort the transaction. If you release the transaction object without calling Commit or Abort, the transaction is aborted for you.

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 a response queue.

•If PROPID_M_ADMIN_QUEUE and PROPID_M_ACKNOWLEDGE are passed to MQSendMessage, Message Queuing can return acknowledgment messages back to the administration queue specified. Acknowledgment messages underlie the standard mechanism in Message Queuing for reporting errors that occur during message delivery.

PROPID_M_RESP_QUEUE can also 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.

Equivalent COM Method

When using COM components, you can send a message to one or more destination queues by calling the MSMQMessage.Send method.

For information on	See
How Message Queuing sets the body type of a message	Message Body Types
Tracking messages using source journaling	Source Journaling
How Message Queuing authenticates messages	Message Authentication
How Message Queuing responds to messages	Response Messages
Message Queuing Transactions	Transactions

Example Code

The following code examples are included in Using Message Queuing.

For an example of	See
Sending a message to a queue	C/C++ Code Example: Sending Messages to a Destination Queue
Sending messages that request positive or negative source journaling	C/C++ Code Example: Requesting Source Journaling (Positive or Negative)
Sending a message that requests an acknowledgment from Message Queuing	C/C++ Code Example: Requesting Acknowledgment Messages
Sending a message that requests a response message from the receiving application.	C/C++ Code Example: Requesting Response Messages
Sending a messages that requests encryption	C/C++ Code Example: Requesting Encryption
Using a single message (internal) transaction to send a message	C/C++ Code Example: Sending a Message Using a Single-Message Transaction
Using a COM+ transaction to send a message	C/C++ Code Example: Sending a Message Using a COM+ Transaction
Using a Message Queuing internal transaction to send a message	C/C++ Code Example: Sending a Message Using an Internal Transaction
Using an MS DTC external transaction to send a message	C/C++ Code Example: Sending a Message Using an MS DTC External Transaction

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Mq.h.

Library: Use Mqrt.lib.