home *** CD-ROM | disk | FTP | other *** search
/ PC World 2005 June / PCWorld_2005-06_cd.bin / software / vyzkuste / firewally / firewally.exe / framework-2.3.exe / Variant.pm < prev    next >
Text File  |  2002-07-08  |  18KB  |  557 lines
  1. # The documentation is at the __END__
  2.  
  3. package Win32::OLE::Variant;
  4. require Win32::OLE;  # Make sure the XS bootstrap has been called
  5.  
  6. use strict;
  7. use vars qw(@ISA @EXPORT @EXPORT_OK);
  8.  
  9. use Exporter;
  10. @ISA = qw(Exporter);
  11.  
  12. @EXPORT = qw(
  13.          Variant
  14.          VT_EMPTY VT_NULL VT_I2 VT_I4 VT_R4 VT_R8 VT_CY VT_DATE VT_BSTR
  15.          VT_DISPATCH VT_ERROR VT_BOOL VT_VARIANT VT_UNKNOWN VT_DECIMAL VT_UI1
  16.          VT_ARRAY VT_BYREF
  17.         );
  18.  
  19. @EXPORT_OK = qw(CP_ACP CP_OEMCP nothing);
  20.  
  21. # Automation data types.
  22. sub VT_EMPTY {0;}
  23. sub VT_NULL {1;}
  24. sub VT_I2 {2;}
  25. sub VT_I4 {3;}
  26. sub VT_R4 {4;}
  27. sub VT_R8 {5;}
  28. sub VT_CY {6;}
  29. sub VT_DATE {7;}
  30. sub VT_BSTR {8;}
  31. sub VT_DISPATCH {9;}
  32. sub VT_ERROR {10;}
  33. sub VT_BOOL {11;}
  34. sub VT_VARIANT {12;}
  35. sub VT_UNKNOWN {13;}
  36. sub VT_DECIMAL {14;}    # Officially not allowed in VARIANTARGs
  37. sub VT_UI1 {17;}
  38.  
  39. sub VT_ARRAY {0x2000;}
  40. sub VT_BYREF {0x4000;}
  41.  
  42.  
  43. # For backward compatibility
  44. sub CP_ACP   {0;}     # ANSI codepage
  45. sub CP_OEMCP {1;}     # OEM codepage
  46.  
  47. use overload
  48.     # '+' => 'Add', '-' => 'Sub', '*' => 'Mul', '/' => 'Div',
  49.     '""'     => sub {$_[0]->As(VT_BSTR)},
  50.     '0+'     => sub {$_[0]->As(VT_R8)},
  51.     fallback => 1;
  52.  
  53. sub Variant {
  54.     return Win32::OLE::Variant->new(@_);
  55. }
  56.  
  57. sub nothing {
  58.     return Win32::OLE::Variant->new(VT_DISPATCH);
  59. }
  60.  
  61. 1;
  62.  
  63. __END__
  64.  
  65. =head1 NAME
  66.  
  67. Win32::OLE::Variant - Create and modify OLE VARIANT variables
  68.  
  69. =head1 SYNOPSIS
  70.  
  71.     use Win32::OLE::Variant;
  72.     my $var = Variant(VT_DATE, 'Jan 1,1970');
  73.     $OleObject->{value} = $var;
  74.     $OleObject->Method($var);
  75.  
  76.  
  77. =head1 DESCRIPTION
  78.  
  79. The IDispatch interface used by the Perl OLE module uses a universal
  80. argument type called VARIANT.  This is basically an object containing
  81. a data type and the actual data value.  The data type is specified by
  82. the VT_xxx constants.
  83.  
  84. =head2 Functions
  85.  
  86. =over 8
  87.  
  88. =item nothing()
  89.  
  90. The nothing() function returns an empty VT_DISPATCH variant.  It can be
  91. used to clear an object reference stored in a property
  92.  
  93.     use Win32::OLE::Variant qw(:DEFAULT nothing);
  94.     # ...
  95.     $object->{Property} = nothing;
  96.  
  97. This has the same effect as the Visual Basic statement
  98.  
  99.     Set object.Property = Nothing
  100.  
  101. The nothing() function is B<not> exported by default.
  102.  
  103. =item Variant(TYPE, DATA)
  104.  
  105. This is just a function alias of the C<Win32::OLE::Variant->new()>
  106. method (see below).  This function is exported by default.
  107.  
  108. =back
  109.  
  110. =head2 Methods
  111.  
  112. =over 8
  113.  
  114. =item new(TYPE, DATA)
  115.  
  116. This method returns a Win32::OLE::Variant object of the specified
  117. TYPE that contains the given DATA.  The Win32::OLE::Variant object
  118. can be used to specify data types other than IV, NV or PV (which are
  119. supported transparently).  See L<Variants> below for details.
  120.  
  121. For VT_EMPTY and VT_NULL variants, the DATA argument may be omitted.
  122. For all non-VT_ARRAY variants DATA specifies the initial value.
  123.  
  124. To create a SAFEARRAY variant, you have to specify the VT_ARRAY flag in
  125. addition to the variant base type of the array elemnts.  In this cases
  126. DATA must be a list specifying the dimensions of the array.  Each element
  127. can be either an element count (indices 0 to count-1) or an array
  128. reference pointing to the lower and upper array bounds of this dimension:
  129.  
  130.     my $Array = Win32::OLE::Variant->new(VT_ARRAY|VT_R8, [1,2], 2);
  131.  
  132. This creates a 2-dimensional SAFEARRAY of doubles with 4 elements:
  133. (1,0), (1,1), (2,0) and (2,1).
  134.  
  135. A special case is the the creation of one-dimensional VT_UI1 arrays with
  136. a string DATA argument:
  137.  
  138.     my $String = Variant(VT_ARRAY|VT_UI1, "String");
  139.  
  140. This creates a 6 element character array initialized to "String".  For
  141. backward compatibility VT_UI1 with a string initializer automatically
  142. implies VT_ARRAY.  The next line is equivalent to the previous example:
  143.  
  144.     my $String = Variant(VT_UI1, "String");
  145.  
  146. If you really need a single character VT_UI1 variant, you have to create
  147. it using a numeric intializer:
  148.  
  149.     my $Char = Variant(VT_UI1, ord('A'));
  150.  
  151. =item As(TYPE)
  152.  
  153. C<As> converts the VARIANT to the new type before converting to a
  154. Perl value.  This take the current LCID setting into account.  For
  155. example a string might contain a ',' as the decimal point character.
  156. Using C<$variant->As(VT_R8)> will correctly return the floating
  157. point value.
  158.  
  159. The underlying variant object is NOT changed by this method.
  160.  
  161. =item ChangeType(TYPE)
  162.  
  163. This method changes the type of the contained VARIANT in place.  It
  164. returns the object itself, not the converted value.
  165.  
  166. =item Copy([DIM])
  167.  
  168. This method creates a copy of the object.  If the original variant had
  169. the VT_BYREF bit set then the new object will contain a copy of the
  170. referenced data and not a reference to the same old data.  The new
  171. object will not have the VT_BYREF bit set.
  172.  
  173.     my $Var = Variant(VT_I4|VT_ARRAY|VT_BYREF, [1,5], 3);
  174.     my $Copy = $Var->Copy;
  175.  
  176. The type of C<$Copy> is now VT_I4|VT_ARRAY and the value is a copy of
  177. the other SAFEARRAY.  Changes to elements of C<$Var> will not be reflected
  178. in C<$Copy> and vice versa.
  179.  
  180. The C<Copy> method can also be used to extract a single element of a
  181. VT_ARRAY | VT_VARIANT object.  In this case the array indices must be
  182. specified as a list DIM:
  183.  
  184.     my $Int = $Var->Copy(1, 2);
  185.  
  186. C<$Int> is now a VT_I4 Variant object containing the value of element (1,2).
  187.  
  188. =item Currency([FORMAT[, LCID]])
  189.  
  190. This method converts the VARIANT value into a formatted curency string.  The
  191. FORMAT can be either an integer constant or a hash reference.  Valid constants
  192. are 0 and LOCALE_NOUSEROVERRIDE.  You get the value of LOCALE_NOUSEROVERRIDE
  193. from the Win32::OLE::NLS module:
  194.  
  195.     use Win32::OLE::NLS qw(:LOCALE);
  196.  
  197. LOCALE_NOUSEROVERRIDE tells the method to use the system default currency
  198. format for the specified locale, disregarding any changes that might have
  199. been made through the control panel application.
  200.  
  201. The hash reference could contain the following keys:
  202.  
  203.     NumDigits    number of fractional digits
  204.     LeadingZero    whether to use leading zeroes in decimal fields
  205.     Grouping    size of each group of digits to the left of the decimal
  206.     DecimalSep    decimal separator string
  207.     ThousandSep    thousand separator string
  208.     NegativeOrder    see L<Win32::OLE::NLS/LOCALE_ICURRENCY>
  209.     PositiveOrder    see L<Win32::OLE::NLS/LOCALE_INEGCURR>
  210.     CurrencySymbol    currency symbol string
  211.  
  212. For example:
  213.  
  214.     use Win32::OLE::Variant;
  215.     use Win32::OLE::NLS qw(:DEFAULT :LANG :SUBLANG :DATE :TIME);
  216.     my $lcidGerman = MAKELCID(MAKELANGID(LANG_GERMAN, SUBLANG_NEUTRAL));
  217.     my $v = Variant(VT_CY, "-922337203685477.5808");
  218.     print $v->Currency({CurrencySymbol => "Tuits"}, $lcidGerman), "\n";
  219.  
  220. will print:
  221.  
  222.     -922.337.203.685.477,58 Tuits
  223.  
  224. =item Date([FORMAT[, LCID]])
  225.  
  226. Converts the VARIANT into a formatted date string.  FORMAT can be either
  227. one of the following integer constants or a format string:
  228.  
  229.     LOCALE_NOUSEROVERRIDE    system default date format for this locale
  230.     DATE_SHORTDATE        use the short date format (default)
  231.     DATE_LONGDATE        use the long date format
  232.     DATE_YEARMONTH        use the year/month format
  233.     DATE_USE_ALT_CALENDAR    use the alternate calendar, if one exists
  234.     DATE_LTRREADING        left-to-right reading order layout
  235.     DATE_RTLREADING        right-to left reading order layout
  236.  
  237. The constants are available from the Win32::OLE::NLS module:
  238.  
  239.     use Win32::OLE::NLS qw(:LOCALE :DATE);
  240.  
  241. The following elements can be used to construct a date format string.
  242. Characters must be specified exactly as given below (e.g. "dd" B<not> "DD").
  243. Spaces can be inserted anywhere between formating codes, other verbatim
  244. text should be included in single quotes.
  245.  
  246.     d    day of month
  247.     dd    day of month with leading zero for single-digit days
  248.     ddd    day of week: three-letter abbreviation (LOCALE_SABBREVDAYNAME)
  249.     dddd    day of week: full name (LOCALE_SDAYNAME)
  250.     M    month
  251.     MM    month with leading zero for single-digit months
  252.     MMM    month: three-letter abbreviation (LOCALE_SABBREVMONTHNAME)
  253.     MMMM    month: full name (LOCALE_SMONTHNAME)
  254.     y    year as last two digits
  255.     yy    year as last two digits with leading zero for years less than 10
  256.     yyyy    year represented by full four digits
  257.     gg    period/era string
  258.  
  259. For example:
  260.  
  261.     my $v = Variant(VT_DATE, "April 1 99");
  262.     print $v->Date(DATE_LONGDATE), "\n";
  263.     print $v->Date("ddd',' MMM dd yy"), "\n";
  264.  
  265. will print:
  266.  
  267.     Thursday, April 01, 1999
  268.     Thu, Apr 01 99
  269.  
  270. =item Dim()
  271.  
  272. Returns a list of array bounds for a VT_ARRAY variant.  The list contains
  273. an array reference for each dimension of the variant's SAFEARRAY.  This
  274. reference points to an array containing the lower and upper bounds for
  275. this dimension.  For example:
  276.  
  277.     my @Dim = $Var->Dim;
  278.  
  279. Now C<@Dim> contains the following list: C<([1,5], [0,2])>.
  280.  
  281. =item Get(DIM)
  282.  
  283. For normal variants C<Get> returns the value of the variant, just like the
  284. C<Value> method.  For VT_ARRAY variants C<Get> retrieves the value of a single
  285. array element.  In this case C<DIM> must be a list of array indices.  E.g.
  286.  
  287.     my $Val = $Var->Get(2,0);
  288.  
  289. As a special case for one dimensional VT_UI1|VT_ARRAY variants the C<Get>
  290. method without arguments returns the character array as a Perl string.
  291.  
  292.     print $String->Get, "\n";
  293.  
  294. =item LastError()
  295.  
  296. The use of the C<Win32::OLE::Variant->LastError()> method is deprecated.
  297. Please use the C<Win32::OLE->LastError()> class method instead.
  298.  
  299. =item Number([FORMAT[, LCID]])
  300.  
  301. This method converts the VARIANT value into a formatted number string.  The
  302. FORMAT can be either an integer constant or a hash reference.  Valid constants
  303. are 0 and LOCALE_NOUSEROVERRIDE.  You get the value of LOCALE_NOUSEROVERRIDE
  304. from the Win32::OLE::NLS module:
  305.  
  306.     use Win32::OLE::NLS qw(:LOCALE);
  307.  
  308. LOCALE_NOUSEROVERRIDE tells the method to use the system default number
  309. format for the specified locale, disregarding any changes that might have
  310. been made through the control panel application.
  311.  
  312. The hash reference could contain the following keys:
  313.  
  314.     NumDigits    number of fractional digits
  315.     LeadingZero    whether to use leading zeroes in decimal fields
  316.     Grouping    size of each group of digits to the left of the decimal
  317.     DecimalSep    decimal separator string
  318.     ThousandSep    thousand separator string
  319.     NegativeOrder    see L<Win32::OLE::NLS/LOCALE_INEGNUMBER>
  320.  
  321. =item Put(DIM, VALUE)
  322.  
  323. The C<Put> method is used to assign a new value to a variant.  The value will
  324. be coerced into the current type of the variant.  E.g.:
  325.  
  326.     my $Var = Variant(VT_I4, 42);
  327.     $Var->Put(3.1415);
  328.  
  329. This changes the value of the variant to C<3> because the type is VT_I4.
  330.  
  331. For VT_ARRAY type variants the indices for each dimension of the contained
  332. SAFEARRAY must be specified in front of the new value:
  333.  
  334.     $Array->Put(1, 1, 2.7);
  335.  
  336. It is also possible to assign values to *every* element of the SAFEARRAY at
  337. once using a single Put() method call:
  338.  
  339.     $Array->Put([[1,2], [3,4]]);
  340.  
  341. In this case the argument to Put() must be an array reference and the
  342. dimensions of the Perl list-of-lists must match the dimensions of the
  343. SAFEARRAY exactly.
  344.  
  345. The are a few special cases for one-dimensional VT_UI1 arrays: The VALUE
  346. can be specified as a string instead of a number.  This will set the selected
  347. character to the first character of the string or to '\0' if the string was
  348. empty:
  349.  
  350.     my $String = Variant(VT_UI1|VT_ARRAY, "ABCDE");
  351.     $String->Put(1, "123");
  352.     $String->Put(3, ord('Z'));
  353.     $String->Put(4, '');
  354.  
  355. This will set the value of C<$String> to C<"A1CZ\0">.  If the index is omitted
  356. then the string is copied to the value completely.  The string is truncated
  357. if it is longer than the size of the VT_UI1 array.  The result will be padded
  358. with '\0's if the string is shorter:
  359.  
  360.     $String->Put("String");
  361.  
  362. Now C<$String> contains the value "Strin".
  363.  
  364. C<Put> returns the Variant object itself so that multiple C<Put> calls can be
  365. chained together:
  366.  
  367.     $Array->Put(0,0,$First_value)->Put(0,1,$Another_value);
  368.  
  369. =item Time([FORMAT[, LCID]])
  370.  
  371. Converts the VARIANT into a formatted time string.  FORMAT can be either
  372. one of the following integer constants or a format string:
  373.  
  374.     LOCALE_NOUSEROVERRIDE    system default time format for this locale
  375.     TIME_NOMINUTESORSECONDS    don't use minutes or seconds
  376.     TIME_NOSECONDS        don't use seconds
  377.     TIME_NOTIMEMARKER    don't use a time marker
  378.     TIME_FORCE24HOURFORMAT    always use a 24-hour time format
  379.  
  380. The constants are available from the Win32::OLE::NLS module:
  381.  
  382.     use Win32::OLE::NLS qw(:LOCALE :TIME);
  383.  
  384. The following elements can be used to construct a time format string.
  385. Characters must be specified exactly as given below (e.g. "dd" B<not> "DD").
  386. Spaces can be inserted anywhere between formating codes, other verbatim
  387. text should be included in single quotes.
  388.  
  389.     h    hours; 12-hour clock
  390.     hh    hours with leading zero for single-digit hours; 12-hour clock
  391.     H    hours; 24-hour clock
  392.     HH    hours with leading zero for single-digit hours; 24-hour clock
  393.     m    minutes
  394.     mm    minutes with leading zero for single-digit minutes
  395.     s    seconds
  396.     ss    seconds with leading zero for single-digit seconds
  397.     t    one character time marker string, such as A or P
  398.     tt    multicharacter time marker string, such as AM or PM
  399.  
  400. For example:
  401.  
  402.     my $v = Variant(VT_DATE, "April 1 99 2:23 pm");
  403.     print $v->Time, "\n";
  404.     print $v->Time(TIME_FORCE24HOURFORMAT|TIME_NOTIMEMARKER), "\n";
  405.     print $v->Time("hh.mm.ss tt"), "\n";
  406.  
  407. will print:
  408.  
  409.     2:23:00 PM
  410.     14:23:00
  411.     02.23.00 PM
  412.  
  413. =item Type()
  414.  
  415. The C<Type> method returns the variant type of the contained VARIANT.
  416.  
  417. =item Unicode()
  418.  
  419. The C<Unicode> method returns a C<Unicode::String> object.  This contains
  420. the BSTR value of the variant in network byte order.  If the variant is
  421. not currently in VT_BSTR format then a VT_BSTR copy will be produced first.
  422.  
  423. =item Value()
  424.  
  425. The C<Value> method returns the value of the VARIANT as a Perl value.  The
  426. conversion is performed in the same manner as all return values of
  427. Win32::OLE method calls are converted.
  428.  
  429. =back
  430.  
  431. =head2 Overloading
  432.  
  433. The Win32::OLE::Variant package has overloaded the conversion to
  434. string and number formats.  Therefore variant objects can be used in
  435. arithmetic and string operations without applying the C<Value>
  436. method first.
  437.  
  438. =head2 Class Variables
  439.  
  440. The Win32::OLE::Variant class used to have its own set of class variables
  441. like C<$CP>, C<$LCID> and C<$Warn>.  In version 0.1003 and later of the
  442. Win32::OLE module these variables have been eleminated.  Now the settings
  443. of Win32::OLE are used by the Win32::OLE::Variant module too.  Please read
  444. the documentation of the C<Win32::OLE->Option> class method.
  445.  
  446.  
  447. =head2 Constants
  448.  
  449. These constants are exported by default:
  450.  
  451.     VT_EMPTY
  452.     VT_NULL
  453.     VT_I2
  454.     VT_I4
  455.     VT_R4
  456.     VT_R8
  457.     VT_CY
  458.     VT_DATE
  459.     VT_BSTR
  460.     VT_DISPATCH
  461.     VT_ERROR
  462.     VT_BOOL
  463.     VT_VARIANT
  464.     VT_UNKNOWN
  465.     VT_DECIMAL
  466.     VT_UI1
  467.  
  468.     VT_ARRAY
  469.     VT_BYREF
  470.  
  471. VT_DECIMAL is not on the official list of allowable OLE Automation
  472. datatypes.  But even Microsoft ADO seems to sometimes return values
  473. of Recordset fields in VT_DECIMAL format.
  474.  
  475. =head2 Variants
  476.  
  477. A Variant is a data type that is used to pass data between OLE
  478. connections.
  479.  
  480. The default behavior is to convert each perl scalar variable into
  481. an OLE Variant according to the internal perl representation.
  482. The following type correspondence holds:
  483.  
  484.         C type          Perl type       OLE type
  485.         ------          ---------       --------
  486.           int              IV            VT_I4
  487.         double             NV            VT_R8
  488.         char *             PV            VT_BSTR
  489.         void *           ref to AV       VT_ARRAY
  490.            ?              undef          VT_ERROR
  491.            ?        Win32::OLE object    VT_DISPATCH
  492.  
  493. Note that VT_BSTR is a wide character or Unicode string.  This presents a
  494. problem if you want to pass in binary data as a parameter as 0x00 is
  495. inserted between all the bytes in your data.  The C<Variant()> method
  496. provides a solution to this.  With Variants the script writer can specify
  497. the OLE variant type that the parameter should be converted to.  Currently
  498. supported types are:
  499.  
  500.         VT_UI1     unsigned char
  501.         VT_I2      signed int (2 bytes)
  502.         VT_I4      signed int (4 bytes)
  503.         VT_R4      float      (4 bytes)
  504.         VT_R8      float      (8 bytes)
  505.         VT_DATE    OLE Date
  506.         VT_BSTR    OLE String
  507.         VT_CY      OLE Currency
  508.         VT_BOOL    OLE Boolean
  509.  
  510. When VT_DATE and VT_CY objects are created, the input parameter is treated
  511. as a Perl string type, which is then converted to VT_BSTR, and finally to
  512. VT_DATE of VT_CY using the C<VariantChangeType()> OLE API function.
  513. See L<Win32::OLE/EXAMPLES> for how these types can be used.
  514.  
  515. =head2 Variant arrays
  516.  
  517. A variant can not only contain a single value but also a multi-dimensional
  518. array of values (called a SAFEARRAY).  In this case the VT_ARRAY flag must
  519. be added to the base variant type, e.g. C<VT_I4 | VT_ARRAY> for an array of
  520. integers.  The VT_EMPTY and VT_NULL types are invalid for SAFEARRAYs.  It
  521. is possible to create an array of variants: C<VT_VARIANT | VT_ARRAY>.  In this
  522. case each element of the array can have a different type (including VT_EMPTY
  523. and VT_NULL).  The elements of a VT_VARIANT SAFEARRAY cannot have either of the
  524. VT_ARRAY or VT_BYREF flags set.
  525.  
  526. The lower and upper bounds for each dimension can be specified separately.
  527. They do not have to have all the same lower bound (unlike Perl's arrays).
  528.  
  529. =head2 Variants by reference
  530.  
  531. Some OLE servers expect parameters passed by reference so that they
  532. can be changed in the method call.  This allows methods to easily
  533. return multiple values.  There is preliminary support for this in
  534. the Win32::OLE::Variant module:
  535.  
  536.     my $x = Variant(VT_I4|VT_BYREF, 0);
  537.     my $y = Variant(VT_I4|VT_BYREF, 0);
  538.     $Corel->GetSize($x, $y);
  539.     print "Size is $x by $y\n";
  540.  
  541. After the C<GetSize> method call C<$x> and C<$y> will be set to
  542. the respective sizes.  They will still be variants.  In the print
  543. statement the overloading converts them to string representation
  544. automatically.
  545.  
  546. VT_BYREF is now supported for all variant types (including SAFEARRAYs).
  547. It can also be used to pass an OLE object by reference:
  548.  
  549.     my $Results = $App->CreateResultsObject;
  550.     $Object->Method(Variant(VT_DISPATCH|VT_BYREF, $Results));
  551.  
  552. =head1 AUTHORS/COPYRIGHT
  553.  
  554. This module is part of the Win32::OLE distribution.
  555.  
  556. =cut
  557.