Ref/com-Phpdoc专题

参见

For further information on COM read the » COM specification. You might find some additional useful information in our FAQ for PHP 和 COM. If you're thinking of using MS Office applications on the server side, you should read the information here: » Considerations for Server-Side Automation of Office.

com_create_guid

Generate a globally unique identifier (GUID)

说明

stringfalse com_create_guid ( void )

Generates a Globally Unique Identifier (GUID).

A GUID is generated in the same way as DCE UUID's, except that the Microsoft convention is to enclose a GUID in curly braces.

返回值

Returns the GUID as a string, 或者在失败时返回 false.

参见

uuid_create in the PECL uuid extension

com_event_sink

Connect events from a COM object to a PHP object

说明

bool com_event_sink ( variant $variant , object $sink_object [, arraystringnull $sink_interface = null ] )

Instructs COM to sink events generated by variant into the PHP object sink_object.

Be careful how you use this feature; if you are doing something similar to the example below, then it doesn't really make sense to run it in a web server context.

参数

variant

sink_object
sink_object should be an instance of a class with methods named after those of the desired dispinterface; you may use com_print_typeinfo to help generate a template class for this purpose.

sink_interface
PHP will attempt to use the default dispinterface type specified by the typelibrary associated with variant, but you may override this choice by setting sink_interface to the name of the dispinterface that you want to use.

返回值

成功时返回 true，或者在失败时返回 false。

更新日志

版本	说明
8.0.0	`sink_interface` is nullable now.

范例

示例 #1 COM event sink example

<?php
class IEEventSinker {
    var $terminated = false;

   function ProgressChange($progress, $progressmax) {
      echo "Download progress: $progress / $progressmax\n";
    }

    function DocumentComplete(&$dom, $url) {
      echo "Document $url complete\n";
    }

    function OnQuit() {
      echo "Quit!\n";
      $this->terminated = true;
    }
}
$ie = new COM("InternetExplorer.Application");
$sink = new IEEventSinker();
com_event_sink($ie, $sink, "DWebBrowserEvents2");
$ie->Visible = true;
$ie->Navigate("http://www.example.org");
while(!$sink->terminated) {
  com_message_pump(4000);
}
$ie = null;
?>

注释

Caution

Prior to PHP 8.0.0, calling exit from any of the event handlers is not supported, and may cause PHP to hang. This can be worked around by throwing an exception from the event handler, catching the exception in the main code, and calling exit from there.

参见

com_print_typeinfo
com_message_pump

com_get_active_object

Returns a handle to an already running instance of a COM object

说明

variant com_get_active_object ( string $prog_id [, intnull $codepage = null ] )

com_get_active_object is similar to creating a new instance of a com object, except that it will only return an object to your script if the object is already running. OLE applications use something known as the "Running Object Table" to allow well-known applications to be launched only once; this function exposes the COM library function GetActiveObject() to get a handle on a running instance.

参数

prog_id
prog_id must be either the ProgID or CLSID for the object that you want to access (for example Word.Application).

codepage
Acts in precisely the same way that it does for the com class.

返回值

If the requested object is running, it will be returned to your script just like any other COM object.

错误／异常

There are a variety of reasons why this function might fail, the most common being that the object is not already running. In that situation, the exception error code will be MK_E_UNAVAILABLE; you can use the getCode method of the exception object to check the exception code.

更新日志

版本	说明
8.0.0	`codepage` is nullable now.

注释

Warning

Using com_get_active_object in a web server context is not always a smart idea. Most COM/OLE applications are not designed to handle more than one client concurrently, even (or especially!) Microsoft Office. You should read » Considerations for Server-Side Automation of Office for more information on the general issues involved.

com_load_typelib

装载一个 Typelib

说明

bool com_load_typelib ( string $typelib_name [, bool $case_insensitive = true ] )

Loads a type-library and registers its constants in the engine, as though they were defined using define.

Note that it is much more efficient to use the configuration setting to pre-load and register the constants, although not so flexible.

If you have turned on , then PHP will attempt to automatically register the constants associated with a COM object when you instantiate it. This depends on the interfaces provided by the COM object itself, and may not always be possible.

参数

typelib_name
typelib_name can be one of the following:

The filename of a .tlb file or the executable module that contains the type library.
The type library GUID, followed by its version number, for example {00000200-0000-0010-8000-00AA006D2EA4},2,0.
The type library name, e.g. Microsoft OLE DB ActiveX Data Objects 1.0 Library.

PHP will attempt to resolve the type library in this order, as the process gets more and more expensive as you progress down the list; searching for the type library by name is handled by physically enumerating the registry until we find a match.

case_insensitive
The case_insensitive behaves in the same way as the parameter with the same name in the define function.

返回值

成功时返回 true，或者在失败时返回 false。

