Allocating Memory when Retrieving Queue Properties

  • Article

 

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

When retrieving queue properties, Message Queuing stores the value returned for each property or a pointer to a buffer containing the value returned in the union member of an MQPROPVARIANT structure. When the union member stores a pointer to a buffer for a wide-character string or a GUID, space must be allocated for the property value returned outside the MQPROPVARIANT structure. For example, space must be allocated before the label of a queue (PROPID_Q_LABEL) can be retrieved. This space is allocated based on the property identifier stored in the aPropID array and the type indicator stored in the vt field of the MQPROPVARIANT element of the aPropVar array for each property. For most queue properties, the vt field can contain the specific type indicator stipulated for the property or VT_NULL. However, VT_NULL is required if the type indicator of the queue property is VT_LPWSTR.

Specifying the Type Indicator

Unless the type indicator of the queue property is VT_LPWSTR, your application can specify the type indicator stipulated for the property. In this case, the application is responsible for allocating any corresponding buffers when needed. In the following example, the vt field is set to VT_CLSID (the type indicator stipulated for PROPID_Q_INSTANCE) and the puuid field (the union field) contains the address of the allocated buffer.

CLSID InstanceBuffer;  
aPropID[i] = PROPID_Q_INSTANCE;  
aPropVar[i].vt = VT_CLSID;  
aPropVar[i].puuid = &guidInstanceBuffer;  
i++;

Specifying VT_NULL

When VT_NULL is specified in the vt field, Message Queuing automatically changes the type indicator to the specific type indicator for the property and allocates memory, if needed, for a buffer for the returned value. In the following example, the vt field is set to VT_NULL.

aPropID[i] = PROPID_Q_LABEL;  
aPropVar[i].vt = VT_NULL;  
i++;

When Message Queuing allocates a buffer for a returned value (when VT_NULL is specified in the vt field), it is the application's responsibility to free the memory using the MQFreeMemory function after the buffer is no longer needed.