PROPVARIANT

The PROPVARIANT structure is a general structure used to store property values. It is used for the elements of the aPropVar array used in MQQUEUEPROPS, MQMSGPROPS, and MQQMPROPS; the prval array of MQPROPERTYRESTRICTION; and as a parameter in MQLocateNext.

Property values are tagged values, where the tag is the type indicator (an integer value) passed as an instance of PROPVARIANT (a data type that will be part of Automation in the future). MSMQ uses a similar structure (included here for reference) along with some other Automation types and definitions on which this structure relies. The complete definition of the Automation PROPVARIANT structure can be found in the header file ‹oleext.h› and in the additional header files it includes.

For information on how property structures work together, see Property Structures.

struct    MQtagPROPVARIANT  {
    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      bool;      /* VT_BOOL               */
             long              lVal;      /* VT_I4                 */
             ULONG             ulVal;     /* VT_UI4                */
             SCODE             scode;     /*                       */
             DATE              date;      /* VT_DATE               */
             CLSID  _RPC_FAR  *puuid;     /* VT_CLSID              */
             BLOB              blob;      /* VT_BLOB               */
             LPOLESTR          bstrVal;   /*                       */
             LPSTR             pszVal;    /* VT_LPSTR              */
             LPWSTR            pwszVal;   /* VT_LPWSTR             */
             CAUI1             caub;      /* VT_VECTOR | VT_UI1    */
             CAI2              cai;       /* VT_VECTOR | VT_I2     */
             CAUI2             caus;      /* VT_VECTOR | VT_UI2    */
             CABOOL            cabool;    /* VT_VECTOR | VT_BOOL   */
             CAI4              cal;       /* VT_VECTOR | VT_I4     */
             CAUI4             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;   /*                       */
            };                      
};

typedef struct MQtagPROPVARIANT PROPVARIANT;
 

Members

vt

The type indicator of the property. The valid indicators for the VT field are a subset of the Automation VARENUM enumeration 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 MSMQ.

union

Specifies the value of the property. Depending on the type identifier specified by VT, the corresponding member of the union holds the value of the property.

Remarks

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.

CA prefixed members of the union (caub through capropvar) are constructs used to pass buffers as counted arrays.

For example, CAUI1 is a counted array of bytes:

typedef struct tagCAUI1 {
    ULONG cElems;               /* Byte Counter                  */
    unsigned char *pElems;      /* Pointer to a buffer of bytes  */
} CAUI1;
 

QuickInfo

  Windows NT: Requires version 4.0 or later.
  Windows: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in objidl.h.

See Also

MQLocateNext, MQMSGPROPS, MQPROPERTYRESTRICTION, MQQMPROPS, MQQUEUEPROPS