Allocating Memory when Retrieving Computer 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 computer 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, or it references a counted array of strings or a counted array of unsigned characters, space must be allocated for the property value returned outside the MQPROPVARIANT structure. For example, space must be allocated before the path name of a computer (PROPID_QM_PATHNAME) 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 some computer 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 computer property is VT_LPWSTR, VT_VECTOR | VT_LPWSTR, or VT_VECTOR | VT_UI1.

Specifying the Specific Type Indicator

Unless the type indicator of the computer property is VT_LPWSTR, VT_VECTOR | VT_LPWSTR, or VT_VECTOR | VT_UI1, your application can specify the type indicator stipulated for the property. In this case, the application is responsible for allocating the corresponding buffer when appropriate. In the following example, the vt field is set to VT_CLSID (the type indicator stipulated for PROPID_QM_MACHINE_ID) and the puuid field contains the address of the allocated buffer.

CLSID MachineIdBuffer;  
aPropID[i] = PROPID_QM_MACHINE_ID;  
aPropVar[i].vt = VT_CLSID;  
aPropVar[i].puuid = &guidMachineIdBuffer;  
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 the returned value. In the following example, the vt field is set to VT_NULL.

aPropID[i] = PROPID_QM_PATHNAME;  
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.