com_message_pump

Process COM messages, sleeping for up to timeoutms milliseconds

说明

bool com_message_pump ([ int $timeout_milliseconds = 0 ] )

This function will sleep for up to timeout_milliseconds milliseconds, or until a message arrives in the queue.

The purpose of this function is to route COM calls between apartments and handle various synchronization issues. This allows your script to wait efficiently for events to be triggered, while still handling other events or running other code in the background. You should use it in a loop, as demonstrated by the example in the com_event_sink function, until you are finished using event bound COM objects.

参数

timeout_milliseconds
The timeout, in milliseconds.

If you do not specify a value for timeout_milliseconds, then 0 will be assumed. A 0 value means that no waiting will be performed; if there are messages pending they will be dispatched as before; if there are no messages pending, the function will return false immediately without sleeping.

返回值

If a message or messages arrives before the timeout, they will be dispatched, and the function will return true. If the timeout occurs and no messages were processed, the return value will be false.

com_print_typeinfo

Print out a PHP class definition for a dispatchable interface

说明

bool com_print_typeinfo ( variantstring $variant [, stringnull $dispatch_interface = null [, bool $display_sink = false ]] )

The purpose of this function is to help generate a skeleton class for use as an event sink. You may also use it to generate a dump of any COM object, provided that it supports enough of the introspection interfaces, and that you know the name of the interface you want to display.

参数

variant
variant should be either an instance of a COM object, or be the name of a typelibrary (which will be resolved according to the rules set out in com_load_typelib).

dispatch_interface
The name of an IDispatch descendant interface that you want to display.

display_sink
If set to true, the corresponding sink interface will be displayed instead.

返回值

成功时返回 true，或者在失败时返回 false。

参见

com_event_sink
com_load_typelib

variant_abs

Returns the absolute value of a variant

说明

variant variant_abs ( mixed $value )

Returns the absolute value of a variant.

参数

value
The variant.

返回值

Returns the absolute value of value.

错误／异常

Throws a com_exception on failure.

参见

variant_add

"Adds" two variant values together and returns the result

说明

variant variant_add ( mixed $left , mixed $right )

Adds left to right using the following rules (taken from the MSDN library), which correspond to those of Visual Basic:

If	Then
Both expressions are of the string type	Concatenation
One expression is a string type and the other a character	Addition
One expression is numeric and the other is a string	Addition
Both expressions are numeric	Addition
Either expression is NULL	NULL is returned
Both expressions are empty	Integer subtype is returned

参数

left
The left operand.

right
The right operand.

返回值

Returns the result.

错误／异常

Throws a com_exception on failure.

参见

variant_sub

variant_and

Performs a bitwise AND operation between two variants

说明

variant variant_and ( mixed $left , mixed $right )

Performs a bitwise AND operation. Note that this is slightly different from a regular AND operation.

参数

left
The left operand.

right
The right operand.

返回值

If `left` is	If `right` is	then the result is
`true`	`true`	`true`
`true`	`false`	`false`
`true`	`null`	`null`
`false`	`true`	`false`
`false`	`false`	`false`
`false`	`null`	`false`
`null`	`true`	`null`
`null`	`false`	`false`
`null`	`null`	`null`

错误／异常

Throws a com_exception on failure.

参见

variant_or

variant_cast

Convert a variant into a new variant object of another type

说明

variant variant_cast ( variant $variant , int $type )

This function makes a copy of variant and then performs a variant cast operation to force the copy to have the type given by type.

This function wraps VariantChangeType() in the COM library; consult MSDN for more information.

参数

variant
The variant.

type
type should be one of the VT_XXX constants.

返回值

Returns a variant of given type.

参见

variant_set_type

variant_cat

Concatenates two variant values together and returns the result

说明

variant variant_cat ( mixed $left , mixed $right )

Concatenates left with right and returns the result.

This function is notionally equivalent to $left . $right.

参数

left
The left operand.

right
The right operand.

返回值

Returns the result of the concatenation.

错误／异常

Throws a com_exception on failure.

参见

字符串运算符 for the string concatenation operator

variant_cmp

Compares two variants

说明

int variant_cmp ( mixed $left , mixed $right [, int $locale_id = LOCALE_SYSTEM_DEFAULT [, int $flags = 0 ]] )

Compares left with right.

This function will only compare scalar values, not arrays or variant records.

参数

left
The left operand.

right
The right operand.

locale_id
A valid Locale Identifier to use when comparing strings (this affects string collation).

flags
flags can be one or more of the following values OR'd together, and affects string comparisons:

value	meaning
`NORM_IGNORECASE`	Compare case insensitively
`NORM_IGNORENONSPACE`	Ignore nonspacing characters
`NORM_IGNORESYMBOLS`	Ignore symbols
`NORM_IGNOREWIDTH`	Ignore string width
`NORM_IGNOREKANATYPE`	Ignore Kana type
`NORM_IGNOREKASHIDA`	Ignore Arabic kashida characters

