Programming with Microsoft Visual C++.NET 6ed [Electronic resources] نسخه متنی

The VARIANT Type

No doubt you noticed the VARIANT type used in both Automation client and component functions in the previous example. VARIANT is an all-purpose data type that IDispatch::Invoke uses to transmit parameters and return values. The VARIANT type is the natural type to use when you exchange data with VBA. Here's a simplified version of the VARIANT definition in the Windows header files:

struct tagVARIANT {
VARTYPE vt; // unsigned short integer type code
WORD wReserved1, wReserved2, wReserved3;
union {
short      iVal;                 // VT_I2  short integer
long       lVal;                 // VT_I4  long integer
float      fltVal;               // VT_R4  4-byte float
double     dblVal;               // VT_R8  8-byte IEEE float
DATE       date;                 // VT_DATE stored as dbl
//  date.time
CY         vtCY                  // VT_CY 64-bit integer
BSTR       bstrVal;              // VT_BSTR
IUnknown*  punkVal;              // VT_UNKNOWN
IDispatch* pdispVal;             // VT_DISPATCH
short*     piVal;                // VT_BYREF | VT_I2
long*      plVal;                // VT_BYREF | VT_I4
float*     pfltVal;              // VT_BYREF | VT_R4
double*    pdblVal;              // VT_BYREF | VT_R8
DATE*      pdate;                // VT_BYREF | VT_DATE
CY*        pvtCY;                // VT_BYREF | VT_CY
BSTR*      pbstrVal;             // VT_BYREF | VT_BSTR
}
};
typedef struct tagVARIANT VARIANT;

As you can see, the VARIANT type is a C structure that contains a type code vt, some reserved bytes, and a big union of types that you already know about. If vt is VT_I2, for example, you read the VARIANT's value from iVal, which contains a 2-byte integer. If vt is VT_R8, you read this value from dblVal, which contains an 8-byte real value.

A VARIANT object can contain actual data or a pointer to data. If vt has the VT_BYREF bit set, you must access a pointer in piVal, plVal, and so on. Note that a VARIANT object can contain an IUnknown pointer or an IDispatch pointer. This means that you can pass a complete COM object using an Automation call, but if you want VBA to process that object, its class should have an IDispatch interface.

Strings are special. The BSTR type is yet another way to represent character strings. A BSTR variable is a pointer to a zero-terminated character array with a character count in front. A BSTR variable can therefore contain binary characters, including zeros. If you have a VARIANT object with vt = VT_BSTR, memory will look like this:

Because the string has a terminating 0, you can use bstrVal as if it were an ordinary char pointer, but you have to be very, very careful about memory cleanup. You can't simply delete the string pointer because the allocated memory begins with the character count. Windows provides the SysAllocString and SysFreeString functions for allocating and deleting BSTR objects.

Windows supplies some useful VARIANT manipulation functions, including those shown in the following table. If a VARIANT contains a BSTR, these functions ensure that memory is allocated and cleared properly. The VariantInit and VariantClear functions set vt to VT_EMPTY. All the variant functions are global functions and take a VARIANT* parameter.