MQPROPVARIANT

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 MQROPVARIANT structure is a general structure used to store or reference property values and their data types. It is used to specify the elements of the aPropVar array and for the prval member of the MQPROPERTYRESTRICTION structure.

typedef struct tagMQPROPVARIANT  
{  
    VARTYPE vt;                    /* value tag  */  
    WORD wReserved1;  
    WORD wReserved2;  
    WORD wReserved3;  
    union   {  
             UCHAR             bVal;      /* VT_UI1    */  
             SHORT             iVal;      /* VT_I2     */  
             USHORT            uiVal;     /* VT_UI2    */  
             VARIANT_BOOL      boolVal;   /* VT_BOOL   */  
             LONG              lVal;      /* VT_I4     */  
             ULONG             ulVal;     /* VT_UI4    */  
             ULARGE_INTEGER    uhVal;     /* VT_UI8    */  
             SCODE             scode;     /* VT_ERROR  */  
             DATE              date;      /* VT_DATE   */  
             CLSID _RPC_FAR  * puuid;     /* VT_CLSID  */  
             BLOB              blob;      /* VT_BLOB   */  
             LPOLESTR          bstrVal;   /* VT_BSTR   */  
             LPSTR             pszVal;    /* VT_LPSTR  */  
             LPWSTR            pwszVal;   /* VT_LPWSTR */  
             CAUB              caub;      /* VT_VECTOR | VT_UI1     */  
             CAI               cai;       /* VT_VECTOR | VT_I2      */  
             CAUI              caui;      /* VT_VECTOR | VT_UI2     */  
             CABOOL            cabool;    /* VT_VECTOR | VT_BOOL    */  
             CAL               cal;       /* VT_VECTOR | VT_I4      */  
             CAUL              caul;      /* VT_VECTOR | VT_UI4     */  
             CACLSID           cauuid;    /* VT_VECTOR | VT_CLSID   */  
             CABSTR            cabstr;    /* VT_VECTOR | VT_BSTR    */  
             CALPWSTR          calpwstr;  /* VT_VECTOR | VT_LPWSTR  */  
             CAPROPVARIANT     capropvar; /* VT_VECTOR | VT_VARIANT */  
            };                        
} MQPROPVARIANT;

Members

The type indicator of the property. Most of the valid indicators for the vt field are members or combinations of members of the Automation VARENUM enumerated type (including VT_NULL, VT_I2, VT_I4, VT_LPWSTR, VT_UI1, VT_UI4, VT_CLSID, VT_VECTOR|VT_UI1, VT_VECTOR|VT_LPWSTR ).

wReserved1, wReserved2, wReserved3

Reserved by Message Queuing.

union

Specifies the value of the property. The type indicator specified by vt determines the member of the union that holds the value of the property or a pointer to it.

Remarks

Property values are tagged values, where the tag is the type indicator (an integer value) passed as an instance of VARTYPE.

To specify a property (with the exception of some message properties passed to MQReceiveMessage) and queue properties passed to MQGetQueueProperties, you must know its type indicator and the member of the union associated with the type indicator (both are provided with each property description). For example, to specify the message body in PROPID_M_BODY, the application must set vt to VT_UI1| VT_VECTOR and assign the message body to the caub member of the union.

The ca-prefixed members of the union (caub through capropvar) are structures used to pass buffers as counted arrays. Each structure has two members: an unsigned long specifying the number of elements in the array and a pointer to the buffer that stores the property value.

For example, CAUB is a counted array of bytes:

typedef struct tagCAUB {  
    ULONG cElems;               // Byte counter  
    unsigned char *pElems;      // Pointer to a buffer of bytes  
} CAUB;

In addition to the members that are countered arrays, the puuid, blob, bstrVal, pszVal, and pwszVal members also contain pointers to buffers that store the actual property values. When assigning the values of properties that are passed in buffers, your application must supply the applicable pointers.

When retrieving message and queue manager property values that are stored in buffers, your application must create the applicable buffers and be able to enlarge them when necessary. When retrieving queue property values that are stored in buffers, it is recommended that your application set the type indicator to VT_NULL so that Message Queuing will create the buffer. However, in the case of PROPID_Q_INSTANCE and PROPID_Q_TYPE, your application can also set the type indicator to VT_CLSID and create the buffers required.

When the values of the management properties specified in the MQMGMTPROPS structure are retrieved, Message Queuing creates the buffers needed automatically.

The ULARGE data type of the uhval member is used to specify a 64-bit unsigned integer value. It is defined as follows.

typedef union _ULARGE_INTEGER {   
  struct {  
      DWORD LowPart;  
      DWORD HighPart;   
  };  
  ULONGLONG QuadPart;  
} ULARGE_INTEGER, *PULARGE_INTEGER;

The value of the 64-bit integer is stored in the QuadPart member of the union.

The BLOB data type of the blob member is defined in the wtypes.h header file.

typedef struct tagBLOB {  
    ULONG cbSize;                   // Blob size  
    BYTE __RPC_FAR * pBlobData;     // Pointer to a data buffer  
} BLOB;

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.

MQPROPVARIANT

Members

Remarks

Requirements

See Also

Additional resources