reference/com/com.xml
14767af0f05dffa6fdb9b49e1a1f4e9ca7022a60
...
...
@@ -1,268 +1,70 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
3
<!-- splitted from ./en/functions/com.xml, last change in rev 1.12 -->
4
-
<phpdoc:classref xmlns:phpdoc="http://php.net/ns/phpdoc" xml:id="class.com" xmlns="http://docbook.org/ns/docbook">
5
-
<titleabbrev>COM</titleabbrev>
6
-
<title>The COM class</title>
4
+
<phpdoc:classref xml:id="class.com" xmlns:phpdoc="http://php.net/ns/phpdoc" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
5
+
<titleabbrev>com</titleabbrev>
6
+
<title>The com class</title>
7
7
<partintro>
8
8

9
-
<section xml:id="class.com.class">
10
-
<title>Description</title>
11
-
<simpara>
12
-
The COM class allows you to instantiate an OLE compatible COM object and
13
-
call its methods and access its properties.
14
-
</simpara>
15
-
<simpara>
16
-
<literal>$obj = new COM("Application.ID")</literal>
17
-
</simpara>
18
-
</section>
19
-
<section xml:id="com.com">
20
-
<title>Methods</title>
21
-
<methodsynopsis>
22
-
<methodname>COM::__construct</methodname>
23
-
<methodparam><type>string</type><parameter>module_name</parameter></methodparam>
24
-
<methodparam choice="opt"><type>mixed</type><parameter>server_name</parameter></methodparam>
25
-
<methodparam choice="opt"><type>int</type><parameter>codepage</parameter></methodparam>
26
-
<methodparam choice="opt"><type>string</type><parameter>typelib</parameter></methodparam>
27
-
</methodsynopsis>
28
-
<para>
29
-
COM class constructor. The parameters have the following meanings:
30
-
<variablelist>
31
-
<varlistentry>
32
-
<term>module_name</term>
33
-
<listitem>
34
-
<simpara>
35
-
Can be a ProgID, Class ID or Moniker that names the component to load.
36
-
</simpara>
37
-
<simpara>
38
-
A ProgID is typically the application or DLL name, followed by a period,
39
-
followed by the object name. e.g: <literal>Word.Application</literal>.
40
-
</simpara>
41
-
<simpara>
42
-
A Class ID is the UUID that uniquely identifies a given class.
43
-
</simpara>
44
-
<simpara>
45
-
A Moniker is a special form of naming, similar in concept to a URL
46
-
scheme, that identifies a resource and specifies how it should be
47
-
loaded. As an example, you could load up Word and get an object
48
-
representing a word document by specifying the full path to the word
49
-
document as the module name, or you can use <literal>LDAP:</literal> as
50
-
a moniker to use the ADSI interface to LDAP.
51
-
</simpara>
52
-
</listitem>
53
-
</varlistentry>
54
-
<varlistentry>
55
-
<term>server_name</term>
56
-
<listitem>
57
-
<simpara>
58
-
The name of the DCOM server on which the component should be loaded and
59
-
run. If &null;, the object is run using the default for the
60
-
application. The default is typically to run it on the local machine,
61
-
although the administrator might have configured the application to
62
-
launch on a different machine.
63
-
</simpara>
64
-
<simpara>
65
-
If you specify a non-&null; value for server, PHP will refuse to load
66
-
the object unless the <xref
67
-
linkend="ini.com.allow-dcom"/> configuration option
68
-
is set to &true;.
69
-
</simpara>
70
-
<para>
71
-
If <parameter>server_name</parameter> is an array, it should contain the
72
-
following elements (case sensitive!). Note that they are all optional
73
-
(although you need to specify both Username and Password together); if
74
-
you omit the Server setting, the default server will be used (as
75
-
mentioned above), and the instantiation of the object will not be
76
-
affected by the <xref linkend="ini.com.allow-dcom"/>
77
-
directive.
78
-
<table>
79
-
<title>DCOM server name</title>
80
-
<tgroup cols="3">
81
-
<thead>
82
-
<row>
83
-
<entry><parameter>server_name</parameter> key</entry>
84
-
<entry>type</entry>
85
-
<entry>description</entry>
86
-
</row>
87
-
</thead>
88
-
<tbody>
89
-
<row>
90
-
<entry>Server</entry>
91
-
<entry>string</entry>
92
-
<entry>The name of the server.</entry>
93
-
</row>
94
-
<row>
95
-
<entry>Username</entry>
96
-
<entry>string</entry>
97
-
<entry>The username to connect as.</entry>
98
-
</row>
99
-
<row>
100
-
<entry>Password</entry>
101
-
<entry>string</entry>
102
-
<entry>The password for <parameter>Username</parameter>.</entry>
103
-
</row>
104
-
<row>
105
-
<entry>Flags</entry>
106
-
<entry>integer</entry>
107
-
<entry>One or more of the following constants, logically OR'd together:
108
-
<constant>CLSCTX_INPROC_SERVER</constant>,
109
-
<constant>CLSCTX_INPROC_HANDLER</constant>,
110
-
<constant>CLSCTX_LOCAL_SERVER</constant>,
111
-
<constant>CLSCTX_REMOTE_SERVER</constant>,
112
-
<constant>CLSCTX_SERVER</constant> and
113
-
<constant>CLSCTX_ALL</constant>. The default value if not
114
-
specified here is <constant>CLSCTX_SERVER</constant> if you also
115
-
omit <parameter>Server</parameter>, or
116
-
<constant>CLSCTX_REMOTE_SERVER</constant> if you do specify a
117
-
server. You should consult the Microsoft documentation for
118
-
CoCreateInstance for more information on the meaning of these
119
-
constants; you will typically never have to use them.
120
-
</entry>
121
-
</row>
122
-
</tbody>
123
-
</tgroup>
124
-
</table>
125
-
</para>
126
-
</listitem>
127
-
</varlistentry>
128
-
<varlistentry>
129
-
<term>codepage</term>
130
-
<listitem>
131
-
<simpara>
132
-
Specifies the codepage that is used to convert strings to
133
-
unicode-strings and vice versa. The conversion is applied whenever a
134
-
PHP string is passed as a parameter or returned from a method of this
135
-
COM object. The code page is sticky in PHP 5, which means that it will
136
-
propagate to objects and variants returned from the object.
137
-
</simpara>
138
-
<simpara>
139
-
Possible values are
140
-
<constant>CP_ACP</constant> (use system default ANSI code page - the
141
-
default if this parameter is omitted),
142
-
<constant>CP_MACCP</constant>,
143
-
<constant>CP_OEMCP</constant>, <constant>CP_SYMBOL</constant>,
144
-
<constant>CP_THREAD_ACP</constant> (use codepage/locale set for the
145
-
current executing thread), <constant>CP_UTF7</constant>
146
-
and <constant>CP_UTF8</constant>. You may also use the number for a
147
-
given codepage; consult the Microsoft documentation for more details on
148
-
codepages and their numeric values.
149
-
</simpara>
150
-
</listitem>
151
-
</varlistentry>
152
-
</variablelist>
153
-
</para>
154
-
</section>
155
-

