ole.pm

ARM上的如果你对底层感兴趣

# 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);

$VERSION = '0.1005';

use Carp;
use Exporter;
use DynaLoader;
@ISA = qw(Exporter DynaLoader);

@EXPORT = qw();
@EXPORT_OK = qw(CP_ACP CP_OEMCP CP_MACCP CP_UTF7 CP_UTF8 in valof with OVERLOAD
		DISPATCH_METHOD DISPATCH_PROPERTYGET
		DISPATCH_PROPERTYPUT DISPATCH_PROPERTYPUTREF);
@EXPORT_FAIL = qw(OVERLOAD);

sub export_fail {
    shift;
    if ($_[0] eq 'OVERLOAD') {
	shift;
	eval <<'OVERLOAD';
	    use overload '""'     => \&valof,
	                 '0+'     => \&valof,
	                 fallback => 1;
OVERLOAD
    }
    return @_;
}

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.

=head2 Methods

=over 8

=item Win32::OLE->new(PROGID [, DESTRUCTOR])

OLE Automation objects are created using the new() method, the second
argument to which must be the OLE program id or class id of the
application to create.  Return value is undef if the attempt to create
an OLE connection failed for some reason. The optional third argument
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 objects in case the Perl program dies in the middle of
OLE activity.

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.

=item Win32::OLE->GetActiveObject(CLASS)

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.

=item Win32::OLE->GetObject(MONIKER)

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 '!'.

=item Win32::OLE->Initialize(COINIT)

The C<Initialize> class method can be used to specify an alternative
apartment model for the Perl thread. It must be called before the
first object is created. 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 C<Invoke> object method is an alternate way to invoke OLE
methods. It is normally equivalent to C<$OBJECT->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 C<Invoke> method (if such a thing exists), please use:

	$Object->Invoke('Invoke', @Args);

=item Win32::OLE->LastError()

The C<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 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 Win32::OLE->Option(OPTION)

The C<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 C<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 OBJECT->SetProperty(NAME,ARGS,VALUE)

The C<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.
It is not possible to use "named argument" syntax with this function
because the new value must be the last argument to C<SetProperty>.

This method hides any native OLE object method called C<SetProperty>.
The native method will still be available through the C<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 C<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 C<Initialize> class method again with a different
apartment model after shutting down OLE with C<Uninitialize>.

=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 C<$Worksheets> object doesnot 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 Functions

The following functions are not exported by default.

=over 8

=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->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 C<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 C<$ValOf> still contains the old value wheras C<$RefOf> would
resolve to the C<$NewValue> because it is still a reference to
C<$Object>.

The C<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->{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 C<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 Module Options

The following module options can be accessed and modified with the
C<Win32::OLE->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 idnetifier 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 Warn

This variable determines the behavior of the Win32::OLE module when
an error happens. Valid values are: