From 1f1450f2f76b0d095c6024fec1cf8fec7fcec734 Mon Sep 17 00:00:00 2001 From: Wez Furlong Date: Mon, 3 May 2004 14:55:02 +0000 Subject: [PATCH] Document PHP 4 and PHP 5 stuff in the COM extension. # win32 users, you all owe me beer ;) git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@157837 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/com/constants.xml | 63 ++++- reference/com/functions/class.com.xml | 235 ++++++++++++++++-- reference/com/functions/class.dotnet.xml | 92 +++++++ reference/com/functions/class.variant.xml | 105 ++++++-- reference/com/functions/com-addref.xml | 14 +- reference/com/functions/com-create-guid.xml | 50 ++++ reference/com/functions/com-event-sink.xml | 107 ++++++++ reference/com/functions/com-get.xml | 22 +- reference/com/functions/com-invoke.xml | 21 +- reference/com/functions/com-isenum.xml | 19 +- reference/com/functions/com-load-typelib.xml | 54 +++- reference/com/functions/com-load.xml | 42 +++- reference/com/functions/com-message-pump.xml | 61 +++++ .../com/functions/com-print-typeinfo.xml | 66 +++++ reference/com/functions/com-propget.xml | 3 +- reference/com/functions/com-propput.xml | 3 +- reference/com/functions/com-propset.xml | 3 +- reference/com/functions/com-release.xml | 16 +- reference/com/functions/com-set.xml | 21 +- reference/com/functions/variant-abs.xml | 49 ++++ reference/com/functions/variant-add.xml | 92 +++++++ reference/com/functions/variant-and.xml | 74 ++++++ reference/com/functions/variant-cast.xml | 57 +++++ reference/com/functions/variant-cat.xml | 53 ++++ reference/com/functions/variant-cmp.xml | 145 +++++++++++ .../functions/variant-date-from-timestamp.xml | 52 ++++ .../functions/variant-date-to-timestamp.xml | 52 ++++ reference/com/functions/variant-div.xml | 99 ++++++++ reference/com/functions/variant-eqv.xml | 48 ++++ reference/com/functions/variant-fix.xml | 64 +++++ reference/com/functions/variant-get-type.xml | 56 +++++ reference/com/functions/variant-idiv.xml | 91 +++++++ reference/com/functions/variant-imp.xml | 69 +++++ reference/com/functions/variant-int.xml | 56 +++++ reference/com/functions/variant-mod.xml | 52 ++++ reference/com/functions/variant-mul.xml | 95 +++++++ reference/com/functions/variant-neg.xml | 46 ++++ reference/com/functions/variant-not.xml | 47 ++++ reference/com/functions/variant-or.xml | 72 ++++++ reference/com/functions/variant-pow.xml | 51 ++++ reference/com/functions/variant-round.xml | 51 ++++ reference/com/functions/variant-set-type.xml | 52 ++++ reference/com/functions/variant-set.xml | 47 ++++ reference/com/functions/variant-sub.xml | 90 +++++++ reference/com/functions/variant-xor.xml | 69 +++++ reference/com/ini.xml | 124 ++++++++- reference/com/reference.xml | 183 ++++++++++++-- reference/com/use-oo-instead.xml | 6 + reference/com/variant-arith.xml | 16 ++ 49 files changed, 2964 insertions(+), 91 deletions(-) create mode 100644 reference/com/functions/class.dotnet.xml create mode 100644 reference/com/functions/com-create-guid.xml create mode 100644 reference/com/functions/com-event-sink.xml create mode 100644 reference/com/functions/com-message-pump.xml create mode 100644 reference/com/functions/com-print-typeinfo.xml create mode 100644 reference/com/functions/variant-abs.xml create mode 100644 reference/com/functions/variant-add.xml create mode 100644 reference/com/functions/variant-and.xml create mode 100644 reference/com/functions/variant-cast.xml create mode 100644 reference/com/functions/variant-cat.xml create mode 100644 reference/com/functions/variant-cmp.xml create mode 100644 reference/com/functions/variant-date-from-timestamp.xml create mode 100644 reference/com/functions/variant-date-to-timestamp.xml create mode 100644 reference/com/functions/variant-div.xml create mode 100644 reference/com/functions/variant-eqv.xml create mode 100644 reference/com/functions/variant-fix.xml create mode 100644 reference/com/functions/variant-get-type.xml create mode 100644 reference/com/functions/variant-idiv.xml create mode 100644 reference/com/functions/variant-imp.xml create mode 100644 reference/com/functions/variant-int.xml create mode 100644 reference/com/functions/variant-mod.xml create mode 100644 reference/com/functions/variant-mul.xml create mode 100644 reference/com/functions/variant-neg.xml create mode 100644 reference/com/functions/variant-not.xml create mode 100644 reference/com/functions/variant-or.xml create mode 100644 reference/com/functions/variant-pow.xml create mode 100644 reference/com/functions/variant-round.xml create mode 100644 reference/com/functions/variant-set-type.xml create mode 100644 reference/com/functions/variant-set.xml create mode 100644 reference/com/functions/variant-sub.xml create mode 100644 reference/com/functions/variant-xor.xml create mode 100644 reference/com/use-oo-instead.xml create mode 100644 reference/com/variant-arith.xml diff --git a/reference/com/constants.xml b/reference/com/constants.xml index 6a2a8d9b73..6aaf3b2388 100644 --- a/reference/com/constants.xml +++ b/reference/com/constants.xml @@ -1,5 +1,5 @@ - +
&reftitle.constants; &extension.constants; @@ -400,6 +400,67 @@ + + + VARCMP_LT (integer) + + + + VARCMP_EQ (integer) + + + + VARCMP_GT (integer) + + + + VARCMP_NULL (integer) + + + + + NORM_IGNORECASE (integer) + + + + NORM_IGNORENONSPACE (integer) + + + + NORM_IGNORESYMBOLS (integer) + + + + NORM_IGNOREWIDTH (integer) + + + + NORM_IGNOREKANATYPE (integer) + + + + NORM_IGNOREKASHIDA (integer) + + + + + DISP_E_DIVBYZERO (integer) + + + + DISP_E_OVERFLOW (integer) + + + + + + + + + + + +
diff --git a/reference/com/functions/class.com.xml b/reference/com/functions/class.com.xml index 15f955a4da..accda3607c 100644 --- a/reference/com/functions/class.com.xml +++ b/reference/com/functions/class.com.xml @@ -1,5 +1,5 @@ - + @@ -7,57 +7,252 @@ COM class - $obj = new COM("server.object") + $obj = new COM("Application.ID") Description - The COM class provides a framework to integrate (D)COM components into - your PHP scripts. + The COM class allows you to instantiate an OLE compatible COM object and + call its methods and access its properties. Methods - stringCOM::COM + objectCOM::COM stringmodule_name - stringserver_name + mixedserver_name intcodepage + stringtypelib - COM class constructor. Parameters: + COM class constructor. The parameters have the following meanings: module_name - name or class-id of the requested component. + 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 - name of the DCOM server from which the component should be fetched. - If &null;, localhost is assumed. - To allow DCOM com.allow_dcom has to be set to - &true; in &php.ini;. + 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 php-strings to - unicode-strings and vice versa. Possible values are - CP_ACP, CP_MACCP, + 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 + propogate 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, CP_UTF7 - and CP_UTF8. + 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 class to wrap the + byref parameters. + + + + + + Psuedo 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. + + + + voidCOM::AddRef + + + Artificially adds a reference count to the COM object. + You should never need to use this method. It exists a + logical complement to the Release() method below. + + + voidCOM::Release + + + Artificially removes a reference count from the COM object. + + You should never need to use this method. It's existence in PHP is a bug + designed to work around a bug that keeps COM objects running longer than + they should. + + + + + Psuedo 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 instead. + + + + objectCOM::All + + + 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. + + + + objectCOM::Next + + + Returns a variant representing the next element available from + the iterator, or &false; when there are no more elements. + + + + objectCOM::Prev + + + Returns a variant representing the previous element available from + the iterator, or &false; when there are no more elements. + + + + voidCOM::Reset + + + Rewinds the iterator back to the start. + + + + COM examples COM example (1) @@ -65,7 +260,7 @@ Version}\n"; //bring it to front @@ -82,7 +277,6 @@ $word->Documents[1]->SaveAs("Useless test.doc"); $word->Quit(); //free the object -$word->Release(); $word = null; ?> ]]> @@ -122,9 +316,6 @@ while (!$rs->EOF) { $rs->Close(); $conn->Close(); -$rs->Release(); -$conn->Release(); - $rs = null; $conn = null; diff --git a/reference/com/functions/class.dotnet.xml b/reference/com/functions/class.dotnet.xml new file mode 100644 index 0000000000..891ae5c983 --- /dev/null +++ b/reference/com/functions/class.dotnet.xml @@ -0,0 +1,92 @@ + + + + + DOTNET + DOTNET class + + + $obj = new DOTNET("assembly", "classname") + + + Description + + The DOTNET class allows you to instantiate a class from a .Net assembly and + call its methods and access its properties. + + + + Methods + + stringDOTNET::DOTNET + stringassembly name + stringclass_name + intcodepage + + + 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 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. + + + + + DOTNET example + +Push(".Net"); + $stack->Push("Hello "); + echo $stack->Pop() . $stack->Pop(); +?> +]]> + + + + + + + You need to install the .Net runtime on your web server to take advantage + of this feature. + + + + + + diff --git a/reference/com/functions/class.variant.xml b/reference/com/functions/class.variant.xml index c7dc9c4a77..a765c9b0b5 100644 --- a/reference/com/functions/class.variant.xml +++ b/reference/com/functions/class.variant.xml @@ -1,5 +1,5 @@ - + @@ -12,7 +12,10 @@ Description - A simple container to wrap variables into VARIANT structures. + 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. @@ -29,7 +32,7 @@ value - initial value. if omitted an VT_EMPTY object is created. + initial value. if omitted, or set to &null; an VT_EMPTY object is created. @@ -37,31 +40,99 @@ specifies the content type of the VARIANT object. Possible values are - VT_UI1, VT_UI2, VT_UI4, - VT_I1, VT_I2, VT_I4, - VT_R4, VT_R8, VT_INT, VT_UINT, - VT_BOOL, VT_ERROR, VT_CY, - VT_DATE, VT_BSTR, VT_DECIMAL, - VT_UNKNOWN, VT_DISPATCH and VT_VARIANT. These values are - mutual exclusive, but they can be combined with VT_BYREF to specify being a value. If omitted, - the type of value is used. Consult the MSDN library for additional information. + one of the VT_XXX . + + + 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 php-strings to - unicode-strings and vice versa. Possible values are - CP_ACP, CP_MACCP, - CP_OEMCP, CP_SYMBOL, - CP_THREAD_ACP, CP_UTF7 - and CP_UTF8. + specifies the codepage that is used to convert strings to + unicode. See the parameter of the same name in the + 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: + + + + + Variant example, PHP 4.x style + +type . "
"; +print "The value is " . $v->value . "
"; +?> +]]> + + + + + + + Variant example, PHP 5 style + +"; +print "The value is " . $v . "
"; +?> +]]> + + + + + + 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. + + + + + 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. + + + + + See also variant_get_type. + + diff --git a/reference/com/functions/com-addref.xml b/reference/com/functions/com-addref.xml index a6da0973dd..de77ed4f83 100644 --- a/reference/com/functions/com-addref.xml +++ b/reference/com/functions/com-addref.xml @@ -1,11 +1,11 @@ - + com_addref - Increases the components reference counter. + Increases the components reference counter [deprecated] @@ -17,6 +17,16 @@ Increases the components reference counter. + + + + You should never need to use this function. + + + + + This function has gone away in PHP 5. + diff --git a/reference/com/functions/com-create-guid.xml b/reference/com/functions/com-create-guid.xml new file mode 100644 index 0000000000..d48a6331ec --- /dev/null +++ b/reference/com/functions/com-create-guid.xml @@ -0,0 +1,50 @@ + + + + + + com_create_guid + + Generate a globally unique identifier (GUID) + + + + Description + + stringcom_create_guid + + + + + Generates a Globally Unique Identifier (GUID) and returns it as a string. + 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. + + + + See also uuid_create in the PECL uuid extension. + + + + + + diff --git a/reference/com/functions/com-event-sink.xml b/reference/com/functions/com-event-sink.xml new file mode 100644 index 0000000000..51d4725886 --- /dev/null +++ b/reference/com/functions/com-event-sink.xml @@ -0,0 +1,107 @@ + + + + + + com_event_sink + + Connect events from a COM object to a PHP object + + + + Description + + boolcom_event_sink + objectcomobject + objectsinkobject + mixedsinkinterface + + + + Instructs COM to sink events generated by + comobject into the PHP object + sinkobject. PHP will attempt to use the default + dispinterface type specified by the typelibrary associated with + comobject, but you may override this choice by + setting sinkinterface to the name of the + dispinterface that you want to use. + + + + sinkobject 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. + + + + 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. + + + + COM event sink example + +terminated = true; + } +} +$ie = new COM("InternetExplorer.Application"); +// note that you don't need the & for PHP 5! +$sink =& new IEEventSinker(); +com_event_sink($ie, $sink, "DWebBrowserEvents2"); +$ie->Visible = true; +$ie->Navigate("http://www.php.net"); +while(!$sink->terminated) { + com_message_pump(4000); +} +$ie = null; +?> +]]> + + + + + See also com_print_typeinfo, + com_message_pump. + + + + + + + diff --git a/reference/com/functions/com-get.xml b/reference/com/functions/com-get.xml index c6001c7893..eeb379903d 100644 --- a/reference/com/functions/com-get.xml +++ b/reference/com/functions/com-get.xml @@ -1,11 +1,11 @@ - + com_get - Gets the value of a COM Component's property + Gets the value of a COM Component's property [deprecated] @@ -20,6 +20,24 @@ COM component referenced by com_object. Returns &false; on error. + + + Don't use com_get(), use OO syntax instead + +property; +// instead of this: +$var = com_get($obj, 'property'); +?> +]]> + + + + + &reference.com.use-oo-instead; + diff --git a/reference/com/functions/com-invoke.xml b/reference/com/functions/com-invoke.xml index 3dbc57e72e..a23a31a195 100644 --- a/reference/com/functions/com-invoke.xml +++ b/reference/com/functions/com-invoke.xml @@ -1,11 +1,11 @@ - + com_invoke - Calls a COM component's method. + Calls a COM component's method [deprecated] @@ -26,6 +26,23 @@ function_parameters are passed to the method function_name. + + + Don't use com_invoke(), use OO syntax instead + +method($one, $two); +// instead of this: +$val = com_invoke($obj, 'method', $one, $two); +?> +]]> + + + + + &reference.com.use-oo-instead; diff --git a/reference/com/functions/com-isenum.xml b/reference/com/functions/com-isenum.xml index f03d34a102..593b2eed0d 100644 --- a/reference/com/functions/com-isenum.xml +++ b/reference/com/functions/com-isenum.xml @@ -1,20 +1,31 @@ - + com_isenum - Grabs an IEnumVariant + Indicates if a COM object has an IEnumVariant interface for iteration [deprecated] Description - voidcom_isenum + booleancom_isenum objectcom_module - &warn.undocumented.func; + Checks to see if a COM object can be enumerated using the + Next() method hack. Returns &true; if it can, &false; if it cannot. + See class for more details on these + methods. + + + This function does not exist in PHP 5; use the more natural + statement to iterate + over the contents of COM objects. See for + more details. + + diff --git a/reference/com/functions/com-load-typelib.xml b/reference/com/functions/com-load-typelib.xml index 30fa062faf..62a4d5287e 100644 --- a/reference/com/functions/com-load-typelib.xml +++ b/reference/com/functions/com-load-typelib.xml @@ -1,5 +1,5 @@ - + @@ -9,13 +9,61 @@ Description - voidcom_load_typelib + boolcom_load_typelib stringtypelib_name intcase_insensitive - &warn.undocumented.func; + Loads a type-library and registers its constants in the engine, as though + they were defined using define. The + case_insensitive behaves in the same way as the + parameter with the same name in the define function. + + 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. + + + + 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. + + diff --git a/reference/com/functions/com-load.xml b/reference/com/functions/com-load.xml index f03e951d77..20259e33c8 100644 --- a/reference/com/functions/com-load.xml +++ b/reference/com/functions/com-load.xml @@ -1,17 +1,17 @@ - + com_load - Creates a new reference to a COM component + Creates a new reference to a COM component [deprecated] Description - stringcom_load + resourcecom_load stringmodule_name string server_name @@ -21,17 +21,33 @@ - com_load creates a new COM component and - returns a reference to it. Returns &false; on failure. Possible - values for codepage are: - CP_ACP, - CP_MACCP, - CP_OEMCP, - CP_SYMBOL, - CP_THREAD_ACP, - CP_UTF7, and - CP_UTF8. + Equivalent to using the new operator to create an + instance of the class. You should do + that instead of calling this function. + + + Don't use com_load(), use OO syntax instead + + +]]> + + + + + + + + This function does not exist in PHP 5; use the class instead. + + diff --git a/reference/com/functions/com-message-pump.xml b/reference/com/functions/com-message-pump.xml new file mode 100644 index 0000000000..65ab695e33 --- /dev/null +++ b/reference/com/functions/com-message-pump.xml @@ -0,0 +1,61 @@ + + + + + + com_message_pump + + Process COM messages, sleeping for up to timeoutms milliseconds + + + + Description + + boolcom_message_pump + inttimeoutms + + + + This function will sleep for up to timeoutms + milliseconds, or until a message arrives in the queue. 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;. If you do not specify a + value for timeoutms, 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. + + + + 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. + + + + + + diff --git a/reference/com/functions/com-print-typeinfo.xml b/reference/com/functions/com-print-typeinfo.xml new file mode 100644 index 0000000000..04e4ec8007 --- /dev/null +++ b/reference/com/functions/com-print-typeinfo.xml @@ -0,0 +1,66 @@ + + + + + + com_print_typeinfo + + Print out a PHP class definition for a dispatchable interface + + + + Description + + + boolcom_print_typeinfo + objectcomobject + stringdispinterface + boolwantsink + + + + 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. + + + + comobject 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). + dispinterface is the name of an IDispatch + descendant interface that you want to display. If + wantsink is &true;, the corresponding sink + interface will be displayed instead. + + + + See also com_event_sink, + com_load_typelib. + + + + + + diff --git a/reference/com/functions/com-propget.xml b/reference/com/functions/com-propget.xml index 56e0ebe68e..74884362a3 100644 --- a/reference/com/functions/com-propget.xml +++ b/reference/com/functions/com-propget.xml @@ -1,5 +1,5 @@ - + @@ -11,6 +11,7 @@ This function is an alias for com_get. + &reference.com.use-oo-instead; diff --git a/reference/com/functions/com-propput.xml b/reference/com/functions/com-propput.xml index 7540f9b3ca..f6b3250625 100644 --- a/reference/com/functions/com-propput.xml +++ b/reference/com/functions/com-propput.xml @@ -1,5 +1,5 @@ - + @@ -11,6 +11,7 @@ This function is an alias for com_set. + &reference.com.use-oo-instead; diff --git a/reference/com/functions/com-propset.xml b/reference/com/functions/com-propset.xml index f049c0a7ef..e2e740d3ec 100644 --- a/reference/com/functions/com-propset.xml +++ b/reference/com/functions/com-propset.xml @@ -1,5 +1,5 @@ - + @@ -11,6 +11,7 @@ This function is an alias for com_set. + &reference.com.use-oo-instead; diff --git a/reference/com/functions/com-release.xml b/reference/com/functions/com-release.xml index df80bb537e..2892130ab7 100644 --- a/reference/com/functions/com-release.xml +++ b/reference/com/functions/com-release.xml @@ -1,11 +1,11 @@ - + com_release - Decreases the components reference counter. + Decreases the components reference counter [deprecated] @@ -17,6 +17,18 @@ Decreases the components reference counter. + + + + You should never need to use this function. + + + + + This function has gone away in PHP 5. + + + diff --git a/reference/com/functions/com-set.xml b/reference/com/functions/com-set.xml index 7eaac99528..94941aa1d5 100644 --- a/reference/com/functions/com-set.xml +++ b/reference/com/functions/com-set.xml @@ -1,5 +1,5 @@ - + @@ -21,6 +21,25 @@ component referenced by com_object. Returns the newly set value if succeeded, &false; on error. + + + + Don't use com_set(), use OO syntax instead + +property = $value; +// instead of this: +com_set($obj, 'property', $value); +?> +]]> + + + + + + &reference.com.use-oo-instead; diff --git a/reference/com/functions/variant-abs.xml b/reference/com/functions/variant-abs.xml new file mode 100644 index 0000000000..9ed0369c7a --- /dev/null +++ b/reference/com/functions/variant-abs.xml @@ -0,0 +1,49 @@ + + + + + variant_abs + + Returns the absolute value of a variant + + + + Description + + mixedvariant_abs + mixedval + + + + Returns the absolute value of val. + + + + See also abs. + + + &reference.com.variant-arith; + + + + + diff --git a/reference/com/functions/variant-add.xml b/reference/com/functions/variant-add.xml new file mode 100644 index 0000000000..97ebe9642d --- /dev/null +++ b/reference/com/functions/variant-add.xml @@ -0,0 +1,92 @@ + + + + + + variant_add + + "Adds" two variant values together and returns the result + + + + Description + + mixedvariant_add + mixedleft + mixedright + + + + Adds left to right using + the following rules (taken from the MSDN library), which correspond to + those of Visual Basic: + + + Variant Addition Rules + + + + 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 + + + +
+ + + + See also variant_sub. + + + &reference.com.variant-arith; + + + + + diff --git a/reference/com/functions/variant-and.xml b/reference/com/functions/variant-and.xml new file mode 100644 index 0000000000..a1c5953f61 --- /dev/null +++ b/reference/com/functions/variant-and.xml @@ -0,0 +1,74 @@ + + + + + + variant_and + + performs a bitwise AND operation between two variants and returns the result + + + + Description + + mixedvariant_and + mixedleft + mixedright + + + + Performs a bitwise AND operation, according to the following truth table; + note that this is slightly different from a regular AND operation. + + Variant AND Rules + + + + 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; + + +
+ + + See also variant_or. + + + &reference.com.variant-arith; + + + + + diff --git a/reference/com/functions/variant-cast.xml b/reference/com/functions/variant-cast.xml new file mode 100644 index 0000000000..944a3dee7e --- /dev/null +++ b/reference/com/functions/variant-cast.xml @@ -0,0 +1,57 @@ + + + + + + variant_cast + + Convert a variant into a new variant object of another type + + + + Description + + objectvariant_cast + objectvariant + inttype + + + + 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. type should + be one of the VT_XXX constants. + + + + This function wraps VariantChangeType() in the COM library; consult MSDN + for more information. + + + + See also variant_set_type. + + + + + + diff --git a/reference/com/functions/variant-cat.xml b/reference/com/functions/variant-cat.xml new file mode 100644 index 0000000000..2929eed633 --- /dev/null +++ b/reference/com/functions/variant-cat.xml @@ -0,0 +1,53 @@ + + + + + + variant_cat + + concatenates two variant values together and returns the result + + + + Description + + mixedvariant_cat + mixedleft + mixedright + + + + Concatenates left with + right and returns the result. + + + + See also for the string + concatenation operator; this function is notionally equivalent to + $left . $right. + + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-cmp.xml b/reference/com/functions/variant-cmp.xml new file mode 100644 index 0000000000..d243b5f02e --- /dev/null +++ b/reference/com/functions/variant-cmp.xml @@ -0,0 +1,145 @@ + + + + + + variant_cmp + + Compares two variants + + + + Description + + intvariant_cmp + mixedleft + mixedright + intlcid + intflags + + + + Compares left with right + and returns one of the following values: + + + Variant Comparision Results + + + + 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; + + + + + +
+ + + + This function will only compare scalar values, not arrays or variant records. + + + + lcid is a valid Locale Identifier to use when + comparing strings (this affects string collation). + flags can be one or more of the following values + OR'd together, and affects string comparisons: + + + Variant Comparision Flags + + + + 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 + + + +
+ + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-date-from-timestamp.xml b/reference/com/functions/variant-date-from-timestamp.xml new file mode 100644 index 0000000000..3079e3fc6f --- /dev/null +++ b/reference/com/functions/variant-date-from-timestamp.xml @@ -0,0 +1,52 @@ + + + + + + variant_date_from_timestamp + + Returns a variant date representation of a unix timestamp + + + + Description + + objectvariant_date_from_timestamp + inttimestamp + + + + 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. + + + + See also variant_date_to_timestamp for the inverse + of this operation, + mktime, time. + + + + + + diff --git a/reference/com/functions/variant-date-to-timestamp.xml b/reference/com/functions/variant-date-to-timestamp.xml new file mode 100644 index 0000000000..24b9ff5b9b --- /dev/null +++ b/reference/com/functions/variant-date-to-timestamp.xml @@ -0,0 +1,52 @@ + + + + + + variant_date_to_timestamp + + Converts a variant date/time value to unix timestamp + + + + Description + + intvariant_date_to_timestamp + objectvariant + + + + 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. + + + + See also variant_date_from_timestamp for the inverse + of this operation, + date, strftime. + + + + + + diff --git a/reference/com/functions/variant-div.xml b/reference/com/functions/variant-div.xml new file mode 100644 index 0000000000..85a691d20e --- /dev/null +++ b/reference/com/functions/variant-div.xml @@ -0,0 +1,99 @@ + + + + + + variant_div + + Returns the result from dividing two variants + + + + Description + + mixedvariant_div + mixedleft + mixedright + + + + Divides left by right and + returns the result, subject to the following rules: + + + Variant Division Rules + + + + 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 + + + +
+ + + &reference.com.variant-arith; + + + + + diff --git a/reference/com/functions/variant-eqv.xml b/reference/com/functions/variant-eqv.xml new file mode 100644 index 0000000000..e474afdeb6 --- /dev/null +++ b/reference/com/functions/variant-eqv.xml @@ -0,0 +1,48 @@ + + + + + + variant_eqv + + Performs a bitwise equivalence on two variants + + + + Description + + mixedvariant_eqv + mixedleft + mixedright + + + + If each bit in left is equal to the corresponding + bit in right then &true; is returned, otherwise + &false; is returned. + + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-fix.xml b/reference/com/functions/variant-fix.xml new file mode 100644 index 0000000000..163a1cf341 --- /dev/null +++ b/reference/com/functions/variant-fix.xml @@ -0,0 +1,64 @@ + + + + + + variant_fix + + Returns the integer portion ? of a variant + + + + Description + + mixedvariant_fix + mixedvariant + + + + If variant 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 + variant. + + + + See also variant_int, + variant_round, floor, + ceil, + round. + + + + + 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. + + + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-get-type.xml b/reference/com/functions/variant-get-type.xml new file mode 100644 index 0000000000..b47cab541b --- /dev/null +++ b/reference/com/functions/variant-get-type.xml @@ -0,0 +1,56 @@ + + + + + variant_get_type + Returns the type of a variant object + + + Description + + intvariant_get_type + objectvariant + + + This function returns an integer value that indicates the type of + variant, which can be an instance of + , + or + 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. + + + In PHP versions prior to 5, you could obtain this information from + instances of the VARIANT class ONLY, by reading a fake + type property. See the class for more information on + this. + + + + + diff --git a/reference/com/functions/variant-idiv.xml b/reference/com/functions/variant-idiv.xml new file mode 100644 index 0000000000..587e661340 --- /dev/null +++ b/reference/com/functions/variant-idiv.xml @@ -0,0 +1,91 @@ + + + + + + variant_idiv + + Converts variants to integers and then returns the result from dividing them + + + + Description + + mixedvariant_idiv + mixedleft + mixedright + + + + Converts left and right to + integer values, and then performs integer division according the + following rules: + + Variant Integer Division Rules + + + + 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 + + + +
+ + + + See also variant_div. + + &reference.com.variant-arith; + + + + + diff --git a/reference/com/functions/variant-imp.xml b/reference/com/functions/variant-imp.xml new file mode 100644 index 0000000000..6b7852312c --- /dev/null +++ b/reference/com/functions/variant-imp.xml @@ -0,0 +1,69 @@ + + + + + + variant_imp + + Performs a bitwise implication on two variants + + + + Description + + mixedvariant_imp + mixedleft + mixedright + + + + Performs a bitwise implication operation, according to the following truth table: + + Variant Implication Table + + + + If left is + If right is + then the result is + + + + &true;&true;&true; + &true;&false;&true; + &true;&null;&true; + &false;&true;&true; + &false;&false;&true; + &false;&null;&true; + &null;&true;&true; + &null;&false;&null; + &null;&null;&null; + + +
+ + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-int.xml b/reference/com/functions/variant-int.xml new file mode 100644 index 0000000000..d053f4ba9f --- /dev/null +++ b/reference/com/functions/variant-int.xml @@ -0,0 +1,56 @@ + + + + + + variant_int + + Returns the integer portion of a variant + + + + Description + + mixedvariant_int + mixedvariant + + + + If variant 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 + variant. + + + + See also variant_fix, + variant_round, floor, + ceil, + round. + + + &reference.com.variant-arith; + + + + + diff --git a/reference/com/functions/variant-mod.xml b/reference/com/functions/variant-mod.xml new file mode 100644 index 0000000000..b92f05f9a9 --- /dev/null +++ b/reference/com/functions/variant-mod.xml @@ -0,0 +1,52 @@ + + + + + + variant_mod + + Divides two variants and returns only the remainder + + + + Description + + mixedvariant_mod + mixedleft + mixedright + + + + Divides left by right and + returns the remainder. + + + + See also variant_div, + variant_idiv. + + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-mul.xml b/reference/com/functions/variant-mul.xml new file mode 100644 index 0000000000..b7a979b541 --- /dev/null +++ b/reference/com/functions/variant-mul.xml @@ -0,0 +1,95 @@ + + + + + + variant_mul + + multiplies the values of the two variants and returns the result + + + + Description + + mixedvariant_mul + mixedleft + mixedright + + + + Multiplies left by right and + returns the result, subject to the following rules: + + + Variant Multiplication Rules + + + + 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 + + + +
+ + + + Boolean values are converted to -1 for &false; and 0 for &true;. + + + + See also variant_div, + variant_idiv. + + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-neg.xml b/reference/com/functions/variant-neg.xml new file mode 100644 index 0000000000..cfb86b8c70 --- /dev/null +++ b/reference/com/functions/variant-neg.xml @@ -0,0 +1,46 @@ + + + + + + variant_neg + + Performs logical negation on a variant + + + + Description + + mixedvariant_neg + mixedvariant + + + + Performs logical negation of variant and returns + the result. + + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-not.xml b/reference/com/functions/variant-not.xml new file mode 100644 index 0000000000..58d26a0b20 --- /dev/null +++ b/reference/com/functions/variant-not.xml @@ -0,0 +1,47 @@ + + + + + + variant_not + + Performs bitwise not negation on a variant + + + + Description + + mixedvariant_not + mixedvariant + + + + Performs bitwise not negation on variant and + returns the result. If variant is &null;, the + result will also be &null;. + + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-or.xml b/reference/com/functions/variant-or.xml new file mode 100644 index 0000000000..0155b1df72 --- /dev/null +++ b/reference/com/functions/variant-or.xml @@ -0,0 +1,72 @@ + + + + + + variant_or + + Performs a logical disjunction on two variants + + + + Description + + mixedvariant_or + mixedleft + mixedright + + + Performs a bitwise OR operation, according to the following truth table; + note that this is slightly different from a regular OR operation. + + Variant OR Rules + + + + 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; + + +
+ + + See also variant_and, + variant_xor. + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-pow.xml b/reference/com/functions/variant-pow.xml new file mode 100644 index 0000000000..49e6cafca8 --- /dev/null +++ b/reference/com/functions/variant-pow.xml @@ -0,0 +1,51 @@ + + + + + + variant_pow + + Returns the result of performing the power function with two variants + + + + Description + + mixedvariant_pow + mixedleft + mixedright + + + + Returns the result of left to the power of + right. + + + + See also pow. + + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-round.xml b/reference/com/functions/variant-round.xml new file mode 100644 index 0000000000..0bfa080c00 --- /dev/null +++ b/reference/com/functions/variant-round.xml @@ -0,0 +1,51 @@ + + + + + + variant_round + + Rounds a variant to the specified number of decimal places + + + + Description + + mixedvariant_round + mixedvariant + intdecimals + + + + Returns the value of variant rounded to + decimals decimal places. + + + + See also round. + + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-set-type.xml b/reference/com/functions/variant-set-type.xml new file mode 100644 index 0000000000..70b14a5d0b --- /dev/null +++ b/reference/com/functions/variant-set-type.xml @@ -0,0 +1,52 @@ + + + + + + variant_set_type + + Convert a variant into another type. Variant is modified "in-place" + + + + Description + + voidvariant_set_type + objectvariant + inttype + + + + 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. + + + + See also variant_cast. + + + + + + diff --git a/reference/com/functions/variant-set.xml b/reference/com/functions/variant-set.xml new file mode 100644 index 0000000000..de1f29038b --- /dev/null +++ b/reference/com/functions/variant-set.xml @@ -0,0 +1,47 @@ + + + + + + variant_set + + Assigns a new value for a variant object + + + + Description + + voidvariant_set + objectvariant + mixedvalue + + + + 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. + + + + + + diff --git a/reference/com/functions/variant-sub.xml b/reference/com/functions/variant-sub.xml new file mode 100644 index 0000000000..4b6c70575c --- /dev/null +++ b/reference/com/functions/variant-sub.xml @@ -0,0 +1,90 @@ + + + + + + variant_sub + + subtracts the value of the right variant from the left variant value and returns the result + + + + Description + + mixedvariant_sub + mixedleft + mixedright + + + + Subtracts right from left using + the following rules: + + + Variant Subtraction Rules + + + + 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 + + + +
+ + + + See also variant_add. + + + &reference.com.variant-arith; + + + + diff --git a/reference/com/functions/variant-xor.xml b/reference/com/functions/variant-xor.xml new file mode 100644 index 0000000000..07982eba50 --- /dev/null +++ b/reference/com/functions/variant-xor.xml @@ -0,0 +1,69 @@ + + + + + + variant_xor + + Performs a logical exclusion on two variants + + + + Description + + mixedvariant_xor + mixedleft + mixedright + + + + Performs a logical exclusion, according to the following truth table: + + Variant XOR Rules + + + + 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; + + +
+ + + See also variant_and, + variant_or. + + &reference.com.variant-arith; + + + + + diff --git a/reference/com/ini.xml b/reference/com/ini.xml index ab55eddf0b..640d352480 100644 --- a/reference/com/ini.xml +++ b/reference/com/ini.xml @@ -1,5 +1,5 @@ - +
&reftitle.runtime; &extension.runtime; @@ -23,17 +23,22 @@ com.autoregister_typelib "0" - PHP_INI_SYSTEM + PHP_INI_ALL com.autoregister_verbose "0" - PHP_INI_SYSTEM + PHP_INI_ALL com.autoregister_casesensitive "1" - PHP_INI_SYSTEM + PHP_INI_ALL + + + com.code_page + "" + PHP_INI_ALL com.typelib_file @@ -46,6 +51,117 @@ For further details and definition of the PHP_INI_* constants see ini_set. + + &ini.descriptions.title; + + + + + + com.allow_dcom + + + + When this is turned on, PHP will be allowed to operate as a D-COM + (Distributed COM) client and will allow the PHP script to instantiate + COM objects on a remote server. + + + + + + + com.autoregister_typelib + + + + When this is turned on, PHP will attempt to register constants from + the typelibrary of objects that it instantiates, if those objects + implement the interfaces required to obtain that information. + The case sensitivity of the constants it registers is controlled by the + configuration directive. + + + + + + + com.autoregister_verbose + + + + When this is turned on, any problems with loading a typelibrary during + object instantiation will be reported using the PHP error mechanism. + The default is off, which does not emit any indication if there was + an error finding or loading the type library. + + + + + + + com.autoregister_casesensitive + + + + When this is turned on (the default), constants found in auto-loaded + type libraries will be registered case sensitively. See + com_load_typelib for more details. + + + + + + + com.code_page + + + + It controls the default character set code-page to use when passing + strings to and from COM objects. If set to an empty string, PHP will + assume that you want CP_ACP, which is the default + system ANSI code page. + + + If the text in your scripts is encoded using a different + encoding/character set by default, setting this directive will save you + from having to pass the code page as a parameter to the class constructor. Please note that by + using this directive (as with any PHP configuration directive), your PHP + script becomes less portable; you should use the COM constructor parameter + whenever possible. + + + + This configuration directive was introduced with PHP 5. + + + + + + + + com.typelib_file + + + + When set, this should hold the path to a file that contains a list + of typelibraries that should be loaded on startup. Each line of + the file will be treated as the type library name and loaded as + though you had called com_load_typelib. + The constants will be registered persistently, so that the library + only needs to be loaded once. If a type library name ends with the + string #cis or #case_insensitive, + then the constants from that library will be registered case + insensitively. + + + + + + +
+ - COM support functions for Windows + COM and .Net (Windows) COM
&reftitle.intro; - COM is a technology which allows the reuse of code written in any - language (by any language) using a standard calling convention and hiding - behind APIs the implementation details such as what machine the Component is - stored on and the executable which houses it. It can be thought of as a super - Remote Procedure Call (RPC) mechanism with some basic object roots. It - separates implementation from interface. - + COM is an acronym for Component Object Model; it is an object orientated + layer (and associated services) on top of DCE RPC (an open standard) and + defines a common calling convention that enables code written in any + language to call and interoperate with code written in any other language + (provided those languages are COM aware). Not only can the code be + written in any language, but it need not even be part of the same + executable; the code can be loadaed from a DLL, be found in another + process running on the same machine, or, with DCOM (Distributed COM), be + found in another process on a remote machine, all without your code even + needing to know where a component resides. + - COM encourages versioning, separation of implementation from - interface and hiding the implementation details such as executable location and - the language it was written in. - + There is a subset of COM known as OLE Automation which comprises a set of + COM interfaces that allow loose binding to COM objects, so that they can + be introspected and called at run-time without compile-time knowledge of + how the object works. The PHP COM extension utilitizes the OLE + Automation interfaces to allow you to create and call compatible objects + from your scripts. Technically speaking, this should really be called + the "OLE Automation Extension for PHP", since not all COM objects are OLE + compatible. + + + Now, why would or should you use COM? COM is one of the main ways to glue + applications and components together on the Windows platform; using COM + you can launch Microsoft Word, fill in a document template and save the + result as a Word document and send it to a visitor of your web site. You + can also use COM to perform administrative tasks for your network and to + configure your IIS; these are just the most common uses; you can do much + more with COM. + + + Starting with PHP 5, this extension (and this documentation) was + rewritten from scratch and much of the old confusing and bogus cruft has + be removed. Additionally, we support the instantiation and creation of + .Net assemblies using the COM interoperability layer provided by + Microsoft. + + + Please read this article + for an overview of the changes in this extension in PHP 5. +
&reftitle.required; - COM functions are only available on the Windows version of PHP. + COM functions are only available for the Windows version of PHP. + + + .Net support requires PHP 5 and the .Net runtime.
@@ -32,6 +64,124 @@ &reftitle.install; &no.install; &windows.builtin; + + You are responsible for installing support for the various COM objects + that you intend to use (such as MS Word); we don't and can't bundle all + of those with PHP. + + + +
+ For Each + + + Starting with PHP 5, you may use PHP's own statement to iterate + over the contents of a standard COM/OLE IEnumVariant. In laymans terms, + this means that you can use foreach in places where you would have used + For Each in VB/ASP code. + + + + + For Each in ASP + +" +Next +%> +]]> + + + + + + + while() ... Next() in PHP 4 + +Next()) { + echo $obj->Name . "
"; +} +?> +]]> + + + + + + + foreach in PHP 5 + +Name . "
"; +} +?> +]]> + + + +
+ +
+ Arrays and Array-style COM properties + + + Many COM objects expose their properties as arrays, or using array-style + access. In PHP 4, you may use PHP array syntax to read/write such a + property, but only a single dimension is allowed. If you want to read a + multi-dimensional property, you could instead make the property access + into a function call, with each parameter representing each dimension of + the array access, but there is no way to write to such a property. + + + + PHP 5 introduces the following new features to make your life easier: + + + + + Access multi-dimensional arrays, or COM properties that require + multiple parameters using PHP array syntax. You can also write or set + properties using this technique. + + + + + + Iterate SafeArrays ("true" arrays) using the control structure. This works + because SafeArrays include information about their size. If an + array-style property implements IEnumVariant then you can also use + foreach for that property too; take a look at for more information on this topic. + + + + + +
+ +
+ Exceptions (PHP 5) + + + This extension will throw instances of the class com_exception + whenever there is a potentially fatal error reported by COM. All + COM exceptions have a well-defined code property that + corresponds to the HRESULT return value from the various COM operations. + You may use this code to make programmatic decisions on how to handle the + exception. + +
&reference.com.ini; @@ -43,7 +193,9 @@ For further information on COM read the COM specification or perhaps take a look at Don Box's - Yet Another COM Library (YACL) + Yet Another COM Library (YACL). + You might find some additional useful information in our FAQ for @@ -59,6 +211,7 @@ sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 + sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil diff --git a/reference/com/use-oo-instead.xml b/reference/com/use-oo-instead.xml new file mode 100644 index 0000000000..ecfe9dd536 --- /dev/null +++ b/reference/com/use-oo-instead.xml @@ -0,0 +1,6 @@ + + + This function does not exist in PHP 5; instead, you should use the regular + and more natural OO syntax to access properties or call methods. + + diff --git a/reference/com/variant-arith.xml b/reference/com/variant-arith.xml new file mode 100644 index 0000000000..2ab015f026 --- /dev/null +++ b/reference/com/variant-arith.xml @@ -0,0 +1,16 @@ + + + As with all the variant arithmetic functions, the parameters for this function + can be either a PHP native type (integer, string, floating point, boolean or + &null;), or an instance of a COM, VARIANT or DOTNET class. PHP native types + will be converted to variants using the same rules as found in the constructor + for the class. COM and DOTNET objects + will have the value of their default property taken and used as the variant value. + + + The variant arithmetic functions are wrappers around the similarly named + functions in the COM library; for more information on these functions, consult + the MSDN library. The PHP functions are named slightly differently; for example + variant_add() in PHP corresponds to VarAdd() in the MSDN documentation. + +