COM and .Net (Windows)

Table of Contents

Introduction
Installing/Configuring
Predefined Constants
Errors and error handling
Examples
- For Each
- Arrays and Array-style COM properties
COM — The COM class
DOTNET — The DOTNET class
VARIANT — VARIANT class
COM Functions
- com_addref — Increases the components reference counter [deprecated]
- com_create_guid — Generate a globally unique identifier (GUID)
- com_event_sink — Connect events from a COM object to a PHP object
- com_get_active_object — Returns a handle to an already running instance of a COM object
- com_get — Gets the value of a COM Component's property [deprecated]
- com_invoke — Calls a COM component's method [deprecated]
- com_isenum — Indicates if a COM object has an IEnumVariant interface for iteration [deprecated]
- com_load_typelib — Loads a Typelib
- com_load — Creates a new reference to a COM component [deprecated]
- com_message_pump — Process COM messages, sleeping for up to timeoutms milliseconds
- com_print_typeinfo — Print out a PHP class definition for a dispatchable interface
- com_propget — Alias of com_get
- com_propput — Alias of com_set
- com_propset — Alias of com_set
- com_release — Decreases the components reference counter [deprecated]
- com_set — Assigns a value to a COM component's property
- variant_abs — Returns the absolute value of a variant
- variant_add — "Adds" two variant values together and returns the result
- variant_and — Performs a bitwise AND operation between two variants
- variant_cast — Convert a variant into a new variant object of another type
- variant_cat — concatenates two variant values together and returns the result
- variant_cmp — Compares two variants
- variant_date_from_timestamp — Returns a variant date representation of a Unix timestamp
- variant_date_to_timestamp — Converts a variant date/time value to Unix timestamp
- variant_div — Returns the result from dividing two variants
- variant_eqv — Performs a bitwise equivalence on two variants
- variant_fix — Returns the integer portion of a variant
- variant_get_type — Returns the type of a variant object
- variant_idiv — Converts variants to integers and then returns the result from dividing them
- variant_imp — Performs a bitwise implication on two variants
- variant_int — Returns the integer portion of a variant
- variant_mod — Divides two variants and returns only the remainder
- variant_mul — Multiplies the values of the two variants
- variant_neg — Performs logical negation on a variant
- variant_not — Performs bitwise not negation on a variant
- variant_or — Performs a logical disjunction on two variants
- variant_pow — Returns the result of performing the power function with two variants
- variant_round — Rounds a variant to the specified number of decimal places
- variant_set_type — Convert a variant into another type "in-place"
- variant_set — Assigns a new value for a variant object
- variant_sub — Subtracts the value of the right variant from the left variant value
- variant_xor — Performs a logical exclusion on two variants

The COM class

Description

The COM class allows you to instantiate an OLE compatible COM object and call its methods and access its properties.

$obj = new COM("Application.ID")

Methods

COM::COM ( string $module_name [, mixed $server_name [, int $codepage [, string $typelib ]]] )

COM class constructor. The parameters have the following meanings:

module_name

Can be a ProgID, Class ID or Moniker that names the component to load. A ProgID is typically the application or DLL name, followed by a period, followed by the object name. e.g: Word.Application. A Class ID is the UUID that uniquely identifies a given class. A Moniker is a special form of naming, similar in concept to a URL scheme, that identifies a resource and specifies how it should be loaded. As an example, you could load up Word and get an object representing a word document by specifying the full path to the word document as the module name, or you can use LDAP: as a moniker to use the ADSI interface to LDAP.

server_name

The name of the DCOM server on which the component should be loaded and run. If NULL, the object is run using the default for the application. The default is typically to run it on the local machine, although the administrator might have configured the application to launch on a different machine. If you specify a non-NULL value for server, PHP will refuse to load the object unless the configuration option is set to TRUE.

If server_name is an array, it should contain the following elements (case sensitive!). Note that they are all optional (although you need to specify both Username and Password together); if you omit the Server setting, the default server will be used (as mentioned above), and the instantiation of the object will not be affected by the directive.

