HOWTO: When MQFreeMemory Must Be Used

ID: Q201258

The information in this article applies to:

Microsoft Message Queue Server version 1.0

SUMMARY

You can use MQFreeMemory for the following MSMQ queue properties only:

PROPID_Q_INSTANCE
PROPID_Q_TYPE
PROPID_Q_LABEL
PROPID_Q_PATHNAME
All of the PROPID_QM properties (such as PROPID_QM_SITE_ID and PROPID_QM_CONNECTION)

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.

REFERENCES

MSMQ SDK Help; search on: "MQGetMachineProperties"; "MQGetQueueProperties"; "MQReceiveMessage";

Additional query words:


Keywords          : kbMSMQ100 
Version           : winnt:1.0
Platform          : winnt 
Issue type        : kbhowto

Last Reviewed: January 22, 1999