Win32-OLE-0.1502 > Win32::OLE::Variant
Win32-OLE-0.1502
Other versions:
libwin32-0.26

名前

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

Win32::OLE::Variant - OLE バリアント変数の作成と変更

概要

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

説明

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.

Perl OLE モジュールによって使われる IDispatch インターフェースは バリアント(VARIANT)と呼ばれる汎用的な引数型を使います。 これは基本的にデータ型と実際のデータ値をもったオブジェクトです。 データ型は VT_xxx 定数により指定されます。

関数

nothing()

The nothing() function returns an empty VT_DISPATCH variant. It can be used to clear an object reference stored in a property

nothing() 関数は空の VT_DISPATCH 変数を返します。 プロパティに格納されたオブジェクト参照をクリアするために使えます。

        use Win32::OLE::Variant qw(:DEFAULT nothing);
        # ...
        $object->{Property} = nothing;

This has the same effect as the Visual Basic statement

これは以下の Visual Basic ステートメントと同じ効果を持ちます。

        Set object.Property = Nothing

The nothing() function is not exported by default.

nothing() はデフォルトではエクスポート されません

Variant(TYPE, DATA)

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

これは Win32::OLE::Variant-new()> メソッドの単なる別名関数です。 (下記をご覧ください)この関数はデフォルトでエクスポートされます。

メソッド