**DCOM server name**
`server_name` key	type	description
Server	string	The name of the server.
Username	string	The username to connect as.
Password	string	The password for `Username`.
Flags	integer	One or more of the following constants, logically OR'd together: `CLSCTX_INPROC_SERVER`, `CLSCTX_INPROC_HANDLER`, `CLSCTX_LOCAL_SERVER`, `CLSCTX_REMOTE_SERVER`, `CLSCTX_SERVER` and `CLSCTX_ALL`. The default value if not specified here is `CLSCTX_SERVER` if you also omit `Server`, or `CLSCTX_REMOTE_SERVER` if you do specify a server. You should consult the Microsoft documentation for CoCreateInstance for more information on the meaning of these constants; you will typically never have to use them.

codepage

Specifies the codepage that is used to convert strings to unicode-strings and vice versa. The conversion is applied whenever a PHP string is passed as a parameter or returned from a method of this COM object. The code page is sticky in PHP 5, which means that it will propagate to objects and variants returned from the object. Possible values are CP_ACP (use system default ANSI code page - the default if this parameter is omitted), CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP (use codepage/locale set for the current executing thread), CP_UTF7 and CP_UTF8. You may also use the number for a given codepage; consult the Microsoft documentation for more details on codepages and their numeric values.

Overloaded Methods

The returned object is an overloaded object, which means that PHP does not see any fixed methods as it does with regular classes; instead, any property or method accesses are passed through to COM.

Starting with PHP 5, PHP will automatically detect methods that accept parameters by reference, and will automatically convert regular PHP variables to a form that can be passed by reference. This means that you can call the method very naturally; you needn't go to any extra effort in your code.

In PHP 4, to pass parameters by reference you need to create an instance of the VARIANT class to wrap the byref parameters.

Pseudo Methods

In PHP versions prior to 5, a number of not very pleasant hacks meant that the following method names were not passed through to COM and were handled directly by PHP. PHP 5 eliminates these things; read the details below to determine how to fix your scripts. These magic method names are case insensitive.

void COM::AddRef ( void )

Artificially adds a reference count to the COM object.

Warning

You should never need to use this method. It exists as a logical complement to the Release() method below.

void COM::Release ( void )

Artificially removes a reference count from the COM object.

Warning

You should never need to use this method. Its existence in PHP is a bug designed to work around a bug that keeps COM objects running longer than they should.

Pseudo Methods for Iterating

These pseudo methods are only available if com_isenum returns TRUE, in which case, they hide any methods with the same names that might otherwise be provided by the COM object. These methods have all been eliminated in PHP 5, and you should use For Each instead.

variant COM::All ( void )

Returns a variant representing a SafeArray that has 10 elements; each element will be an empty/null variant. This function was supposed to return an array containing all the elements from the iterator, but was never completed. Do not use.

variant COM::Next ( void )

Returns a variant representing the next element available from the iterator, or FALSE when there are no more elements.

variant COM::Prev ( void )

Returns a variant representing the previous element available from the iterator, or FALSE when there are no more elements.

void COM::Reset ( void )

Rewinds the iterator back to the start.

COM examples

Example #1 COM example (1)


<?php
// starting word
$word = new COM("word.application") or die("Unable to instantiate Word");
echo "Loaded Word, version {$word->Version}\n";

//bring it to front
$word->Visible = 1;

//open an empty document
$word->Documents->Add();

//do some weird stuff
$word->Selection->TypeText("This is a test...");
$word->Documents[1]->SaveAs("Useless test.doc");

//closing word
$word->Quit();

//free the object
$word = null;
?>

Example #2 COM example (2)


<?php

