HOWTO: When MQFreeMemory Must Be Used (201258)

MORE INFORMATION

The only properties for which MSMQ allocates memory are as follows:

• PROPID_Q_INSTANCE
• PROPID_Q_TYPE
• PROPID_Q_LABEL
• PROPID_Q_PATHNAME
• The PROPID_QM_XXX properties

MQFreeMemory is only designed to free memory allocated by MSMQ, so using MQFreeMemory on any other property (which the user MUST allocate) causes undefined results.

MSMQ does not allocate memory for any of the MSMQ message properties (PROPID_M_XXX) or the queue properties (PROPID_Q_XXX) not specified above. When you use one of those message or queue properties, you must always specifically allocate the memory you want use. You need to allocate memory when the PROPVARIANT type is one of the following:

• VT_CLSID
• VT_LPWSTR
• VT_VECTOR | VT_UI
• VT_VECTOR | VT_LPWSTR

Other types (such as VT_UI4) are stored within the PROPVARIANT and do not require special allocation.

When you try to retrieve the queue or QueueManager properties mentioned above (for example, MQGetQueueProperties), you can pass a PROPVARIANT of type VT_NULL. MSMQ will allocate the memory for the returned property. Then you have to call MQFreeMemory on that property's data.

In most cases you can pass VT_NULL as the PROPVARIANT type for any property where memory allocation is not necessary, such as a property of type VT_UI4. At this time, known exceptions to this rule include the following:

• PROPID_M_VERSION
• PROPID_M_TIME_TO_BE_RECEIVED
• PROPID_M_TIME_TO_REACH_QUEUE

In the case of a VT_LPWSTR or VT_VECTOR | VT_UI property where the property size is not a fixed size (consult the MSMQ Server Online Help for that property to find out), a length property is associated with the property of unknown size. For example, PROPID_M_BODY has a length property of PROPID_M_BODY_SIZE, and PROPID_M_LABEL has an associated length property PROPID_M_LABEL_LEN. You can retrieve the length property separately and use that value as the required size of the allocated property.