Win32::OLE::NEWS(3) User Contributed Perl Documentation Win32::OLE::NEWS(3)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.
Version 0.18
VT_CY and VT_DECIMAL return values handled differently
The new "Variant" option enables values of VT_CY or VT_DECIMAL type to
be returned as Win32::OLE::Variant objects instead of being converted
into strings and numbers respectively. This is similar to the change
in Win32::OLE version 0.12 to VT_DATE and VT_ERROR values. The
Win32::OLE::Variant module must be included to make sure that VT_CY and
VT_DECIMAL values behave as before in numeric or string contexts.
Because the new behavior is potentially incompatible, it must be
explicitly enabled:
Win32::OLE->Option(Variant => 1);
Version 0.17
New nullstring() function in Win32::OLE::Variant
The 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.
Version 0.16
Improved Unicode support
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.
You must enable Unicode support by switching Win32::OLE to the UTF8
codepage:
Win32::OLE->Option(CP => Win32::OLE::CP_UTF8());
Version 0.13
New nothing() function 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
New _NewEnum and _Unique options
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.
Version 0.12
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 "On Error Goto Label"
construct:
Win32::OLE->Option(Warn => sub {goto CheckError});
# ... your normal OLE code here ...
CheckError:
# ... your error handling code here ...
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 }
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 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 "Win32::OLE" article from "The Perl Journal #10"
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.
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.
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.
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.
Version 0.11 (changes since 0.1008)
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 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.
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.
Version 0.1008
new LetProperty() object method
In 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);
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
}
Version 0.1007 (changes since 0.1005)
OLE Event support
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 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.
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.
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.
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);
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);
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
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.
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.
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 "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.
Version 0.1005 (changes since 0.1003)
Win32::OLE 0.1005 has been release with ActivePerl build 509. It is
also included in the Perl Resource Kit for Win32 Update.
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 "impolite" to stop applications that
you did not start yourself.
new Variant object method: $object->Copy()
See "Copy([DIM])" in Win32::OLE::Variant.
new Win32::OLE->Option() class method
The Option() class method can be used to inspect and modify "Module
Options" in Win32::OLE. 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".
perl v5.14.2 2005-09-17 Win32::OLE::NEWS(3)
