DESCRIPTION
The COM extension allows developers to use perl to communicate with COM objects that have IDispatch interfaces. The mapimail.ksh script is an example of how this is done (see mapimail).
To use this extension, place
require COM;
in your perl script before using any of this extension's features.
Opening Communication with a COM Object
You can open a COM object by using either its name or its CLSID. For example, MSMapi32.ocx supports an interface named "MSMAPI.MAPISession". Its CLSID is "{20C62CA0-15DA-101B-B9A8-444553540000}". To open communications with this interface, use
$session = new IDispatch "com-id";
if ($session == 0) {
die "Could not open the MAPI Session Control, stopped";
}
where com-id is either the name MSMAPI.MAPISession or the CLSID {20C62CA0-15DA-101B-B9A8-444553540000}.
Once communication with the COM object is open, you can access the properties, methods, and collections associated with this object.
Accessing Properties
You can refer to an object's properties with the following syntax:
$object-handle->{property-name}
where $object-handle is the scalar variable set by new IDispatch when opening communication with the object and property-name is the name of the desired property.
For example, the mapimail.ksh script obtains the value of the SessionID property with:
$session->{SessionID}
Some properties are write-only; attempting to read one of these generates an error message.
Setting the value of a property is similar. mapimail.ksh sets the value of the NewSession property with
$session->{NewSession} = 0;
Some properties are read-only; attempting to set one of these generates an error message.
Accessing Methods
You can call a COM object's methods with the following syntax:
$var=$object-handle->method-name(args)
where $object-handle is the scalar variable set by new IDispatch when opening communication with the object, method-name is the name of the desired method, args is the list of arguments to be passed to the method, and $var is a variable to hold a value returned by a method. Some methods do not take arguments and some do not return values. For example, the mapimail.ksh script calls
$session->SignOff();
Accessing Collections
COM objects can also have a particular type of property known as a collection. A collection is a set of values associated with a single property. This extension uses a reference to a perl array to represent a collection. You can refer to a specific element of a collection with the following syntax:
$object-handle->{collection-name}->[num]
where $object-handle is the scalar variable set by new IDispatch when opening communication with the object, collection-name is the name of the collection and num is a number indicating which element of the collection you wish to access.
For example, if $object indicates an object which has a collection named fields as one of its properties, you can access the fifth element of this collection with
$object->{fields}->[5]
Normally, collections have their own properties such as Count and Items; however, these properties are not directly accessible to perl. Instead, you should use the normal perl syntax for accessing elements and for determining the length of an array.
PORTABILITY
Windows NT 4.0. Windows 2000. Windows XP. Windows Server 2003.
NOTE
Because ActiveX and Active Server Pages objects are similar to COM objects, the techniques described in this man page for accessing an object's properties, methods, and collections are the same as those used by PScript scripting language (see pscript).
MKS Toolkit for Power Users
MKS Toolkit for System Administrators
MKS Toolkit for Developers
MKS Toolkit for Interoperability
MKS Toolkit for Professional Developers
MKS Toolkit for Enterprise Developers
MKS Toolkit for Enterprise Developers 64-Bit Edition
MKS AlertCentre
SEE ALSO
- Commands:
- mapimail, perl
- Miscellaneous:
- pscript