diff options
Diffstat (limited to 'Master/tlpkg/tlperl/site/lib/Win32/OLE.pm')
-rwxr-xr-x | Master/tlpkg/tlperl/site/lib/Win32/OLE.pm | 968 |
1 files changed, 0 insertions, 968 deletions
diff --git a/Master/tlpkg/tlperl/site/lib/Win32/OLE.pm b/Master/tlpkg/tlperl/site/lib/Win32/OLE.pm deleted file mode 100755 index ece534b15fa..00000000000 --- a/Master/tlpkg/tlperl/site/lib/Win32/OLE.pm +++ /dev/null @@ -1,968 +0,0 @@ -# The documentation is at the __END__ - -package Win32::OLE; - -use strict; -use vars qw($VERSION @ISA @EXPORT @EXPORT_OK @EXPORT_FAIL $AUTOLOAD - $CP $LCID $Warn $LastError $_NewEnum $_Unique); - -$VERSION = '0.1712'; - -use Carp; -use Exporter; -use DynaLoader; -@ISA = qw(Exporter DynaLoader); - -@EXPORT = qw(); -@EXPORT_OK = qw(in valof with HRESULT EVENTS OVERLOAD - CP_ACP CP_OEMCP CP_MACCP CP_UTF7 CP_UTF8 - DISPATCH_METHOD DISPATCH_PROPERTYGET - DISPATCH_PROPERTYPUT DISPATCH_PROPERTYPUTREF); -@EXPORT_FAIL = qw(EVENTS OVERLOAD); - -sub export_fail { - shift; - my @unknown; - while (@_) { - my $symbol = shift; - if ($symbol eq 'OVERLOAD') { - eval <<'OVERLOAD'; - use overload '""' => \&valof, - '0+' => \&valof, - fallback => 1; -OVERLOAD - } - elsif ($symbol eq 'EVENTS') { - Win32::OLE->Initialize(Win32::OLE::COINIT_OLEINITIALIZE()); - } - else { - push @unknown, $symbol; - } - } - return @unknown; -} - -unless (defined &Dispatch) { - # Use regular DynaLoader if XS part is not yet initialized - bootstrap Win32::OLE; - require Win32::OLE::Lite; -} - -1; - -######################################################################## - -__END__ - -=head1 NAME - -Win32::OLE - OLE Automation extensions - -=head1 SYNOPSIS - - $ex = Win32::OLE->new('Excel.Application') or die "oops\n"; - $ex->Amethod("arg")->Bmethod->{'Property'} = "foo"; - $ex->Cmethod(undef,undef,$Arg3); - $ex->Dmethod($RequiredArg1, {NamedArg1 => $Value1, NamedArg2 => $Value2}); - - $wd = Win32::OLE->GetObject("D:\\Data\\Message.doc"); - $xl = Win32::OLE->GetActiveObject("Excel.Application"); - -=head1 DESCRIPTION - -This module provides an interface to OLE Automation from Perl. -OLE Automation brings VisualBasic like scripting capabilities and -offers powerful extensibility and the ability to control many Win32 -applications from Perl scripts. - -The Win32::OLE module uses the IDispatch interface exclusively. It is -not possible to access a custom OLE interface. OLE events and OCX's are -currently not supported. - -Actually, that's no longer strictly true. This module now contains -B<ALPHA> level support for OLE events. This is largely untested and the -specific interface might still change in the future. - -=head2 Methods - -=over 8 - -=item Win32::OLE->new(PROGID[, DESTRUCTOR]) - -The new() class method starts a new instance of an OLE Automation object. -It returns a reference to this object or C<undef> if the creation failed. - -The PROGID argument must be either the OLE I<program id> or the I<class id> -of the required application. The optional DESTRUCTOR specifies a DESTROY-like -method. This can be either a CODE reference or a string containing an OLE -method name. It can be used to cleanly terminate OLE applications in case the -Perl program dies. - -To create an object via DCOM on a remote server you can use an array -reference in place of PROGID. The referenced array must contain the -machine name and the I<program id> or I<class id>. For example: - - my $obj = Win32::OLE->new(['my.machine.com', 'Program.Id']); - -If the PROGID is a I<program id> then Win32::OLE will try to resolve the -corresponding I<class id> locally. If the I<program id> is not registered -locally then the remote registry is queried. This will only succeed if -the local process has read access to the remote registry. The safest -(and fastest) method is to specify the C<class id> directly. - -=item Win32::OLE->EnumAllObjects([CALLBACK]) - -This class method returns the number Win32::OLE objects currently in -existence. It will call the optional CALLBACK function for each of -these objects: - - $Count = Win32::OLE->EnumAllObjects(sub { - my $Object = shift; - my $Class = Win32::OLE->QueryObjectType($Object); - printf "# Object=%s Class=%s\n", $Object, $Class; - }); - -The EnumAllObjects() method is primarily a debugging tool. It can be -used e.g. in an END block to check if all external connections have -been properly destroyed. - -=item Win32::OLE->FreeUnusedLibraries() - -The FreeUnusedLibraries() class method unloads all unused OLE -resources. These are the libraries of those classes of which all -existing objects have been destroyed. The unloading of object -libraries is really only important for long running processes that -might instantiate a huge number of B<different> objects over time. - -Be aware that objects implemented in Visual Basic have a buggy -implementation of this functionality: They pretend to be unloadable -while they are actually still running their cleanup code. Unloading -the DLL at that moment typically produces an access violation. The -probability for this problem can be reduced by calling the -SpinMessageLoop() method and sleep()ing for a few seconds. - -=item Win32::OLE->GetActiveObject(CLASS[, DESTRUCTOR]) - -The GetActiveObject() class method returns an OLE reference to a -running instance of the specified OLE automation server. It returns -C<undef> if the server is not currently active. It will croak if -the class is not even registered. The optional DESTRUCTOR method takes -either a method name or a code reference. It is executed when the last -reference to this object goes away. It is generally considered rude -to stop applications that you did not start yourself. - -=item Win32::OLE->GetObject(MONIKER[, DESTRUCTOR]) - -The GetObject() class method returns an OLE reference to the specified -object. The object is specified by a pathname optionally followed by -additional item subcomponent separated by exclamation marks '!'. The -optional DESTRUCTOR argument has the same semantics as the DESTRUCTOR in -new() or GetActiveObject(). - -=item Win32::OLE->Initialize([COINIT]) - -The Initialize() class method can be used to specify an alternative -apartment model for the Perl thread. It must be called B<before> the -first OLE object is created. If the C<Win32::OLE::Const> module is -used then the call to the Initialize() method must be made from a BEGIN -block before the first C<use> statement for the C<Win32::OLE::Const> -module. - -Valid values for COINIT are: - - Win32::OLE::COINIT_APARTMENTTHREADED - single threaded - Win32::OLE::COINIT_MULTITHREADED - the default - Win32::OLE::COINIT_OLEINITIALIZE - single threaded, additional OLE stuff - -COINIT_OLEINITIALIZE is sometimes needed when an OLE object uses -additional OLE compound document technologies not available from the -normal COM subsystem (for example MAPI.Session seems to require it). -Both COINIT_OLEINITIALIZE and COINIT_APARTMENTTHREADED create a hidden -top level window and a message queue for the Perl process. This may -create problems with other application, because Perl normally doesn't -process its message queue. This means programs using synchronous -communication between applications (such as DDE initiation), may hang -until Perl makes another OLE method call/property access or terminates. -This applies to InstallShield setups and many things started to shell -associations. Please try to utilize the C<Win32::OLE-E<gt>SpinMessageLoop> -and C<Win32::OLE-E<gt>Uninitialize> methods if you can not use the default -COINIT_MULTITHREADED model. - -=item OBJECT->Invoke(METHOD[, ARGS]) - -The Invoke() object method is an alternate way to invoke OLE -methods. It is normally equivalent to C<$OBJECT-E<gt>METHOD(@ARGS)>. This -function must be used if the METHOD name contains characters not valid -in a Perl variable name (like foreign language characters). It can -also be used to invoke the default method of an object even if the -default method has not been given a name in the type library. In this -case use <undef> or C<''> as the method name. To invoke an OLE objects -native Invoke() method (if such a thing exists), please use: - - $Object->Invoke('Invoke', @Args); - -=item Win32::OLE->LastError() - -The LastError() class method returns the last recorded OLE -error. This is a dual value like the C<$!> variable: in a numeric -context it returns the error number and in a string context it returns -the error message. The error number is a signed HRESULT value. Please -use the L<HRESULT(ERROR)> function to convert an unsigned hexadecimal -constant to a signed HRESULT. - -The last OLE error is automatically reset by a successful OLE -call. The numeric value can also explicitly be set by a call (which will -discard the string value): - - Win32::OLE->LastError(0); - -=item OBJECT->LetProperty(NAME,ARGS,VALUE) - -In Win32::OLE property assignment using the hash syntax is equivalent -to the Visual Basic C<Set> syntax (I<by reference> assignment): - - $Object->{Property} = $OtherObject; - -corresponds to this Visual Basic statement: - - Set Object.Property = OtherObject - -To get the I<by value> treatment of the Visual Basic C<Let> statement - - Object.Property = OtherObject - -you have to use the LetProperty() object method in Perl: - - $Object->LetProperty($Property, $OtherObject); - -LetProperty() also supports optional arguments for the property assignment. -See L<OBJECT->SetProperty(NAME,ARGS,VALUE)> for details. - -=item Win32::OLE->MessageLoop() - -The MessageLoop() class method will run a standard Windows message -loop, dispatching messages until the QuitMessageLoop() class method is -called. It is used to wait for OLE events. - -=item Win32::OLE->Option(OPTION) - -The Option() class method can be used to inspect and modify -L<Module Options>. The single argument form retrieves the value of -an option: - - my $CP = Win32::OLE->Option('CP'); - -A single call can be used to set multiple options simultaneously: - - Win32::OLE->Option(CP => CP_ACP, Warn => 3); - -=item Win32::OLE->QueryObjectType(OBJECT) - -The QueryObjectType() class method returns a list of the type library -name and the objects class name. In a scalar context it returns the -class name only. It returns C<undef> when the type information is not -available. - -=item Win32::OLE->QuitMessageLoop() - -The QuitMessageLoop() class method posts a (user-level) "Quit" message -to the current threads message loop. QuitMessageLoop() is typically -called from an event handler. The MessageLoop() class method will -return when it receives this "Quit" method. - -=item OBJECT->SetProperty(NAME,ARGS,VALUE) - -The SetProperty() method allows to modify properties with arguments, -which is not supported by the hash syntax. The hash form - - $Object->{Property} = $Value; - -is equivalent to - - $Object->SetProperty('Property', $Value); - -Arguments must be specified between the property name and the new value: - - $Object->SetProperty('Property', @Args, $Value); - -It is not possible to use "named argument" syntax with this function -because the new value must be the last argument to SetProperty(). - -This method hides any native OLE object method called SetProperty(). -The native method will still be available through the Invoke() method: - - $Object->Invoke('SetProperty', @Args); - -=item Win32::OLE->SpinMessageLoop - -This class method retrieves all pending messages from the message queue -and dispatches them to their respective window procedures. Calling this -method is only necessary when not using the COINIT_MULTITHREADED model. -All OLE method calls and property accesses automatically process the -message queue. - -=item Win32::OLE->Uninitialize - -The Uninitialize() class method uninitializes the OLE subsystem. It -also destroys the hidden top level window created by OLE for single -threaded apartments. All OLE objects will become invalid after this call! -It is possible to call the Initialize() class method again with a different -apartment model after shutting down OLE with Uninitialize(). - -=item Win32::OLE->WithEvents(OBJECT[, HANDLER[, INTERFACE]]) - -This class method enables and disables the firing of events by the -specified OBJECT. If no HANDLER is specified, then events are -disconnected. For some objects Win32::OLE is not able to -automatically determine the correct event interface. In this case the -INTERFACE argument must contain either the COCLASS name of the OBJECT -or the name of the event DISPATCH interface. Please read the L<Events> -section below for detailed explanation of the Win32::OLE event -support. - -=back - -Whenever Perl does not find a method name in the Win32::OLE package it -is automatically used as the name of an OLE method and this method call -is dispatched to the OLE server. - -There is one special hack built into the module: If a method or property -name could not be resolved with the OLE object, then the default method -of the object is called with the method name as its first parameter. So - - my $Sheet = $Worksheets->Table1; -or - my $Sheet = $Worksheets->{Table1}; - -is resolved as - - my $Sheet = $Worksheet->Item('Table1'); - -provided that the $Worksheets object does not have a C<Table1> method -or property. This hack has been introduced to call the default method -of collections which did not name the method in their type library. The -recommended way to call the "unnamed" default method is: - - my $Sheet = $Worksheets->Invoke('', 'Table1'); - -This special hack is disabled under C<use strict 'subs';>. - -=head2 Object methods and properties - -The object returned by the new() method can be used to invoke -methods or retrieve properties in the same fashion as described -in the documentation for the particular OLE class (eg. Microsoft -Excel documentation describes the object hierarchy along with the -properties and methods exposed for OLE access). - -Optional parameters on method calls can be omitted by using C<undef> -as a placeholder. A better way is to use named arguments, as the -order of optional parameters may change in later versions of the OLE -server application. Named parameters can be specified in a reference -to a hash as the last parameter to a method call. - -Properties can be retrieved or set using hash syntax, while methods -can be invoked with the usual perl method call syntax. The C<keys> -and C<each> functions can be used to enumerate an object's properties. -Beware that a property is not always writable or even readable (sometimes -raising exceptions when read while being undefined). - -If a method or property returns an embedded OLE object, method -and property access can be chained as shown in the examples below. - -=head2 Functions - -The following functions are not exported by default. - -=over 8 - -=item HRESULT(ERROR) - -The HRESULT() function converts an unsigned number into a signed HRESULT -error value as used by OLE internally. This is necessary because Perl -treats all hexadecimal constants as unsigned. To check if the last OLE -function returned "Member not found" (0x80020003) you can write: - - if (Win32::OLE->LastError == HRESULT(0x80020003)) { - # your error recovery here - } - -=item in(COLLECTION) - -If COLLECTION is an OLE collection object then C<in $COLLECTION> -returns a list of all members of the collection. This is a shortcut -for C<Win32::OLE::Enum-E<gt>All($COLLECTION)>. It is most commonly used in -a C<foreach> loop: - - foreach my $value (in $collection) { - # do something with $value here - } - -=item valof(OBJECT) - -Normal assignment of Perl OLE objects creates just another reference -to the OLE object. The valof() function explictly dereferences the -object (through the default method) and returns the value of the object. - - my $RefOf = $Object; - my $ValOf = valof $Object; - $Object->{Value} = $NewValue; - -Now $ValOf still contains the old value whereas $RefOf would -resolve to the $NewValue because it is still a reference to -$Object. - -The valof() function can also be used to convert Win32::OLE::Variant -objects to Perl values. - -=item with(OBJECT, PROPERTYNAME => VALUE, ...) - -This function provides a concise way to set the values of multiple -properties of an object. It iterates over its arguments doing -C<$OBJECT-E<gt>{PROPERTYNAME} = $VALUE> on each trailing pair. - -=back - -=head2 Overloading - -The Win32::OLE objects can be overloaded to automatically convert to -their values whenever they are used in a bool, numeric or string -context. This is not enabled by default. You have to request it -through the OVERLOAD pseudoexport: - - use Win32::OLE qw(in valof with OVERLOAD); - -You can still get the original string representation of an object -(C<Win32::OLE=0xDEADBEEF>), e.g. for debugging, by using the -C<overload::StrVal()> method: - - print overload::StrVal($object), "\n"; - -Please note that C<OVERLOAD> is a global setting. If any module enables -Win32::OLE overloading then it's active everywhere. - -=head2 Events - -The Win32::OLE module now contains B<ALPHA> level event support. This -support is only available when Perl is running in a single threaded -apartment. This can most easily be assured by using the C<EVENTS> -pseudo-import: - - use Win32::OLE qw(EVENTS); - -which implicitly does something like: - - use Win32::OLE; - Win32::OLE->Initialize(Win32::OLE::COINIT_OLEINITIALIZE); - -The current interface to OLE events should be considered experimental -and is subject to change. It works as expected for normal OLE -applications, but OLE control events often don't seem to work yet. - -Events must be enabled explicitly for an OLE object through the -Win32::OLE->WithEvents() class method. The Win32::OLE module uses the -IProvideClassInfo2 interface to determine the default event source of -the object. If this interface is not supported, then the user must -specify the name of the event source explicitly in the WithEvents() -method call. It is also possible to specify the class name of the -object as the third parameter. In this case Win32::OLE will try to -look up the default source interface for this COCLASS. - -The HANDLER argument to Win32::OLE->WithEvents() can either be a CODE -reference or a package name. In the first case, all events will invoke -this particular function. The first two arguments to this function will -be the OBJECT itself and the name of the event. The remaining arguments -will be event specific. - - sub Event { - my ($Obj,$Event,@Args) = @_; - print "Event triggered: '$Event'\n"; - } - Win32::OLE->WithEvents($Obj, \&Event); - -Alternatively the HANDLER argument can specify a package name. When the -OBJECT fires an event, Win32::OLE will try to find a function of the same -name as the event in this package. This function will be called with the -OBJECT as the first argument followed again by the event specific parameters: - - package MyEvents; - sub EventName1 { - my ($Obj,@Args) = @_; - print "EventName1 event triggered\n"; - } - - package main; - Win32::OLE->WithEvents($Obj, 'MyEvents', 'IEventInterface'); - -If Win32::OLE doesn't find a function with the name of the event then nothing -happens. - -Event parameters passed I<by reference> are handled specially. They are not -converted to the corresponding Perl datatype but passed as Win32::OLE::Variant -objects. You can assign a new value to these objects with the help of the -Put() method. This value will be passed back to the object when the event -function returns: - - package MyEvents; - sub BeforeClose { - my ($self,$Cancel) = @_; - $Cancel->Put(1) unless $MayClose; - } - -Direct assignment to $Cancel would have no effect on the original value and -would therefore not command the object to abort the closing action. - -=head2 Module Options - -The following module options can be accessed and modified with the -C<Win32::OLE-E<gt>Option> class method. In earlier versions of the Win32::OLE -module these options were manipulated directly as class variables. This -practice is now deprecated. - -=over 8 - -=item CP - -This variable is used to determine the codepage used by all -translations between Perl strings and Unicode strings used by the OLE -interface. The default value is CP_ACP, which is the default ANSI -codepage. Other possible values are CP_OEMCP, CP_MACCP, CP_UTF7 and -CP_UTF8. These constants are not exported by default. - -=item LCID - -This variable controls the locale identifier used for all OLE calls. -It is set to LOCALE_NEUTRAL by default. Please check the -L<Win32::OLE::NLS> module for other locale related information. - -=item Variant - -This options controls how method calls and property accessors return -values of type VT_CY and VT_DECIMAL are being returned. By default -VT_CY values are turned into strings and VT_DECIMAL values into -floating point numbers. If the C<Variant> option is enabled, these -values are returned as Win32::OLE::Variant objects, just like VT_DATE -and VT_ERROR values. If the Win32::OLE::Variant module is also -loaded, then all values should still behave as before in string and in -numeric context. - -The only reason that the C<Variant> behavior is not the default is that -this is an incompatible change that might break existing programs. - -=item Warn - -This variable determines the behavior of the Win32::OLE module when -an error happens. Valid values are: - - 0 Ignore error, return undef - 1 Carp::carp if $^W is set (-w option) - 2 always Carp::carp - 3 Carp::croak - -The error number and message (without Carp line/module info) are -available through the C<Win32::OLE-E<gt>LastError> class method. - -Alternatively the Warn option can be set to a CODE reference. E.g. - - Win32::OLE->Option(Warn => 3); - -is equivalent to - - Win32::OLE->Option(Warn => \&Carp::croak); - -This can even be used to emulate the VisualBasic C<On Error Goto -Label> construct: - - Win32::OLE->Option(Warn => sub {goto CheckError}); - # ... your normal OLE code here ... - - CheckError: - # ... your error handling code here ... - -=item _NewEnum - -This option enables additional enumeration support for collection -objects. When the C<_NewEnum> option is set, all collections will -receive one additional property: C<_NewEnum>. The value of this -property will be a reference to an array containing all the elements -of the collection. This option can be useful when used in conjunction -with an automatic tree traversal program, like C<Data::Dumper> or an -object tree browser. The value of this option should be either 1 -(enabled) or 0 (disabled, default). - - Win32::OLE->Option(_NewEnum => 1); - # ... - my @sheets = @{$Excel->Worksheets->{_NewEnum}}; - -In normal application code, this would be better written as: - - use Win32::OLE qw(in); - # ... - my @sheets = in $Excel->Worksheets; - -=item _Unique - -The C<_Unique> options guarantees that Win32::OLE will maintain a -one-to-one mapping between Win32::OLE objects and the native COM/OLE -objects. Without this option, you can query the same property twice -and get two different Win32::OLE objects for the same underlying COM -object. - -Using a unique proxy makes life easier for tree traversal algorithms -to recognize they already visited a particular node. This option -comes at a price: Win32::OLE has to maintain a global hash of all -outstanding objects and their corresponding proxies. Identity checks -on COM objects can also be expensive if the objects reside -out-of-process or even on a different computer. Therefore this option -is off by default unless the program is being run in the debugger. - -Unfortunately, this option doesn't always help. Some programs will -return new COM objects for even the same property when asked for it -multiple times (especially for collections). In this case, there is -nothing Win32::OLE can do to detect that these objects are in fact -identical (because they aren't at the COM level). - -The C<_Unique> option can be set to either 1 (enabled) or 0 (disabled, -default). - -=back - -=head1 EXAMPLES - -Here is a simple Microsoft Excel application. - - use Win32::OLE; - - # use existing instance if Excel is already running - eval {$ex = Win32::OLE->GetActiveObject('Excel.Application')}; - die "Excel not installed" if $@; - unless (defined $ex) { - $ex = Win32::OLE->new('Excel.Application', sub {$_[0]->Quit;}) - or die "Oops, cannot start Excel"; - } - - # get a new workbook - $book = $ex->Workbooks->Add; - - # write to a particular cell - $sheet = $book->Worksheets(1); - $sheet->Cells(1,1)->{Value} = "foo"; - - # write a 2 rows by 3 columns range - $sheet->Range("A8:C9")->{Value} = [[ undef, 'Xyzzy', 'Plugh' ], - [ 42, 'Perl', 3.1415 ]]; - - # print "XyzzyPerl" - $array = $sheet->Range("A8:C9")->{Value}; - for (@$array) { - for (@$_) { - print defined($_) ? "$_|" : "<undef>|"; - } - print "\n"; - } - - # save and exit - $book->SaveAs( 'test.xls' ); - undef $book; - undef $ex; - -Please note the destructor specified on the Win32::OLE->new method. It ensures -that Excel will shutdown properly even if the Perl program dies. Otherwise -there could be a process leak if your application dies after having opened -an OLE instance of Excel. It is the responsibility of the module user to -make sure that all OLE objects are cleaned up properly! - -Here is an example of using Variant data types. - - use Win32::OLE; - use Win32::OLE::Variant; - $ex = Win32::OLE->new('Excel.Application', \&OleQuit) or die "oops\n"; - $ex->{Visible} = 1; - $ex->Workbooks->Add; - # should generate a warning under -w - $ovR8 = Variant(VT_R8, "3 is a good number"); - $ex->Range("A1")->{Value} = $ovR8; - $ex->Range("A2")->{Value} = Variant(VT_DATE, 'Jan 1,1970'); - - sub OleQuit { - my $self = shift; - $self->Quit; - } - -The above will put value "3" in cell A1 rather than the string -"3 is a good number". Cell A2 will contain the date. - -Similarly, to invoke a method with some binary data, you can -do the following: - - $obj->Method( Variant(VT_UI1, "foo\000b\001a\002r") ); - -Here is a wrapper class that basically delegates everything but -new() and DESTROY(). The wrapper class shown here is another way to -properly shut down connections if your application is liable to die -without proper cleanup. Your own wrappers will probably do something -more specific to the particular OLE object you may be dealing with, -like overriding the methods that you may wish to enhance with your -own. - - package Excel; - use Win32::OLE; - - sub new { - my $s = {}; - if ($s->{Ex} = Win32::OLE->new('Excel.Application')) { - return bless $s, shift; - } - return undef; - } - - sub DESTROY { - my $s = shift; - if (exists $s->{Ex}) { - print "# closing connection\n"; - $s->{Ex}->Quit; - return undef; - } - } - - sub AUTOLOAD { - my $s = shift; - $AUTOLOAD =~ s/^.*:://; - $s->{Ex}->$AUTOLOAD(@_); - } - - 1; - -The above module can be used just like Win32::OLE, except that -it takes care of closing connections in case of abnormal exits. -Note that the effect of this specific example can be easier accomplished -using the optional destructor argument of Win32::OLE::new: - - my $Excel = Win32::OLE->new('Excel.Application', sub {$_[0]->Quit;}); - -Note that the delegation shown in the earlier example is not the same as -true subclassing with respect to further inheritance of method calls in your -specialized object. See L<perlobj>, L<perltoot> and L<perlbot> for details. -True subclassing (available by setting C<@ISA>) is also feasible, -as the following example demonstrates: - - # - # Add error reporting to Win32::OLE - # - - package Win32::OLE::Strict; - use Carp; - use Win32::OLE; - - use strict qw(vars); - use vars qw($AUTOLOAD @ISA); - @ISA = qw(Win32::OLE); - - sub AUTOLOAD { - my $obj = shift; - $AUTOLOAD =~ s/^.*:://; - my $meth = $AUTOLOAD; - $AUTOLOAD = "SUPER::" . $AUTOLOAD; - my $retval = $obj->$AUTOLOAD(@_); - unless (defined($retval) || $AUTOLOAD eq 'DESTROY') { - my $err = Win32::OLE::LastError(); - croak(sprintf("$meth returned OLE error 0x%08x",$err)) - if $err; - } - return $retval; - } - - 1; - -This package inherits the constructor new() from the Win32::OLE -package. It is important to note that you cannot later rebless a -Win32::OLE object as some information about the package is cached by -the object. Always invoke the new() constructor through the right -package! - -Here's how the above class will be used: - - use Win32::OLE::Strict; - my $Excel = Win32::OLE::Strict->new('Excel.Application', 'Quit'); - my $Books = $Excel->Workbooks; - $Books->UnknownMethod(42); - -In the sample above the call to UnknownMethod() will be caught with - - UnknownMethod returned OLE error 0x80020009 at test.pl line 5 - -because the Workbooks object inherits the class C<Win32::OLE::Strict> from the -C<$Excel> object. - -=head1 NOTES - -=head2 Hints for Microsoft Office automation - -=over 8 - -=item Documentation - -The object model for the Office applications is defined in the Visual Basic -reference guides for the various applications. These are typically not -installed by default during the standard installation. They can be added -later by rerunning the setup program with the custom install option. - -=item Class, Method and Property names - -The names have been changed between different versions of Office. For -example C<Application> was a method in Office 95 and is a property in -Office97. Therefore it will not show up in the list of property names -C<keys %$object> when querying an Office 95 object. - -The class names are not always identical to the method/property names -producing the object. E.g. the C<Workbook> method returns an object of -type C<Workbook> in Office 95 and C<_Workbook> in Office 97. - -=item Moniker (GetObject support) - -Office applications seem to implement file monikers only. For example -it seems to be impossible to retrieve a specific worksheet object through -C<GetObject("File.XLS!Sheet")>. Furthermore, in Excel 95 the moniker starts -a Worksheet object and in Excel 97 it returns a Workbook object. You can use -either the Win32::OLE::QueryObjectType class method or the $object->{Version} -property to write portable code. - -=item Enumeration of collection objects - -Enumerations seem to be incompletely implemented. Office 95 application don't -seem to support neither the Reset() nor the Clone() methods. The Clone() -method is still unimplemented in Office 97. A single walk through the -collection similar to Visual Basics C<for each> construct does work however. - -=item Localization - -Starting with Office 97 Microsoft has changed the localized class, method and -property names back into English. Note that string, date and currency -arguments are still subject to locale specific interpretation. Perl uses the -system default locale for all OLE transaction whereas Visual Basic uses a -type library specific locale. A Visual Basic script would use "R1C1" in string -arguments to specify relative references. A Perl script running on a German -language Windows would have to use "Z1S1". Set the LCID module option -to an English locale to write portable scripts. This variable should -not be changed after creating the OLE objects; some methods seem to randomly -fail if the locale is changed on the fly. - -=item SaveAs method in Word 97 doesn't work - -This is an known bug in Word 97. Search the MS knowledge base for Word / -Foxpro incompatibility. That problem applies to the Perl OLE interface as -well. A workaround is to use the WordBasic compatibility object. It doesn't -support all the options of the native method though. - - $Word->WordBasic->FileSaveAs($file); - -The problem seems to be fixed by applying the Office 97 Service Release 1. - -=item Randomly failing method calls - -It seems like modifying objects that are not selected/activated is sometimes -fragile. Most of these problems go away if the chart/sheet/document is -selected or activated before being manipulated (just like an interactive -user would automatically do it). - -=back - -=head2 Incompatibilities - -There are some incompatibilities with the version distributed by Activeware -(as of build 306). - -=over 8 - -=item 1 - -The package name has changed from "OLE" to "Win32::OLE". - -=item 2 - -All functions of the form "Win32::OLEFoo" are now "Win32::OLE::Foo", -though the old names are temporarily accommodated. Win32::OLECreateObject() -was changed to Win32::OLE::CreateObject(), and is now called -Win32::OLE::new() bowing to established convention for naming constructors. -The old names should be considered deprecated, and will be removed in the -next version. - -=item 3 - -Package "OLE::Variant" is now "Win32::OLE::Variant". - -=item 4 - -The Variant function is new, and is exported by default. So are -all the VT_XXX type constants. - -=item 5 - -The support for collection objects has been moved into the package -Win32::OLE::Enum. The C<keys %$object> method is now used to enumerate -the properties of the object. - -=back - -=head2 Bugs and Limitations - -=over 8 - -=item * - -To invoke a native OLE method with the same name as one of the -Win32::OLE methods (C<Dispatch>, C<Invoke>, C<SetProperty>, C<DESTROY>, -etc.), you have to use the C<Invoke> method: - - $Object->Invoke('Dispatch', @AdditionalArgs); - -The same is true for names exported by the Exporter or the Dynaloader -modules, e.g.: C<export>, C<export_to_level>, C<import>, -C<_push_tags>, C<export_tags>, C<export_ok_tags>, C<export_fail>, -C<require_version>, C<dl_load_flags>, -C<croak>, C<bootstrap>, C<dl_findfile>, C<dl_expandspec>, -C<dl_find_symbol_anywhere>, C<dl_load_file>, C<dl_find_symbol>, -C<dl_undef_symbols>, C<dl_install_xsub> and C<dl_error>. - -=back - -=head1 SEE ALSO - -The documentation for L<Win32::OLE::Const>, L<Win32::OLE::Enum>, -L<Win32::OLE::NLS> and L<Win32::OLE::Variant> contains additional -information about OLE support for Perl on Win32. - -=head1 AUTHORS - -Originally put together by the kind people at Hip and Activeware. - -Gurusamy Sarathy <gsar@cpan.org> subsequently fixed several -major bugs, memory leaks, and reliability problems, along with some -redesign of the code. - -Jan Dubois <jand@activestate.com> pitched in with yet more massive redesign, -added support for named parameters, and other significant enhancements. -He's been hacking on it ever since. - -Please send questions about problems with this module to the -Perl-Win32-Users mailinglist at ActiveState.com. The mailinglist charter -requests that you put an [OLE] tag somewhere on the subject line (for OLE -related questions only, of course). - -=head1 COPYRIGHT - - (c) 1995 Microsoft Corporation. All rights reserved. - Developed by ActiveWare Internet Corp., now known as - ActiveState Tool Corp., http://www.ActiveState.com - - Other modifications Copyright (c) 1997-2006 by Gurusamy Sarathy - <gsar@cpan.org> and Jan Dubois <jand@activestate.com> - - You may distribute under the terms of either the GNU General Public - License or the Artistic License, as specified in the README file. - -=head1 VERSION - -Version 0.1712 14 May 2014 - -=cut |