Book/com-Phpdoc专题

COM and .Net (Windows)

简介
安装／配置
预定义常量
Errors and error handling
范例
- For Each
- Arrays and Array-style COM properties
com — The com class
- com::__construct — com class constructor
dotnet — The dotnet class
- dotnet::__construct — dotnet class constructor
variant — variant class
- variant::__construct — variant class constructor
COMPersistHelper — The COMPersistHelper class
- COMPersistHelper::__construct — Construct a COMPersistHelper object
- COMPersistHelper::GetCurFileName — Get current filename
- COMPersistHelper::GetMaxStreamSize — Get maximum stream size
- COMPersistHelper::InitNew — Initialize object to default state
- COMPersistHelper::LoadFromFile — Load object from file
- COMPersistHelper::LoadFromStream — Load object from stream
- COMPersistHelper::SaveToFile — Save object to file
- COMPersistHelper::SaveToStream — Save object to stream
com_exception — The com_exception class
COM 函数
- 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

简介

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

类摘要

com

class com extends variant {

/* 方法 */

public __construct ( string $module_name [, arraystringnull $server_name = null [, int $codepage = CP_ACP [, string $typelib = "" ]]] )

}

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.

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.

com examples

示例 #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;
?>

示例 #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;

?>

com::__construct

com class constructor

说明

public com::__construct ( string $module_name [, arraystringnull $server_name = null [, int $codepage = CP_ACP [, string $typelib = "" ]]] )

Constructs a new com object.

参数

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.

key	type	description
Server	string	The name of the server.
Username	string	The username to connect as.
Password	string	The password for Username.
Domain	string	The domain of server.
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, 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.

简介

The dotnet class allows you to instantiate a class from a .Net assembly and call its methods and access its properties, if the class and the methods and properties are » visible to COM.

Neither instantiating static classes nor calling static methods is supported.

Some .Net classes do not implement IDispatch, so while they can be instantiated, calling methods or accessing properties on these classes is not supported.

Note:

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

Note:

.Net framework 4.0 and later are not supported by the dotnet class. If assemblies have been registered with regasm.exe, the classes can be instantiated as com objects, though.

类摘要

dotnet

class dotnet extends variant {

/* 方法 */

public __construct ( string $assembly_name , string $datatype_name [, int $codepage = CP_ACP ] )

}

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 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.

dotnet examples

示例 #1 dotnet example

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

dotnet::__construct

dotnet class constructor

说明

public dotnet::__construct ( string $assembly_name , string $datatype_name [, int $codepage = CP_ACP ] )

Constructs a new dotnet object.

参数

assembly_name
Specifies which assembly should be loaded.

datatype_name
Specifices which class in that assembly to instantiate.

codepage
Codepage to use for unicode string transformations; see the com class for more details on code pages.

简介

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.

类摘要

variant

class variant {

/* 方法 */

public __construct ([ mixed $value = null [, int $type = VT_EMPTY [, int $codepage = CP_ACP ]]] )

}

variant examples

示例 #1 variant example

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

Note:

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.

variant::__construct

variant class constructor

说明

public variant::__construct ([ mixed $value = null [, int $type = VT_EMPTY [, int $codepage = CP_ACP ]]] )

Constructs a new variant object.

参数

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 预定义常量. PHP 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.

简介

COMPersistHelper improves the interoperability of COM and PHP with regard to the php.ini directive open_basedir, and stream 资源(resource)s.

类摘要

COMPersistHelper

final class COMPersistHelper {

/* 方法 */

public __construct ([ variantnull $variant ] )

public stringfalse GetCurFileName ( void )

public int GetMaxStreamSize ( void )

public bool InitNew ( void )

public bool LoadFromFile ( string $filename [, int $flags = 0 ] )

public bool LoadFromStream ( resource $stream )

public bool SaveToFile ( stringnull $filename [, bool $remember = true ] )

public bool SaveToStream ( resource $stream )

}

COMPersistHelper::__construct

Construct a COMPersistHelper object

说明

public COMPersistHelper::__construct ([ variantnull $variant ] )

Constructs a persistence helper object, usually associated with a variant.

参数