new(TYPE, 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.

このメソッドは指定された TYPE の与えられた DATA をもった Win32::OLE::Variant オブジェクトを返します。 Win32::OLE::Variant オブジェクトは IV, NV, PV(これらは透過的に サポートされています)以外のデータ型を指定するために使えます。 詳細については下記の "Variants" をご覧ください。

For VT_EMPTY and VT_NULL variants, the DATA argument may be omitted. For all non-VT_ARRAY variants DATA specifies the initial value.

VT_EMPTY と VT_NULL バリアントについては、DATA 引数を省略することができます。 すべての VT_ARRAY ではない variant については、DATA を初期値を指定します。

To create a SAFEARRAY variant, you have to specify the VT_ARRAY flag in addition to the variant base type of the array elemnts. In this cases DATA must be a list specifying the dimensions of the array. Each element can be either an element count (indices 0 to count-1) or an array reference pointing to the lower and upper array bounds of this dimension:

SAFEARRAY バリアントを作るためには、配列要素の基本型に加えて VT_ARRAY フラグを指定する必要があります。 この場合、DATA は配列を次元を指定するリストでなければなりません。 各要素は要素数(0 から指定数 -1 を示します)またはこの次元での上限下限を 示す配列リファレンスのどちらかにすることができます:

        my $Array = Win32::OLE::Variant->new(VT_ARRAY|VT_R8, [1,2], 2);

This creates a 2-dimensional SAFEARRAY of doubles with 4 elements: (1,0), (1,1), (2,0) and (2,1).

これは double で四つの要素:((1,0), (1,1), (2,0), (2,1) をもった 2 次元の SAFEARRAY を作成します。

A special case is the the creation of one-dimensional VT_UI1 arrays with a string DATA argument:

特別なケースは、文字列 DATA 引数をもった 1 次元の VT_UI1 配列の作成です:

        my $String = Variant(VT_ARRAY|VT_UI1, "String");

This creates a 6 element character array initialized to "String". For backward compatibility VT_UI1 with a string initializer automatically implies VT_ARRAY. The next line is equivalent to the previous example:

これは "String" で初期化された六つの文字配列を作成します。 後方互換性のため、文字列初期値をもった VT_UI1 は自動的に VT_ARRAY が 暗黙のうちに設定されます。 次の行は前の例と同じです:

        my $String = Variant(VT_UI1, "String");

If you really need a single character VT_UI1 variant, you have to create it using a numeric intializer:

本当に 1 文字 VT_UI1 バリアントが必要なのであれば、数値の初期値を使って 作らなければなりません:

        my $Char = Variant(VT_UI1, ord('A'));
As(TYPE)

As converts the VARIANT to the new type before converting to a Perl value. This take the current LCID setting into account. For example a string might contain a ',' as the decimal point character. Using $variant-As(VT_R8)> will correctly return the floating point value.

As は VARIANT を Perl の値に変換される前に新しい型に変換します。 これは現在の LCID 設定も勘案します。 例えばある文字列は小数点文字として ',' が入っているかもしれません。 $variant-As(VT_R8)> を使うと浮動小数点値を返します。

The underlying variant object is NOT changed by this method.

元になるバリアントは、このメソッドによって変更されません。

ChangeType(TYPE)

This method changes the type of the contained VARIANT in place. It returns the object itself, not the converted value.

このメソッドは入っているバリアントの型をその場で変更します。 変換された値ではなく、オブジェクトそれ自身を返します。

Copy([DIM])

This method creates a copy of the object. If the original variant had the VT_BYREF bit set then the new object will contain a copy of the referenced data and not a reference to the same old data. The new object will not have the VT_BYREF bit set.

このメソッドはオブジェクトのコピーを作成します。 元のバリアントの VT_BYREF ビットが設定されていれば、新しいオブジェクトは 同じ古いデータのリファレンスではなく参照されているデータのコピーを持ちます。 新しいオブジェクトでは VT_BYREF ビットは設定されていません。

        my $Var = Variant(VT_I4|VT_ARRAY|VT_BYREF, [1,5], 3);
        my $Copy = $Var->Copy;

The type of $Copy is now VT_I4|VT_ARRAY and the value is a copy of the other SAFEARRAY. Changes to elements of $Var will not be reflected in $Copy and vice versa.

$Copy の型は今や VT_I4|VT_ARRAY であり、値は他の SAFEARRAY のコピーです。 $Var の要素を変更しても $Copy には反映されませんし、その逆でも同じです。

The Copy method can also be used to extract a single element of a VT_ARRAY | VT_VARIANT object. In this case the array indices must be specified as a list DIM:

Copy メソッドはVT_ARRAY | VT_VARIANT オブジェクトの一つの要素を 取り出すために使うこともできます。 この場合、配列のインデックスはリスト DIM で指定されなければなりません:

        my $Int = $Var->Copy(1, 2);

$Int is now a VT_I4 Variant object containing the value of element (1,2).

$Int は今や要素 (1,2) の値をもった VT_I4 バリアントオブジェクトです。

Currency([FORMAT[, LCID]])

This method converts the VARIANT value into a formatted curency string. The FORMAT can be either an integer constant or a hash reference. Valid constants are 0 and LOCALE_NOUSEROVERRIDE. You get the value of LOCALE_NOUSEROVERRIDE from the Win32::OLE::NLS module:

このメソッドはバリアントの値を書式設定された通貨文字列に変換します。 FORMAT は整数定数またはハッシュリファレンスのどちらかにすることができます。 適切な定数は 0 と LOCALE_NOUSEROVERRIDE です。 Win32::OLE::NLS モジュールから LOCALE_NOUSEROVERRIDE の値を取得できます:

        use Win32::OLE::NLS qw(:LOCALE);

LOCALE_NOUSEROVERRIDE tells the method to use the system default currency format for the specified locale, disregarding any changes that might have been made through the control panel application.

LOCALE_NOUSEROVERRIDE は、コントロールパネルアプリケーションを通して 行われた変更をすべて無視しして、指定されたロケールのための システムデフォルト通貨フォーマットを使うように指示します。

The hash reference could contain the following keys:

ハッシュリファレンスには以下のキーを入れることができます:

        NumDigits       number of fractional digits
        LeadingZero     whether to use leading zeroes in decimal fields
        Grouping        size of each group of digits to the left of the decimal
        DecimalSep      decimal separator string
        ThousandSep     thousand separator string
        NegativeOrder   see "LOCALE_ICURRENCY" in Win32::OLE::NLS
        PositiveOrder   see "LOCALE_INEGCURR" in Win32::OLE::NLS
        CurrencySymbol  currency symbol string
        NumDigits       小数の桁数
        LeadingZero     数値フィールドで前に 0 をつけるかどうか
        Grouping        数字区切りの各グループの桁数
        DecimalSep      小数点文字列
        ThousandSep     桁区切り文字
        NegativeOrder   "LOCALE_ICURRENCY" in Win32::OLE::NLS を参照
        PositiveOrder   "LOCALE_INEGCURR" in Win32::OLE::NLS を参照
        CurrencySymbol  通貨記号

For example:

例えば:

        use Win32::OLE::Variant;
        use Win32::OLE::NLS qw(:DEFAULT :LANG :SUBLANG :DATE :TIME);
        my $lcidGerman = MAKELCID(MAKELANGID(LANG_GERMAN, SUBLANG_NEUTRAL));
        my $v = Variant(VT_CY, "-922337203685477.5808");
        print $v->Currency({CurrencySymbol => "Tuits"}, $lcidGerman), "\n";

will print:

以下のようになります:

        -922.337.203.685.477,58 Tuits
Date([FORMAT[, LCID]])

Converts the VARIANT into a formatted date string. FORMAT can be either one of the following integer constants or a format string:

バリアントを書式設定された日付文字列に変換します。 FORMAT は以下の整数定数か書式設定文字列のどちらかにすることができます:

        LOCALE_NOUSEROVERRIDE   system default date format for this locale
        DATE_SHORTDATE          use the short date format (default)
        DATE_LONGDATE           use the long date format
        DATE_YEARMONTH          use the year/month format
        DATE_USE_ALT_CALENDAR   use the alternate calendar, if one exists
        DATE_LTRREADING         left-to-right reading order layout
        DATE_RTLREADING         right-to left reading order layout
        LOCALE_NOUSEROVERRIDE   このロケールでのシステムデフォルト日付書式を使う
        DATE_SHORTDATE          短い日付書式を使う (デフォルト)
        DATE_LONGDATE           長い日付書式を使う
        DATE_YEARMONTH          年/月 書式を使う
        DATE_USE_ALT_CALENDAR   もしあれば代替 カレンダーを使う
        DATE_LTRREADING         左から右 読込順レイアウト
        DATE_RTLREADING         右から左 読込順レイアウト

The constants are available from the Win32::OLE::NLS module:

Win32::OLE::NLS モジュールから定数を利用できます:

        use Win32::OLE::NLS qw(:LOCALE :DATE);

The following elements can be used to construct a date format string. Characters must be specified exactly as given below (e.g. "dd" not "DD"). Spaces can be inserted anywhere between formating codes, other verbatim text should be included in single quotes.

以下の要素を日付書式設定文字列を構成するために使えます。 文字は正確に以下で示される通りに指定されなければなりません(例えば "dd" は "DD" では ありません)。 書式コードの間のどこにでも空白を入れることができます。 その他の、逐語的なテキストはシングルクォートに含まれなければなりません:

        d       day of month
        dd      day of month with leading zero for single-digit days
        ddd     day of week: three-letter abbreviation (LOCALE_SABBREVDAYNAME)
        dddd    day of week: full name (LOCALE_SDAYNAME)
        M       month
        MM      month with leading zero for single-digit months
        MMM     month: three-letter abbreviation (LOCALE_SABBREVMONTHNAME)
        MMMM    month: full name (LOCALE_SMONTHNAME)
        y       year as last two digits
        yy      year as last two digits with leading zero for years less than 10
        yyyy    year represented by full four digits
        gg      period/era string
        d       日
        dd      日 (1 桁であれば前に 0 がつく)
        ddd     曜日: 3 文字の省略名 (LOCALE_SABBREVDAYNAME)
        dddd    曜日: フルネーム (LOCALE_SDAYNAME)
        M       月
        MM      月 (1 桁であれば前に 0 がつく)
        MMM     月: 3 文字の省略名 (LOCALE_SABBREVMONTHNAME)
        MMMM    月: フルネーム (LOCALE_SMONTHNAME)
        y       年 (最後の 2 桁)
        yy      年 (最後の 2 桁; 10 よりも小さければ前に 0 がつく)
        yyyy    年 (4 桁により表される)
        gg      時代/年号 文字列

For example:

例えば:

        my $v = Variant(VT_DATE, "April 1 99");
        print $v->Date(DATE_LONGDATE), "\n";
        print $v->Date("ddd',' MMM dd yy"), "\n";

will print:

は以下のように出力します:

        Thursday, April 01, 1999
        Thu, Apr 01 99
Dim()

Returns a list of array bounds for a VT_ARRAY variant. The list contains an array reference for each dimension of the variant's SAFEARRAY. This reference points to an array containing the lower and upper bounds for this dimension. For example:

VT_ARRAY バリアントのための配列範囲を返します。 リストにはバリアントの SAFEARRAY の各次元の配列リファレンスが入ります。 このリファレンスはこの次元のための下限と上限が入った配列を示します。 例えば:

        my @Dim = $Var->Dim;

Now @Dim contains the following list: ([1,5], [0,2]).

すると @Dim には以下のリストが入ります: ([1,5], [0,2])

Get(DIM)

For normal variants Get returns the value of the variant, just like the Value method. For VT_ARRAY variants Get retrieves the value of a single array element. In this case DIM must be a list of array indices. E.g.

通常のバリアントでは GetValue メソッドと全く同じように バリアントの値を返します。 VT_ARRAY バリアントでは Get は一つの配列要素の値を取り出します。 この場合、DIM は配列インデックスのリストでなければなりません。 例えば:

        my $Val = $Var->Get(2,0);

As a special case for one dimensional VT_UI1|VT_ARRAY variants the Get method without arguments returns the character array as a Perl string.

1 次元の VT_UI1|VT_ARRAY バリアントの特別場合、引数のない Get メソッドは Perl 文字列として文字配列を返します:

        print $String->Get, "\n";
LastError()

The use of the Win32::OLE::Variant-LastError()> method is deprecated. Please use the Win32::OLE-LastError()> class method instead.

Win32::OLE::Variant-LastError()> メソッドを使うことは廃止予定です。 代わりに Win32::OLE-LastError()> クラスメソッドを使ってください。

Number([FORMAT[, LCID]])

This method converts the VARIANT value into a formatted number string. The FORMAT can be either an integer constant or a hash reference. Valid constants are 0 and LOCALE_NOUSEROVERRIDE. You get the value of LOCALE_NOUSEROVERRIDE from the Win32::OLE::NLS module:

このメソッドは VARIANT 値を書式化れた数字文字列に変換します。 FORMAT は整数定数またはハッシュリファレンスのどちらかにすることができます。 適切な定数は 0 と LOCALE_NOUSEROVERRIDE です。 LOCALE_NOUSEROVERRIDE の値を Win32::OLE::NLS モジュールから 取得できます:

        use Win32::OLE::NLS qw(:LOCALE);

LOCALE_NOUSEROVERRIDE tells the method to use the system default number format for the specified locale, disregarding any changes that might have been made through the control panel application.

LOCALE_NOUSEROVERRIDE はメソッドにコントロールパネルアプリケーションを 通してなされたかもしれない変更をすべて無視して、指定されたロケールのための システムデフォルト数値書式を使うように指示します。

The hash reference could contain the following keys:

ハッシュリファレンスには以下のキーのものを入れることができます:

        NumDigits       number of fractional digits
        LeadingZero     whether to use leading zeroes in decimal fields
        Grouping        size of each group of digits to the left of the decimal
        DecimalSep      decimal separator string
        ThousandSep     thousand separator string
        NegativeOrder   see "LOCALE_INEGNUMBER" in Win32::OLE::NLS
        NumDigits       小数の桁数
        LeadingZero     数値フィールドで前に 0 をつけるかどうか
        Grouping        桁区切りの桁数
        DecimalSep      小数点の文字列
        ThousandSep     桁区切りの文字列
        NegativeOrder   "LOCALE_INEGNUMBER" in Win32::OLE::NLS を参照
Put(DIM, VALUE)

The Put method is used to assign a new value to a variant. The value will be coerced into the current type of the variant. E.g.:

Put メソッドはバリアントに新しい値を代入するために使われます。 値はバリアントの現在の型に強制されます。 例:

        my $Var = Variant(VT_I4, 42);
        $Var->Put(3.1415);

This changes the value of the variant to 3 because the type is VT_I4.

型が VT_I4 なので、これはバリアントの値を 3 に変更します。

For VT_ARRAY type variants the indices for each dimension of the contained SAFEARRAY must be specified in front of the new value:

VT_ARRAY 型バリアントでは、SAFEARRAY に含まれている各次元のための インデックスが当たらし値の前に指定されなければなりません:

        $Array->Put(1, 1, 2.7);

It is also possible to assign values to *every* element of the SAFEARRAY at once using a single Put() method call:

一度の Put() メソッド呼出しを使って SAFEARRAY の*各*要素に値を代入することも 可能です:

        $Array->Put([[1,2], [3,4]]);

In this case the argument to Put() must be an array reference and the dimensions of the Perl list-of-lists must match the dimensions of the SAFEARRAY exactly.

この場合、Put() への引数は配列リファレンスで、Perl リストのリストの次元は SAFEARRAY の次元と厳密にあっていなければなりません。

The are a few special cases for one-dimensional VT_UI1 arrays: The VALUE can be specified as a string instead of a number. This will set the selected character to the first character of the string or to '\0' if the string was empty:

1 次元の VT_Ul1 配列のためにはいくつか特別なケースがあります: VALUE は数値の代わりに文字列として指定することができます。 これは選択された文字をその文字列の最初の文字に設定します。 または文字列が空であれば '\0' にします:

        my $String = Variant(VT_UI1|VT_ARRAY, "ABCDE");
        $String->Put(1, "123");
        $String->Put(3, ord('Z'));
        $String->Put(4, '');

This will set the value of $String to "A1CZ\0". If the index is omitted then the string is copied to the value completely. The string is truncated if it is longer than the size of the VT_UI1 array. The result will be padded with '\0's if the string is shorter:

これは $String の値を "A1CZ\0" に設定します。 もしインデックスが省略されると、文字列は完全に値へコピーされます。 もし VT_UI1 配列の大きさよりも長ければ、その文字列は切り捨てられます。 もし短ければ '\0' で埋められます。

        $String->Put("String");

Now $String contains the value "Strin".

$String には値 "Strin" が入ります。

Put returns the Variant object itself so that multiple Put calls can be chained together:

Put は Variant オブジェクトそのものを返します; そのため複数の Put 呼び出しをつなげて行えます:

        $Array->Put(0,0,$First_value)->Put(0,1,$Another_value);
Time([FORMAT[, LCID]])

Converts the VARIANT into a formatted time string. FORMAT can be either one of the following integer constants or a format string:

バリアントを書式化された時刻文字列に変換します。 FORAMT は以下の整数定数か書式設定文字列のどちらかにすることができます:

        LOCALE_NOUSEROVERRIDE   system default time format for this locale
        TIME_NOMINUTESORSECONDS don't use minutes or seconds
        TIME_NOSECONDS          don't use seconds
        TIME_NOTIMEMARKER       don't use a time marker
        TIME_FORCE24HOURFORMAT  always use a 24-hour time format
        LOCALE_NOUSEROVERRIDE   このロケールでのシステムデフォルト時刻書式
        TIME_NOMINUTESORSECONDS 分または秒を使わない
        TIME_NOSECONDS          秒を使わない
        TIME_NOTIMEMARKER       時刻マーカーを使わない
        TIME_FORCE24HOURFORMAT  常に 24 時間制の時刻フォーマットを使う

The constants are available from the Win32::OLE::NLS module:

定数は Win32::OLE::NLS モジュールから利用できます:

        use Win32::OLE::NLS qw(:LOCALE :TIME);

The following elements can be used to construct a time format string. Characters must be specified exactly as given below (e.g. "dd" not "DD"). Spaces can be inserted anywhere between formating codes, other verbatim text should be included in single quotes.

以下の要素を日付書式設定文字列を構成するために使えます。 文字は正確に以下で示される通りに指定されなければなりません(例えば "dd" は "DD" では ありません)。 書式コードの間のどこにでも空白を入れることができます。 その他の、逐語的なテキストはシングルクォートに含まれなければなりません:

        h       hours; 12-hour clock
        hh      hours with leading zero for single-digit hours; 12-hour clock
        H       hours; 24-hour clock
        HH      hours with leading zero for single-digit hours; 24-hour clock
        m       minutes
        mm      minutes with leading zero for single-digit minutes
        s       seconds
        ss      seconds with leading zero for single-digit seconds
        t       one character time marker string, such as A or P
        tt      multicharacter time marker string, such as AM or PM
        h       時; 12 時間制
        hh      時; 1 桁であれば前に 0 がつく; 12 時間制
        H       時; 24 時間制
        HH      時; 1 桁であれば前に 0 がつく; 24 時間制
        m       分
        mm      分; 1 桁であれば前に 0 がつく
        s       秒
        ss      秒; 1 桁であれば前に 0 がつく
        t       A や P のような 1 文字時刻マーカー文字列
        tt      AM または PM のような複数文字時刻マーカー文字列

For example:

例えば:

        my $v = Variant(VT_DATE, "April 1 99 2:23 pm");
        print $v->Time, "\n";
        print $v->Time(TIME_FORCE24HOURFORMAT|TIME_NOTIMEMARKER), "\n";
        print $v->Time("hh.mm.ss tt"), "\n";

will print:

これは以下のように出力します:

        2:23:00 PM
        14:23:00
        02.23.00 PM
Type()

The Type method returns the variant type of the contained VARIANT.

Type メソッドは入っているバリアントのバリアント型を返します。

Unicode()

The Unicode method returns a Unicode::String object. This contains the BSTR value of the variant in network byte order. If the variant is not currently in VT_BSTR format then a VT_BSTR copy will be produced first.

Unicode メソッドは Unicode::String オブジェクトを返します。 これはネットワークバイト順でのバリアントの BSTR 値が入ります。 もしバリアントが現在は VT_BSTR フォーマットでなければ、VT_BSTR への コピーが先に作成されます。

Value()

The Value method returns the value of the VARIANT as a Perl value. The conversion is performed in the same manner as all return values of Win32::OLE method calls are converted.

Value メソッドは Perl の値としてバリアントの値を返します。 すべての Win32::OLE メソッドの値が変換されるのと同じ方法で変換されます。

オーバーロード

The Win32::OLE::Variant package has overloaded the conversion to string and number formats. Therefore variant objects can be used in arithmetic and string operations without applying the Value method first.

Win32::OLE::Variant パッケージは文字列と数値書式の変換が オーバーロードされています。 このため Varinat オブジェクトは Value メソッドを先に適用することなしに、 算術と文字列操作で使えます。

クラス変数

The Win32::OLE::Variant class used to have its own set of class variables like $CP, $LCID and $Warn. In version 0.1003 and later of the Win32::OLE module these variables have been eleminated. Now the settings of Win32::OLE are used by the Win32::OLE::Variant module too. Please read the documentation of the Win32::OLE->Option class method.

Win32::OLE::Variant クラスは $CP, $LCID, $Warn のような独自の クラス変数の集合をもつようにしてきました。 Win32::OLE モジュールのバージョン 0.1003 以降では、これらの変数は 削除されています。 今では Win32::OLE の設定が Win32::OLE::Variant モジュールでも使われます。 Win32::OLE->Option クラスメソッドのドキュメントをお読みください。

定数

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_DECIMAL
        VT_UI1

        VT_ARRAY
        VT_BYREF

VT_DECIMAL is not on the official list of allowable OLE Automation datatypes. But even Microsoft ADO seems to sometimes return values of Recordset fields in VT_DECIMAL format.

VT_DECIMAL は公式な許可される OLE オートメーションデータ型のリストには ありません。 しかし Microsoft ADO でさえ、レコードセットフィールドの値を VT_DECIMAL 形式で返しているようです。

バリアント

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

バリアント(Variant) は OLE 接続の間でデータを渡すために使われる データ型です。

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:

デフォルトの動きは各 Perl スカラ変数を内部の perl 表現に合わせて OLE バリアントに変換します。 以下の型対応が取られます:

        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_BSTR がワイド文字または Unicode 文字列であることに注意してください。 これはパラメータとしてバイナリデータを渡そうとすると、データのすべての バイトの間に 0x00 が挿入されるという問題を起こします。 Variant() メソッドはこれを解決する方法を提供します。 Variant でスクリプトの作者は、そのパラメータが変換されるべき OLE バリアント型を指定できます。 現在は以下の型がサポートされています:

        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.

VT_DATE と VT_CY オブジェクトが作成されると、入力パラメータは Perl 文字列型として扱われます。 これは VT_BSTR に変換され、最後に VariantChangeType() OLE API 関数を 使って VT_CY または VT_DATE に変換されます。 これらがどのように使うことができるかについては、"EXAMPLES" in Win32::OLE を ご覧ください。

バリアントの配列

A variant can not only contain a single value but also a multi-dimensional array of values (called a SAFEARRAY). In this case the VT_ARRAY flag must be added to the base variant type, e.g. VT_I4 | VT_ARRAY for an array of integers. The VT_EMPTY and VT_NULL types are invalid for SAFEARRAYs. It is possible to create an array of variants: VT_VARIANT | VT_ARRAY. In this case each element of the array can have a different type (including VT_EMPTY and VT_NULL). The elements of a VT_VARIANT SAFEARRAY cannot have either of the VT_ARRAY or VT_BYREF flags set.

バリアントは一つの値を持つだけでなく、値の多次元配列ももつ事ができます (SAFEARRAY と呼ばれます)。 この場合、VT_ARRAY フラグが基本バリアント型に付与されなければなりません。 例えば VT_I4|VT_ARRAY は整数の配列です。 VT_EMPTY と VT_NULL 型は SAFEARRAY には不正です。 バリアントの配列を作成することも可能です: VT_VARIANT | VT_ARRAY。 この場合、配列の各要素を異なる型(VT_EMPTY と VT_NULL も含めて)に することができます。 VT_VARIANT SAFEARRAY の要素は VT_ARRAY または VT_BYREF のどちらのフラグも 設定できません。

The lower and upper bounds for each dimension can be specified separately. They do not have to have all the same lower bound (unlike Perl's arrays).

各次元の上限、下限は個別に指定できます。 (Perl の配列とは違って)すべてが同じ下限をもつ必要はありません。

リファレンスによるバリアント

Some OLE servers expect parameters passed by reference so that they can be changed in the method call. This allows methods to easily return multiple values. There is preliminary support for this in the Win32::OLE::Variant module:

いくつかの OLE サーバーは、メソッド呼出しの中で変更できるように、 リファレンスによってパラメータが渡されることを期待します。 これはメソッドに複数の値を戻すことを簡単にします。 Win32::OLE::Variant モジュールでこれの予備的なサポートがされています:

        my $x = Variant(VT_I4|VT_BYREF, 0);
        my $y = Variant(VT_I4|VT_BYREF, 0);
        $Corel->GetSize($x, $y);
        print "Size is $x by $y\n";

After the GetSize method call $x and $y will be set to the respective sizes. They will still be variants. In the print statement the overloading converts them to string representation automatically.

GetSize メソッド呼出しの後、$x$y は対応する大きさに 設定されます。 これらはまだバリアントです。 print ステートメントでは、オーバーロードがそれらを自動的に文字列表現に 変換します。

VT_BYREF is now supported for all variant types (including SAFEARRAYs). It can also be used to pass an OLE object by reference:

VT_BYREF は今やすべてのバリアント型でサポートされています (SAFEARRAY も含めて)。 これは OLE オブジェクトをリファレンスで渡すためにも使われます:

        my $Results = $App->CreateResultsObject;
        $Object->Method(Variant(VT_DISPATCH|VT_BYREF, $Results));

AUTHORS/COPYRIGHT

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

このモジュールは Win32::OLE ディストリビューションの一部です。