156
-
<section xml:id="class.com.overloadedmethods">
157
-
<title>Overloaded Methods</title>
158
-
<para>
159
-
The returned object is an overloaded object, which means that PHP does
160
-
not see any fixed methods as it does with regular classes; instead, any
161
-
property or method accesses are passed through to COM.
162
-
</para>
163
-
<para>
164
-
Starting with PHP 5, PHP will automatically detect methods that accept
165
-
parameters by reference, and will automatically convert regular PHP
166
-
variables to a form that can be passed by reference. This means that you
167
-
can call the method very naturally; you needn't go to any extra effort in
168
-
your code.
169
-
</para>
170
-
<para>
171
-
In PHP 4, to pass parameters by reference you need to create an instance
172
-
of the <xref linkend="class.variant"/> class to wrap the
173
-
byref parameters.
174
-
</para>
175
-
</section>
176
-

177
-
<section xml:id="class.com.falsemethods">
178
-
<title>Pseudo Methods</title>
179
-
<para>
180
-
In PHP versions prior to 5, a number of not very pleasant hacks meant that
181
-
the following method names were not passed through to COM and were handled
182
-
directly by PHP. PHP 5 eliminates these things; read the details below to
183
-
determine how to fix your scripts. These magic method names are case
184
-
insensitive.
185
-
</para>
186
-
<methodsynopsis xml:id="com.addref">
187
-
<type>void</type><methodname>COM::AddRef</methodname>
188
-
<void/>
189
-
</methodsynopsis>
190
-
<simpara>
191
-
Artificially adds a reference count to the COM object.
192
-
</simpara>
193
-
<warning>
194
-
<simpara>
195
-
You should never need to use this method. It exists as a logical complement
196
-
to the Release() method below.
197
-
</simpara>
198
-
</warning>
199
-
<methodsynopsis xml:id="com.release">
200
-
<type>void</type><methodname>COM::Release</methodname>
201
-
<void/>
202
-
</methodsynopsis>
203
-
<simpara>
204
-
Artificially removes a reference count from the COM object.
205
-
</simpara>
206
-
<warning>
207
-
<simpara>
208
-
You should never need to use this method. Its existence in PHP is a bug
209
-
designed to work around a bug that keeps COM objects running longer than
210
-
they should.
211
-
</simpara>
212
-
</warning>
213
-
</section>
214
-
<section xml:id="class.com.iteratormethods">
215
-
<title>Pseudo Methods for Iterating</title>
216
-
<para>
217
-
These pseudo methods are only available if
218
-
<function>com_isenum</function> returns &true;, in which case, they hide
219
-
any methods with the same names that might otherwise be provided by the
220
-
COM object. These methods have all been eliminated in PHP 5, and you
221
-
should use <xref linkend="com.examples.foreach"/> instead.
222
-
</para>
223
-
<methodsynopsis xml:id="com.all">
224
-
<type>variant</type><methodname>COM::All</methodname>
225
-
<void/>
226
-
</methodsynopsis>
227
-
<simpara>
228
-
Returns a variant representing a SafeArray that has 10 elements;
229
-
each element will be an empty/null variant. This function was supposed to
230
-
return an array containing all the elements from the iterator, but was
231
-
never completed. Do not use.
232
-
</simpara>
233
-
<methodsynopsis xml:id="com.next">
234
-
<type>variant</type><methodname>COM::Next</methodname>
235
-
<void/>
236
-
</methodsynopsis>
237
-
<simpara>
238
-
Returns a variant representing the next element available from
239
-
the iterator, or &false; when there are no more elements.
240
-
</simpara>
241
-
<methodsynopsis xml:id="com.prev">
242
-
<type>variant</type><methodname>COM::Prev</methodname>
243
-
<void/>
244
-
</methodsynopsis>
245
-
<simpara>Returns a variant representing the previous element available from
246
-
the iterator, or &false; when there are no more elements.
247
-
</simpara>
248
-
<methodsynopsis xml:id="com.reset">
249
-
<type>void</type><methodname>COM::Reset</methodname>
250
-
<void/>
251
-
</methodsynopsis>
252
-
<simpara>
253
-
Rewinds the iterator back to the start.
254
-
</simpara>
255
-
</section>
256
-
<section xml:id="class.com.examples">
257
-
<title>COM examples</title>
258
-
<para>
259
-
<example xml:id="example.com1">
260
-
<title>COM example (1)</title>
261
-
<programlisting role="php">
9
+
<!-- {{{ com intro -->
10
+
<section xml:id="com.intro">
11
+
&reftitle.intro;
12
+
<para>
13
+
The com class allows you to instantiate an OLE compatible COM object and
14
+
call its methods and access its properties.
15
+
</para>
16
+
</section>
17
+
<!-- }}} -->
18
+