variant
A COM object which implements IDispatch. To be able to successfully call any of COMPersistHelper's methods, the object has to implement IPersistFile, IPersistStream and/or IPersistStreamInit. Passing null as variant is only useful if the object is to be loaded from a stream by calling COMPersistHelper::LoadFromStream.

COMPersistHelper::GetCurFileName

Get current filename

说明

public stringfalse COMPersistHelper::GetCurFileName ( void )

Retrieves the current name of the file associated with the object.

参数

此函数没有参数。

返回值

Returns the current name of the file associated with the object.

错误／异常

A com_exception is thrown if the associated object does not implement the COM interface IPersistFile, or when calling the IPersistFile::GetCurFile method failed.

COMPersistHelper::GetMaxStreamSize

Get maximum stream size

说明

public int COMPersistHelper::GetMaxStreamSize ( void )

Retrieves the size of the stream (in bytes) needed to save the object.

参数

此函数没有参数。

返回值

Returns the size of the stream (in bytes) needed to save the object.

错误／异常

A com_exception is thrown if the associated object does neither implement the COM interface IPersistStream nor IPersistStreamInit, or when calling the IPersistStream::GetSizeMax method failed.

COMPersistHelper::InitNew

Initialize object to default state

说明

public bool COMPersistHelper::InitNew ( void )

Initializes an object to a default state.

参数

此函数没有参数。

返回值

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

错误／异常

A com_exception is thrown if the associated object does not implement the COM interface IPersistStreamInit, or when calling its IPersistStreamInit::Init method failed.

COMPersistHelper::LoadFromFile

Load object from file

说明

public bool COMPersistHelper::LoadFromFile ( string $filename [, int $flags = 0 ] )

Opens the specified file and initializes an object from the file contents.

参数

filename
The name of the file from which to load the object.

flags
The access mode to be used when opening the file. Possible values are taken from the » STGM enumeration. The method can treat this value as a suggestion, adding more restrictive permissions if necessary. If flags is 0, the implementation is supposed to open the file using whatever default permissions are used when a user opens the file.

返回值

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

错误／异常

COMPersistHelper::LoadFromStream

Load object from stream

说明

public bool COMPersistHelper::LoadFromStream ( resource $stream )

Initializes an object from the stream where it was saved previously.

参数

stream
The stream 资源(resource) from which to load the object.

返回值

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

错误／异常

A com_exception is thrown if the associated object does not implement the COM interface IPersistStream, or when calling the IPersistStream::Load method failed.

COMPersistHelper::SaveToFile

Save object to file

说明

public bool COMPersistHelper::SaveToFile ( stringnull $filename [, bool $remember = true ] )

Saves a copy of the object to the specified file.

参数

filename
The name of the file to which to save the object.

remember
Indicates whether the filename parameter is to be used as the current working file. If true, filename becomes the current file and the object is supposed to clear its dirty flag after the save. If false, this save operation is a "Save A Copy As ..." operation. In this case, the current file is unchanged and the object is not supposed to clear its dirty flag.

返回值

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

错误／异常

范例

示例 #1 Basic COMPersistHelper::saveToFile Usage

<?php
$word = new COM('Word.Application');
$doc = $word->Documents->Add();
$ph = new COMPersistHelper($doc);
$ph->SaveToFile('C:\\Users\\cmb\\Documents\\my.docx');
$word->Quit();
?>

COMPersistHelper::SaveToStream

Save object to stream

说明

public bool COMPersistHelper::SaveToStream ( resource $stream )

Saves an object to the specified stream.

参数

stream
The stream 资源(resource) to which to save the object.

返回值

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

错误／异常

简介

类摘要

com_exception

class com_exception extends Exception implements Throwable {

/* 继承的属性 */

protected string $message ;

protected int $code ;

protected string $file ;

protected int $line ;

/* 继承的方法 */

final public string Exception::getMessage ( void )

final public Throwable Exception::getPrevious ( void )

final public mixed Exception::getCode ( void )

final public string Exception::getFile ( void )

final public int Exception::getLine ( void )

final public array Exception::getTrace ( void )

final public string Exception::getTraceAsString ( void )

public string Exception::__toString ( void )

final private void Exception::__clone ( void )

}