NAME

Win32::OLE::Variant - Create and modify OLE VARIANT variables

SYNOPSIS

use Win32::OLE::Variant;
my $var = Variant(VT_DATE, 'Jan 1,1970');
$OleObject->{value} = $var;
$OleObject->Method($var);

DESCRIPTION

The IDispatch interface used by the Perl OLE module uses a universal argument type called VARIANT. This is basically an object containing a data type and the actual data value. The data type is specified by the VT_xxx constants.

Functions/Methods

Win32::OLE::Variant->new(TYPENAME, DATA)

This method returns a Win32::OLE::Variant object of the specified type that contains the given data. The Win32::OLE::Variant object can be used to specify data types other than IV, NV or PV (which are supported transparently). See Variants below for details.

Variant(TYPENAME, DATA)

This is just a function alias of the Win32::OLE::Variant->new() method. This function is exported by default.

Constants

These constants are exported by default:

VT_EMPTY
VT_NULL
VT_I2
VT_I4
VT_R4
VT_R8
VT_CY
VT_DATE
VT_BSTR
VT_DISPATCH
VT_ERROR
VT_BOOL
VT_VARIANT
VT_UNKNOWN
VT_UI1

Other OLE constants are also defined in the Win32::OLE::Variant package, but they are unsupported at this time, so they are exported only on request. They are actually also invalid data types for the VARIANT structure; they are used in OLE property sets, safe arrays and type descriptions:

VT_UI2
VT_UI4
VT_I8
VT_UI8
VT_INT
VT_UINT
VT_VOID
VT_HRESULT
VT_PTR
VT_SAFEARRAY
VT_CARRAY
VT_USERDEFINED
VT_LPSTR
VT_LPWSTR
VT_FILETIME
VT_BLOB
VT_STREAM
VT_STORAGE
VT_STREAMED_OBJECT
VT_STORED_OBJECT
VT_BLOB_OBJECT
VT_CF
VT_CLSID

Variants

A Variant is a data type that is used to pass data between OLE connections.

The default behavior is to convert each perl scalar variable into an OLE Variant according to the internal perl representation. The following type correspondence holds:

C type          Perl type       OLE type
------          ---------       --------
  int              IV            VT_I4
double             NV            VT_R8
char *             PV            VT_BSTR
void *           ref to AV       VT_ARRAY
   ?              undef          VT_ERROR
   ?        Win32::OLE object    VT_DISPATCH

Note that VT_BSTR is a wide character or Unicode string. This presents a problem if you want to pass in binary data as a parameter as 0x00 is inserted between all the bytes in your data. The Variant() method provides a solution to this. With Variants the script writer can specify the OLE variant type that the parameter should be converted to. Currently supported types are:

VT_UI1     unsigned char
VT_I2      signed int (2 bytes)
VT_I4      signed int (4 bytes)
VT_R4      float      (4 bytes)
VT_R8      float      (8 bytes)
VT_DATE    OLE Date
VT_BSTR    OLE String
VT_CY      OLE Currency
VT_BOOL    OLE Boolean

When VT_DATE and VT_CY objects are created, the input parameter is treated as a Perl string type, which is then converted to VT_BSTR, and finally to VT_DATE of VT_CY using the VariantChangeType() OLE API function. See "EXAMPLES" in Win32::OLE for how these types can be used.

AUTHORS/COPYRIGHT

This module is part of the Win32::OLE distribution.