$conn = new COM("ADODB.Connection") or die("Cannot start ADO");
$conn->Open("Provider=SQLOLEDB; Data Source=localhost;
Initial Catalog=database; User ID=user; Password=password");

$rs = $conn->Execute("SELECT * FROM sometable");    // Recordset

$num_columns = $rs->Fields->Count();
echo $num_columns . "\n";

for ($i=0; $i < $num_columns; $i++) {
    $fld[$i] = $rs->Fields($i);
}

$rowcount = 0;
while (!$rs->EOF) {
    for ($i=0; $i < $num_columns; $i++) {
        echo $fld[$i]->value . "\t";
    }
    echo "\n";
    $rowcount++;            // increments rowcount
    $rs->MoveNext();
}

$rs->Close();
$conn->Close();

$rs = null;
$conn = null;

?>

The DOTNET class

Description

The DOTNET class allows you to instantiate a class from a .Net assembly and call its methods and access its properties.

$obj = new DOTNET("assembly", "classname")

Methods

DOTNET::DOTNET ( string $assembly_name , string $class_name [, int $codepage ] )

DOTNET class constructor. assembly_name specifies which assembly should be loaded, and class_name specifices which class in that assembly to instantiate. You may optionally specify a codepage to use for unicode string transformations; see the COM class for more details on code pages.

The returned object is an overloaded object, which means that PHP does not see any fixed methods as it does with regular classes; instead, any property or method accesses are passed through to COM and from there to DOTNET. In other words, the .Net object is mapped through the COM interoperability layer provided by the .Net runtime.

Once you have created a DOTNET object, PHP treats it identically to any other COM object; all the same rules apply.

Example #3 DOTNET example


<?php
 $stack = new DOTNET("mscorlib", "System.Collections.Stack");
 $stack->Push(".Net");
 $stack->Push("Hello ");
 echo $stack->Pop() . $stack->Pop();
?>

Note:
You need to install the .Net runtime on your web server to take advantage of this feature.

VARIANT class

Description

The VARIANT is COM's equivalent of the PHP zval; it is a structure that can contain a value with a range of different possible types. The VARIANT class provided by the COM extension allows you to have more control over the way that PHP passes values to and from COM.

$vVar = new VARIANT($var)

Methods

VARIANT::VARIANT ([ mixed $value [, int $type [, int $codepage ]]] )

VARIANT class constructor. Parameters:

value: initial value. if omitted, or set to NULL an VT_EMPTY object is created.
type: specifies the content type of the VARIANT object. Possible values are one of the VT_XXX Predefined Constants. In PHP versions prior to PHP 5, you could force PHP to pass a variant object by reference by OR'ing VT_BYREF with the type. In PHP 5, this hack is not supported; instead, PHP 5 can detect parameters passed by reference automatically; they do not even need to be passed as VARIANT objects. Consult the MSDN library for additional information on the VARIANT type.
codepage: specifies the codepage that is used to convert strings to unicode. See the parameter of the same name in the COM class for more information.

PHP versions prior to PHP 5 define a number of (undocumented) virtual properties for instances of the VARIANT class; these properties have all been removed in PHP 5 in favour of its more natural syntax; these differences are best highlighted by example:

Example #4 Variant example, PHP 4.x style


<?php
$v = new VARIANT(42);
print "The type is " . $v->type . "<br/>";
print "The value is " . $v->value . "<br/>";
?>

Example #5 Variant example, PHP 5 style


<?php
$v = new VARIANT(42);
print "The type is " . variant_get_type($v) . "<br/>";
print "The value is " . $v . "<br/>";
?>

The reason for the change is that, internally, the COM extension sees VARIANT, COM and DOTNET classes as the same thing, and the design philosophy for these classes is that all property and member accesses are passed through to COM with no interference. The new syntax is more natural and less effort, and most of the removed virtual properties didn't make any sense in a PHP context in any case.

Note:
PHP 5 takes a much simpler approach to handling VARIANTs; when returning a value or fetching a variant property, the variant is converted to a PHP value only when there is a direct mapping between the types that would not result in a loss of information. In all other cases, the result is returned as an instance of the VARIANT class. You can force PHP to convert or evaluate the variant as a PHP native type by using a casting operator explicitly, or implicitly casting to a string by printing it. You may use the wide range of variant functions to perform arithmetic operations on variants without forcing a conversion or risking a loss of data.