Win32::OLE::NEWS - What's new in Win32::OLE |
Put()
bug fixesGetObject()
and GetActiveObject()
now support optional DESTRUCTOR argumentPut()
method now returns the VARIANT object itselfPut(ARRAYREF)
form allows assignment to a complete SAFEARRAYSendSettingChange()
and SetLocaleInfo()
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.
Passing Unicode strings to methods and properties as well as returning Unicode strings back to Perl works now with both Perl 5.6 and 5.8. Note that the Unicode support in 5.8 is much more complete than in 5.6 or 5.6.1.
Unicode::String
objects can now be passed to methods or assigned to
properties.
nullstring()
function in Win32::OLE::VariantThe nullstring()
function returns a VT_BSTR variant containing a NULL
string pointer. Note that this is not the same as a VT_BSTR variant
containing the empty string ``''.
The nullstring()
return value is equivalent to the Visual Basic
vbNullString
constant.
nothing()
function in Win32::OLE::VariantThe 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
There are two new options available for the Win32::OLE->Option class
method: _NewEnum
provides the elements of a collection object
directly as the value of a _NewEnum
property. The _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.
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 On Error Goto
Label
construct:
Win32::OLE->Option(Warn => sub {goto CheckError}); # ... your normal OLE code here ...
CheckError: # ... your error handling code here ...
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 }
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 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();
The article is Copyright 1998 by The Perl Journal. http://www.tpj.com
It originally appeared in The Perl Journal # 10 and appears here courtesy of Jon Orwant and The Perl Journal. The sample code from the article is in the eg/tpj.pl file.
Put()
bug fixesThe Put()
method didn't work correctly for arrays of type VT_BSTR,
VT_DISPATH or VT_UNKNOWN. This has been fixed.
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.
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.
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 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.
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.
LetProperty()
object methodIn Win32::OLE property assignment using the hash syntax is equivalent
to the Visual Basic Set
syntax (by reference assignment):
$Object->{Property} = $OtherObject;
corresponds to this Visual Basic statement:
Set Object.Property = OtherObject
To get the by value treatment of the Visual Basic Let
statement
Object.Property = OtherObject
you have to use the LetProperty()
object method in Perl:
$Object->LetProperty($Property, $OtherObject);
HRESULT()
functionThe 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 }
This version of Win32::OLE contains 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.
GetObject()
and GetActiveObject()
now support optional DESTRUCTOR argumentIt is now possible to specify a DESTRUCTOR argument to the GetObject()
and
GetActiveObject()
class methods. They work identical to the new()
DESTRUCTOR
argument.
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.
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.
Put()
method now returns the VARIANT object itselfThis 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);
Put(ARRAYREF)
form allows assignment to a complete SAFEARRAYThis 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);
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
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.
The minor and major version numbers of type libraries have been treated as decimal. This was wrong. They are now correctly decoded as hex.
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
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 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.
Win32::OLE 0.1005 has been release with ActivePerl build 509. It is also included in the Perl Resource Kit for Win32 Update.
GetActiveObject()
GetObject()
class methodsThe 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 impolite
to stop applications that you did not
start yourself.
Copy()
See Copy([DIM]) in the Win32::OLE::Variant manpage.
Option()
class methodThe Option()
class method can be used to inspect and modify
Module Options in the Win32::OLE manpage. 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 Warn
.
Win32::OLE::NEWS - What's new in Win32::OLE |