You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
332 lines
11 KiB
332 lines
11 KiB
=pod
|
|
|
|
=head1 NAME
|
|
|
|
Win32::OLE::NEWS - What's new in Win32::OLE
|
|
|
|
This file contains a history of user visible changes to the
|
|
Win32::OLE::* modules. Only new features and major bug fixes that
|
|
might affect backwards compatibility are included.
|
|
|
|
=head1 Version 0.13
|
|
|
|
=head2 nothing() method in Win32::OLE::Variant
|
|
|
|
The nothing() function returns an empty VT_DISPATCH variant. It can be
|
|
used to clear an object reference stored in a property
|
|
|
|
use Win32::OLE::Variant qw(:DEFAULT nothing);
|
|
# ...
|
|
$object->{Property} = nothing;
|
|
|
|
This has the same effect as the Visual Basic statement
|
|
|
|
Set object.Property = Nothing
|
|
|
|
=head2 new _NewEnum and _Unique options
|
|
|
|
There are two new options available for the Win32::OLE->Option class
|
|
method: C<_NewEnum> provides the elements of a collection object
|
|
directly as the value of a C<_NewEnum> property. The C<_Unique>
|
|
option guarantees that Win32::OLE will not create multiple proxy
|
|
objects for the same underlying COM/OLE object.
|
|
|
|
Both options are only really useful to tree traversal programs or
|
|
during debugging.
|
|
|
|
|
|
=head1 Version 0.12
|
|
|
|
=head2 Additional error handling functionality
|
|
|
|
The Warn option can now be set to a CODE reference too. For example,
|
|
|
|
Win32::OLE->Option(Warn => 3);
|
|
|
|
could now be written as
|
|
|
|
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 ...
|
|
|
|
=head2 Builtin event loop
|
|
|
|
Processing OLE events required a polling loop before, e.g.
|
|
|
|
my $Quit;
|
|
#...
|
|
until ($Quit) {
|
|
Win32::OLE->SpinMessageLoop;
|
|
Win32::Sleep(100);
|
|
}
|
|
package BrowserEvents;
|
|
sub OnQuit { $Quit = 1 }
|
|
|
|
This is inefficient and a bit odd. This version of Win32::OLE now
|
|
supports a standard messageloop:
|
|
|
|
Win32::OLE->MessageLoop();
|
|
|
|
package BrowserEvents;
|
|
sub OnQuit { Win32::OLE->QuitMessageLoop }
|
|
|
|
=head2 Free unused OLE libraries
|
|
|
|
Previous versions of Win32::OLE would call the CoFreeUnusedLibraries()
|
|
API whenever an OLE object was destroyed. This made sure that OLE
|
|
libraries would be unloaded as soon as they were no longer needed.
|
|
Unfortunately, objects implemented in Visual Basic tend to crash
|
|
during this call, as they pretend to be ready for unloading, when in
|
|
fact, they aren't.
|
|
|
|
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. Therefore this API is no longer called
|
|
automatically. The functionality is now available explicitly to those
|
|
who want or need it by calling a Win32::OLE class method:
|
|
|
|
Win32::OLE->FreeUnusedLibraries();
|
|
|
|
=head2 The "Win32::OLE" article from "The Perl Journal #10"
|
|
|
|
The article is Copyright 1998 by I<The Perl
|
|
Journal>. http://www.tpj.com
|
|
|
|
It originally appeared in I<The Perl Journal> # 10 and appears here
|
|
courtesy of Jon Orwant and I<The Perl Journal>. The sample code from
|
|
the article is in the F<eg/tpj.pl> file.
|
|
|
|
=head2 VARIANT->Put() bug fixes
|
|
|
|
The Put() method didn't work correctly for arrays of type VT_BSTR,
|
|
VT_DISPATH or VT_UNKNOWN. This has been fixed.
|
|
|
|
=head2 Error message fixes
|
|
|
|
Previous versions of Win32::OLE gave a wrong argument index for some
|
|
OLE error messages (the number was too large by 1). This should be
|
|
fixed now.
|
|
|
|
=head2 VT_DATE and VT_ERROR return values handled differently
|
|
|
|
Method calls and property accesses returning a VT_DATE or VT_ERROR
|
|
value would previously translate the value to string or integer
|
|
format. This has been changed to return a Win32::OLE::Variant object.
|
|
The return values will behave as before if the Win32::OLE::Variant
|
|
module is being used. This module overloads the conversion of
|
|
the objects to strings and numbers.
|
|
|
|
|
|
=head1 Version 0.11 (changes since 0.1008)
|
|
|
|
=head2 new DHTML typelib browser
|
|
|
|
The Win32::OLE distribution now contains a type library browser. It
|
|
is written in PerlScript, generating dynamic HTML. It requires
|
|
Internet Explorer 4.0 or later. You'll find it in
|
|
F<browser/Browser.html>. It should be available in the ActivePerl
|
|
HTML help under Win32::OLE::Browser.
|
|
|
|
After selecting a library, type or member you can press F1 to call up
|
|
the corresponding help file at the appropriate location.
|
|
|
|
=head2 VT_DECIMAL support
|
|
|
|
The Win32::OLE::Variant module now supports VT_DECIMAL variants too.
|
|
They are not "officially" allowed in OLE Automation calls, but even
|
|
Microsoft's "ActiveX Data Objects" sometimes returns VT_DECIMAL
|
|
values.
|
|
|
|
VT_DECIMAL variables are stored as 96-bit integers scaled by a
|
|
variable power of 10. The power of 10 scaling factor specifies the
|
|
number of digits to the right of the decimal point, and ranges from 0
|
|
to 28. With a scale of 0 (no decimal places), the largest possible
|
|
value is +/-79,228,162,514,264,337,593,543,950,335. With a 28 decimal
|
|
places, the largest value is +/-7.9228162514264337593543950335 and the
|
|
smallest, non-zero value is +/-0.0000000000000000000000000001.
|
|
|
|
=head1 Version 0.1008
|
|
|
|
=head2 new LetProperty() object method
|
|
|
|
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);
|
|
|
|
=head2 new HRESULT() function
|
|
|
|
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
|
|
}
|
|
|
|
=head1 Version 0.1007 (changes since 0.1005)
|
|
|
|
=head2 OLE Event support
|
|
|
|
This version of Win32::OLE contains B<ALPHA> level support for OLE events. The
|
|
userinterface is still subject to change. There are ActiveX objects / controls
|
|
that don't fire events under the current implementation.
|
|
|
|
Events are enabled for a specific object with the Win32::OLE->WithEvents()
|
|
class method:
|
|
|
|
Win32::OLE->WithEvents(OBJECT, HANDLER, INTERFACE)
|
|
|
|
Please read further documentation in Win32::OLE.
|
|
|
|
=head2 GetObject() and GetActiveObject() now support optional DESTRUCTOR argument
|
|
|
|
It is now possible to specify a DESTRUCTOR argument to the GetObject() and
|
|
GetActiveObject() class methods. They work identical to the new() DESTRUCTOR
|
|
argument.
|
|
|
|
=head2 Remote object instantiation via DCOM
|
|
|
|
This has actually been in Win32::OLE since 0.0608, but somehow never got
|
|
documented. You can provide an array reference in place of the usual PROGID
|
|
parameter to Win32::OLE->new():
|
|
|
|
OBJ = Win32::OLE->new([MACHINE, PRODID]);
|
|
|
|
The array must contain two elements: the name of the MACHINE and the PROGID.
|
|
This will try to create the object on the remote MACHINE.
|
|
|
|
=head2 Enumerate all Win32::OLE objects
|
|
|
|
This class method returns the number Win32::OLE objects currently in
|
|
existance. 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.
|
|
|
|
=head2 The VARIANT->Put() method now returns the VARIANT object itself
|
|
|
|
This allows chaining of Put() method calls to set multiple values in an
|
|
array variant:
|
|
|
|
$Array->Put(0,0,$First_value)->Put(0,1,$Another_value);
|
|
|
|
=head2 The VARIANT->Put(ARRAYREF) form allows assignment to a complete SAFEARRAY
|
|
|
|
This allows automatic conversion from a list of lists to a SAFEARRAY.
|
|
You can now write:
|
|
|
|
my $Array = Variant(VT_ARRAY|VT_R8, [1,2], 2);
|
|
$Array->Put([[1,2], [3,4]]);
|
|
|
|
instead of the tedious:
|
|
|
|
$Array->Put(1,0,1);
|
|
$Array->Put(1,1,2);
|
|
$Array->Put(2,0,3);
|
|
$Array->Put(2,1,4);
|
|
|
|
=head2 New Variant formatting methods
|
|
|
|
There are four new methods for formatting variant values: Currency(), Date(),
|
|
Number() and Time(). 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
|
|
|
|
=head2 new Win32::OLE::NLS methods: SendSettingChange() and SetLocaleInfo()
|
|
|
|
SendSettingChange() sends a WM_SETTINGCHANGE message to all top level windows.
|
|
|
|
SetLocaleInfo() allows changing elements in the user override section of the
|
|
locale database. Unfortunately these changes are not automatically available
|
|
to further Variant formatting; you have to call SendSettingChange() first.
|
|
|
|
=head2 Win32::OLE::Const now correctly treats version numbers as hex
|
|
|
|
The minor and major version numbers of type libraries have been treated as
|
|
decimal. This was wrong. They are now correctly decoded as hex.
|
|
|
|
=head2 more robust global destruction of Win32::OLE objects
|
|
|
|
The final destruction of Win32::OLE objects has always been somewhat fragile.
|
|
The reason for this is that Perl doesn't honour reference counts during global
|
|
destruction but destroys objects in seemingly random order. This can lead
|
|
to leaked database connections or unterminated external objects. The only
|
|
solution was to make all objects lexical and hope that no object would be
|
|
trapped in a closure. Alternatively all objects could be explicitly set to
|
|
C<undef>, which doesn't work very well with exception handling.
|
|
|
|
With version 0.1007 of Win32::OLE this problem should be gone: The module
|
|
keeps a list of active Win32::OLE objects. It uses an END block to destroy
|
|
all objects at program termination I<before> the Perl's global destruction
|
|
starts. Objects still existing at program termination are now destroyed in
|
|
reverse order of creation. The effect is similar to explicitly calling
|
|
Win32::OLE->Uninitialize() just prior to termination.
|
|
|
|
=head1 Version 0.1005 (changes since 0.1003)
|
|
|
|
Win32::OLE 0.1005 has been release with ActivePerl build 509. It is also
|
|
included in the I<Perl Resource Kit for Win32> Update.
|
|
|
|
=head2 optional DESTRUCTOR for GetActiveObject() GetObject() class methods
|
|
|
|
The GetActiveObject() and GetObject() class method now also support an
|
|
optional DESTRUCTOR parameter just like Win32::OLE->new(). The DESTRUCTOR
|
|
is executed when the last reference to this object goes away. It is
|
|
generally considered C<impolite> to stop applications that you did not
|
|
start yourself.
|
|
|
|
=head2 new Variant object method: $object->Copy()
|
|
|
|
See L<Win32::OLE::Variant/Copy([DIM])>.
|
|
|
|
=head2 new Win32::OLE->Option() class method
|
|
|
|
The Option() class method can be used to inspect and modify
|
|
L<Win32::OLE/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);
|
|
|
|
Currently the following options exist: CP, LCID and C<Warn>.
|
|
|
|
=cut
|