返回值

Returns one of the following:

value	meaning
`VARCMP_LT`	`left` is less than `right`
`VARCMP_EQ`	`left` is equal to `right`
`VARCMP_GT`	`left` is greater than `right`
`VARCMP_NULL`	Either `left`, `right` or both are `null`

variant_date_from_timestamp

Returns a variant date representation of a Unix timestamp

说明

variant variant_date_from_timestamp ( int $timestamp )

Converts timestamp from a unix timestamp value into a variant of type VT_DATE. This allows easier interopability between the unix-ish parts of PHP and COM.

参数

timestamp
A unix timestamp.

返回值

Returns a VT_DATE variant.

参见

variant_date_to_timestamp
mktime
time

variant_date_to_timestamp

Converts a variant date/time value to Unix timestamp

说明

intnull variant_date_to_timestamp ( variant $variant )

Converts variant from a VT_DATE (or similar) value into a Unix timestamp. This allows easier interopability between the Unix-ish parts of PHP and COM.

参数

variant
The variant.

返回值

Returns a unix timestamp, or null on failure.

参见

variant_date_from_timestamp
date
strftime

variant_div

Returns the result from dividing two variants

说明

variant variant_div ( mixed $left , mixed $right )

Divides left by right and returns the result.

参数

left
The left operand.

right
The right operand.

返回值

If	Then
Both expressions are of the string, date, character, boolean type	Double is returned
One expression is a string type and the other a character	Division and a double is returned
One expression is numeric and the other is a string	Division and a double is returned.
Both expressions are numeric	Division and a double is returned
Either expression is NULL	NULL is returned
`right` is empty and `left` is anything but empty	A com_exception with code `DISP_E_DIVBYZERO` is thrown
`left` is empty and `right` is anything but empty.	0 as type double is returned
Both expressions are empty	A com_exception with code `DISP_E_OVERFLOW` is thrown

错误／异常

Throws a com_exception on failure.

参见

variant_idiv

variant_eqv

Performs a bitwise equivalence on two variants

说明

variant variant_eqv ( mixed $left , mixed $right )

Performs a bitwise equivalence on two variants.

参数

left
The left operand.

right
The right operand.

返回值

If each bit in left is equal to the corresponding bit in right then true is returned, otherwise false is returned.

错误／异常

Throws a com_exception on failure.

variant_fix

Returns the integer portion of a variant

说明

variant variant_fix ( mixed $value )

Gets the integer portion of a variant.

参数

value
The variant.

返回值

If value is negative, then the first negative integer greater than or equal to the variant is returned, otherwise returns the integer portion of the value of value.

错误／异常

Throws a com_exception on failure.

注释

Warning

This documentation is based on the MSDN documentation; it appears that this function is either the same as variant_int, or that there is an error in the MSDN documentation.

参见

variant_int
variant_round
floor
ceil
round

variant_get_type

Returns the type of a variant object

说明

int variant_get_type ( variant $variant )

Returns the type of a variant object.

参数

variant
The variant object.

返回值

This function returns an integer value that indicates the type of variant, which can be an instance of com, dotnet or variant classes. The return value can be compared to one of the VT_XXX constants.

The return value for COM and DOTNET objects will usually be VT_DISPATCH; the only reason this function works for those classes is because COM and DOTNET are descendants of VARIANT.

参见

variant_set_type

variant_idiv

Converts variants to integers and then returns the result from dividing them

说明

variant variant_idiv ( mixed $left , mixed $right )

Converts left and right to integer values, and then performs integer division.

参数

left
The left operand.

right
The right operand.

返回值

If	Then
Both expressions are of the string, date, character, boolean type	Division and integer is returned
One expression is a string type and the other a character	Division
One expression is numeric and the other is a string	Division
Both expressions are numeric	Division
Either expression is NULL	NULL is returned
Both expressions are empty	A com_exception with code `DISP_E_DIVBYZERO` is thrown

错误／异常

Throws a com_exception on failure.

参见

variant_div

variant_imp

Performs a bitwise implication on two variants

说明

variant variant_imp ( mixed $left , mixed $right )

Performs a bitwise implication operation.

参数

left
The left operand.

right
The right operand.

返回值

If `left` is	If `right` is	then the result is
`true`	`true`	`true`
`true`	`false`	`false`
`true`	`null`	`true`
`false`	`true`	`true`
`false`	`false`	`true`
`false`	`null`	`true`
`null`	`true`	`true`
`null`	`false`	`null`
`null`	`null`	`null`

错误／异常

Throws a com_exception on failure.

variant_int

Returns the integer portion of a variant

