PROPVARIANT helpers #1 - Initialization

  • Article

PROPVARIANTs are easy to misuse. Because the data members are so cryptic, it is easy to get confused or to overlook errors.

To help alleviate these and other problems (including readability), we provide a series of PROPVARIANT helpers for common uses. There are a lot of 'em, so I will split this over several days. Here's the first batch which deal with initializing a PROPVARIANT with a particular type of data.

// The following are the most common and straightforward to use.
void PropVariantInit ( PROPVARIANT * pvar ); // VT_EMPTY
HRESULT InitPropVariantFromBoolean(BOOL fVal, __out PROPVARIANT *ppropvar); // VT_BOOL
HRESULT InitPropVariantFromInt16(SHORT nVal, __out PROPVARIANT *ppropvar); // VT_I2
HRESULT InitPropVariantFromUInt16(USHORT uiVal, __out PROPVARIANT *ppropvar); // VT_UI2
HRESULT InitPropVariantFromInt32(LONG lVal, __out PROPVARIANT *ppropvar); // VT_I4
HRESULT InitPropVariantFromUInt32(ULONG ulVal, __out PROPVARIANT *ppropvar); // VT_UI4
HRESULT InitPropVariantFromInt64(LONGLONG llVal, __out PROPVARIANT *ppropvar); // VT_I8
HRESULT InitPropVariantFromUInt64(ULONGLONG ullVal, __out PROPVARIANT *ppropvar); // VT_UI8
HRESULT InitPropVariantFromDouble(DOUBLE dblVal, __out PROPVARIANT *ppropvar); // VT_R8
HRESULT InitPropVariantFromString(PCWSTR psz, __out PROPVARIANT *ppropvar); // VT_LPWSTR
HRESULT InitPropVariantFromGUIDAsBuffer(REFGUID guid, __out PROPVARIANT *ppropvar); // VT_VECTOR | VT_UI1
PSSTDAPI InitPropVariantFromCLSID(REFCLSID clsid, __out PROPVARIANT *ppropvar); // VT_GUID
PSSTDAPI InitPropVariantFromFileTime(const FILETIME *pftIn, __out PROPVARIANT *ppropvar); // VT_FILETIME

// These are interesting. They deserve their own posts (...note to self...)
PSSTDAPI InitPropVariantFromStringAsVector(
PCWSTR psz, __out PROPVARIANT *ppropvar); // VT_VECTOR | VT_LPWSTR
PSSTDAPI InitPropVariantFromPropVariantVectorElem(
REFPROPVARIANT propvarIn, ULONG iElem, __out PROPVARIANT *ppropvar);
PSSTDAPI InitPropVariantFromStrRet(
__in STRRET *pstrret, PCUITEMID_CHILD pidl, __out PROPVARIANT *ppropvar); // VT_LPWSTR

// The following are vector versions:
// VT_VECTOR | VT_LPWSTR
PSSTDAPI InitPropVariantFromStringVector(
__in_ecount_opt(cElems) PCWSTR *prgsz, ULONG cElems, __out PROPVARIANT *ppropvar);

// VT_VECTOR | VT_BOOL
PSSTDAPI InitPropVariantFromBoolVector(
__in_ecount_opt(cElems) const BOOL *prgf, ULONG cElems, __out PROPVARIANT *ppropvar);

// VT_VECTOR | VT_I2
PSSTDAPI InitPropVariantFromInt16Vector(
__in_ecount_opt(cElems) const SHORT *prgn, ULONG cElems, __out PROPVARIANT *ppropvar);

// VT_VECTOR | VT_UI2
PSSTDAPI InitPropVariantFromUInt16Vector(
__in_ecount_opt(cElems) const USHORT *prgn, ULONG cElems, __out PROPVARIANT *ppropvar);

// VT_VECTOR | VT_I4
PSSTDAPI InitPropVariantFromInt32Vector(
__in_ecount_opt(cElems) const LONG *prgn, ULONG cElems, __out PROPVARIANT *ppropvar);

// VT_VECTOR | VT_UI4
PSSTDAPI InitPropVariantFromUInt32Vector(
__in_ecount_opt(cElems) const ULONG *prgn, ULONG cElems, __out PROPVARIANT *ppropvar);

// VT_VECTOR | VT_I8
PSSTDAPI InitPropVariantFromInt64Vector(
__in_ecount_opt(cElems) const LONGLONG *prgn, ULONG cElems, __out PROPVARIANT *ppropvar);

// VT_VECTOR | VT_UI8
PSSTDAPI InitPropVariantFromUInt64Vector(
__in_ecount_opt(cElems) const ULONGLONG *prgn, ULONG cElems, __out PROPVARIANT *ppropvar);

// VT_VECTOR | VT_DOUBLE
PSSTDAPI InitPropVariantFromDoubleVector(
__in_ecount_opt(cElems) const DOUBLE *prgn, ULONG cElems, __out PROPVARIANT *ppropvar);

// VT_VECTOR | VT_FILETIME
PSSTDAPI InitPropVariantFromFileTimeVector(
__in_ecount_opt(cElems) const FILETIME *prgft, ULONG cElems, __out PROPVARIANT *ppropvar);

// These helpers are used less frequently. I may talk about them eventually.
PSSTDAPI InitPropVariantVectorFromPropVariant(
REFPROPVARIANT propvarSingle, __out PROPVARIANT *ppropvarVector);
PSSTDAPI InitPropVariantFromBuffer(
const void *pv, UINT cb, __out PROPVARIANT *ppropvar); // VT_VECTOR | VT_UI1
PSSTDAPI InitPropVariantFromResource(
HINSTANCE hinst, UINT id, VARTYPE vtSaveIn, __out PROPVARIANT *ppropvar); // VT_LPWSTR
PSSTDAPI InitPropVariantFromGUIDAsString(
REFGUID guid, __out PROPVARIANT *ppropvar); // VT_LPWSTR

All these helpers live in propvarutil.h (except for PropVariantInit which lives in propidl.h). Non-inline helpers are implemented in propsys.dll.

As it may be some time before I blog about individual functions, if you are anxious to hear the nitty gritty, just send me a note.