19
+
<section xml:id="com.synopsis">
20
+
&reftitle.classsynopsis;
21
+

22
+
<!-- {{{ Synopsis -->
23
+
<classsynopsis class="class">
24
+
<ooclass>
25
+
<classname>com</classname>
26
+
</ooclass>
27
+

28
+
<ooclass>
29
+
<modifier>extends</modifier>
30
+
<classname>variant</classname>
31
+
</ooclass>
32
+

33
+
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
34
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.com')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='com'])">
35
+
<xi:fallback/>
36
+
</xi:include>
37
+
</classsynopsis>
38
+
<!-- }}} -->
39
+

40
+
</section>
41
+

42
+
<section xml:id="class.com.overloadedmethods">
43
+
<title>Overloaded Methods</title>
44
+
<para>
45
+
The returned object is an overloaded object, which means that PHP does
46
+
not see any fixed methods as it does with regular classes; instead, any
47
+
property or method accesses are passed through to COM.
48
+
</para>
49
+
<para>
50
+
PHP will automatically detect methods that accept
51
+
parameters by reference, and will automatically convert regular PHP
52
+
variables to a form that can be passed by reference. This means that you
53
+
can call the method very naturally; you needn't go to any extra effort in
54
+
your code.
55
+
</para>
56
+
</section>
57
+

58
+
<section xml:id="class.com.examples">
59
+
<title>com examples</title>
60
+
<para>
61
+
<example xml:id="example.com1">
62
+
<title>com example (1)</title>
63
+
<programlisting role="php">
262
64
<![CDATA[
263
65
<?php
264
66
// starting word
265
-
$word = new COM("word.application") or die("Unable to instantiate Word");
67
+
$word = new com("word.application") or die("Unable to instantiate Word");
266
68
echo "Loaded Word, version {$word->Version}\n";
267
69

268
70
//bring it to front
...
...
@@ -283,16 +85,16 @@ $word = null;
283
85
?>
284
86
]]>
285
87
</programlisting>
286
-
</example>
287
-
</para>
288
-
<para>
289
-
<example xml:id="example.com2">
290
-
<title>COM example (2)</title>
291
-
<programlisting role="php">
88
+
</example>
89
+
</para>
90
+
<para>
91
+
<example xml:id="example.com2">
92
+
<title>com example (2)</title>
93
+
<programlisting role="php">
292
94
<![CDATA[
293
95
<?php
294
96

295
-
$conn = new COM("ADODB.Connection") or die("Cannot start ADO");
97
+
$conn = new com("ADODB.Connection") or die("Cannot start ADO");
296
98
$conn->Open("Provider=SQLOLEDB; Data Source=localhost;
297
99
Initial Catalog=database; User ID=user; Password=password");
298
100

...
...
@@ -323,14 +125,16 @@ $conn = null;
323
125

324
126
?>
325
127
]]>
326
-
</programlisting>
327
-
</example>
328
-
</para>
329
-
</section>
128
+
</programlisting>
129
+
</example>
130
+
</para>
131
+
</section>
330
132

331
133
</partintro>
332
-
</phpdoc:classref>
333
134

135
+
&reference.com.entities.com;
136
+

137
+
</phpdoc:classref>
334
138
<!-- Keep this comment at the end of the file
335
139
Local variables:
336
140
mode: sgml
337
141