说明

variant variant_int ( mixed $value )

Gets the integer portion of a variant.

参数

value
The variant.

返回值

If value is negative, then the first negative integer greater than or equal to the variant is returned, otherwise returns the integer portion of the value of value.

错误／异常

Throws a com_exception on failure.

参见

variant_fix
variant_round
floor
ceil
round

variant_mod

Divides two variants and returns only the remainder

说明

variant variant_mod ( mixed $left , mixed $right )

Divides left by right and returns the remainder.

参数

left
The left operand.

right
The right operand.

返回值

Returns the remainder of the division.

错误／异常

Throws a com_exception on failure.

参见

variant_div
variant_idiv

variant_mul

Multiplies the values of the two variants

说明

variant variant_mul ( mixed $left , mixed $right )

Multiplies left by right.

参数

left
The left operand.

right
The right operand.

Boolean values are converted to -1 for false and 0 for true.

返回值

If	Then
Both expressions are of the string, date, character, boolean type	Multiplication
One expression is a string type and the other a character	Multiplication
One expression is numeric and the other is a string	Multiplication
Both expressions are numeric	Multiplication
Either expression is NULL	NULL is returned
Both expressions are empty	Empty string is returned

错误／异常

Throws a com_exception on failure.

参见

variant_div
variant_idiv

variant_neg

Performs logical negation on a variant

说明

variant variant_neg ( mixed $value )

Performs logical negation of value.

参数

value
The variant.

返回值

Returns the result of the logical negation.

错误／异常

Throws a com_exception on failure.

variant_not

Performs bitwise not negation on a variant

说明

variant variant_not ( mixed $value )

Performs bitwise not negation on value and returns the result.

参数

value
The variant.

返回值

Returns the bitwise not negation. If value is null, the result will also be null.

错误／异常

Throws a com_exception on failure.

variant_or

Performs a logical disjunction on two variants

说明

variant variant_or ( mixed $left , mixed $right )

Performs a bitwise OR operation. Note that this is slightly different from a regular OR operation.

参数

left
The left operand.

right
The right operand.

返回值

If `left` is	If `right` is	then the result is
`true`	`true`	`true`
`true`	`false`	`true`
`true`	`null`	`true`
`false`	`true`	`true`
`false`	`false`	`false`
`false`	`null`	`null`
`null`	`true`	`true`
`null`	`false`	`null`
`null`	`null`	`null`

错误／异常

Throws a com_exception on failure.

参见

variant_and
variant_xor

variant_pow

Returns the result of performing the power function with two variants

说明

variant variant_pow ( mixed $left , mixed $right )

Returns the result of left to the power of right.

参数

left
The left operand.

right
The right operand.

返回值

Returns the result of left to the power of right.

错误／异常

Throws a com_exception on failure.

参见

variant_round

Rounds a variant to the specified number of decimal places

说明

variantnull variant_round ( mixed $value , int $decimals )

Returns the value of value rounded to decimals decimal places.

参数

value
The variant.

decimals
Number of decimal places.

返回值

Returns the rounded value, or null on failure.

参见

round

variant_set_type

Convert a variant into another type "in-place"

说明

void variant_set_type ( variant $variant , int $type )

This function is similar to variant_cast except that the variant is modified "in-place"; no new variant is created. The parameters for this function have identical meaning to those of variant_cast.

参数

variant
The variant.

type

返回值

没有返回值。

参见

variant_cast
variant_get_type

variant_set

Assigns a new value for a variant object

说明

void variant_set ( variant $variant , mixed $value )

Converts value to a variant and assigns it to the variant object; no new variant object is created, and the old value of variant is freed/released.

参数

variant
The variant.

value

返回值

没有返回值。

variant_sub

Subtracts the value of the right variant from the left variant value

说明

variant variant_sub ( mixed $left , mixed $right )

Subtracts right from left.

参数

left
The left operand.

right
The right operand.

返回值

If	Then
Both expressions are of the string type	Subtraction
One expression is a string type and the other a character	Subtraction
One expression is numeric and the other is a string	Subtraction.
Both expressions are numeric	Subtraction
Either expression is NULL	NULL is returned
Both expressions are empty	Empty string is returned

错误／异常

Throws a com_exception on failure.

参见

variant_add

variant_xor

Performs a logical exclusion on two variants

说明

variant variant_xor ( mixed $left , mixed $right )

Performs a logical exclusion.

参数

left
The left operand.

right
The right operand.

返回值

If `left` is	If `right` is	then the result is
`true`	`true`	`false`
`true`	`false`	`true`
`false`	`true`	`true`
`false`	`false`	`false`
`null`	`null`	`null`

错误／异常

Throws a com_exception on failure.

参见

variant_or
variant_and

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_load_typelib — 装载一个 Typelib
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
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