reference/xml/functions/xml-set-external-entity-ref-handler.xml
5a14f904d231d294e2e5b4fb5d2fc4d2fd9eddee
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.xml-set-external-entity-ref-handler">
3
+
<refentry xml:id="function.xml-set-external-entity-ref-handler" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>xml_set_external_entity_ref_handler</refname>
6
6
<refpurpose>Set up external entity reference handler</refpurpose>
...
...
@@ -9,8 +9,8 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>bool</type><methodname>xml_set_external_entity_ref_handler</methodname>
13
-
<methodparam><type>resource</type><parameter>parser</parameter></methodparam>
12
+
<type>true</type><methodname>xml_set_external_entity_ref_handler</methodname>
13
+
<methodparam><type>XMLParser</type><parameter>parser</parameter></methodparam>
14
14
<methodparam><type>callable</type><parameter>handler</parameter></methodparam>
15
15
</methodsynopsis>
16
16
<para>
...
...
@@ -23,53 +23,28 @@
23
23
&reftitle.parameters;
24
24
<para>
25
25
<variablelist>
26
-
<varlistentry>
27
-
<term><parameter>parser</parameter></term>
28
-
<listitem>
29
-
<para>
30
-
A reference to the XML parser to set up external entity reference handler function.
31
-
</para>
32
-
</listitem>
33
-
</varlistentry>
26
+
&xml.parser.param;
34
27
<varlistentry>
35
28
<term><parameter>handler</parameter></term>
36
29
<listitem>
30
+
&xml.handler.description;
37
31
<para>
38
-
<parameter>handler</parameter> is a string containing the name of a
39
-
function that must exist when <function>xml_parse</function> is called
40
-
for <parameter>parser</parameter>.
41
-
</para>
42
-
<para>
43
-
The function named by <parameter>handler</parameter> must accept
44
-
five parameters, and should return an integer value.If the
45
-
value returned from the handler is &false; (which it will be if no
46
-
value is returned), the XML parser will stop parsing and
47
-
<function>xml_get_error_code</function> will return
48
-
<constant>XML_ERROR_EXTERNAL_ENTITY_HANDLING</constant>.
32
+
The signature of the handler must be:
49
33
<methodsynopsis>
50
-
<methodname><replaceable>handler</replaceable></methodname>
51
-
<methodparam><type>resource</type><parameter>parser</parameter></methodparam>
34
+
<type>bool</type><methodname><replaceable>handler</replaceable></methodname>
35
+
<methodparam><type>XMLParser</type><parameter>parser</parameter></methodparam>
52
36
<methodparam><type>string</type><parameter>open_entity_names</parameter></methodparam>
53
-
<methodparam><type>string</type><parameter>base</parameter></methodparam>
37
+
<methodparam><type class="union"><type>string</type><type>false</type></type><parameter>base</parameter></methodparam>
54
38
<methodparam><type>string</type><parameter>system_id</parameter></methodparam>
55
-
<methodparam><type>string</type><parameter>public_id</parameter></methodparam>
39
+
<methodparam><type class="union"><type>string</type><type>false</type></type><parameter>public_id</parameter></methodparam>
56
40
</methodsynopsis>
57
41
<variablelist>
58
-
<varlistentry>
59
-
<term><parameter>parser</parameter></term>
60
-
<listitem>
61
-
<simpara>
62
-
The first parameter, <replaceable>parser</replaceable>, is a
63
-
reference to the XML parser calling the handler.
64
-
</simpara>
65
-
</listitem>
66
-
</varlistentry>
42
+
&xml.handler.parser.param;
67
43
<varlistentry>
68
44
<term><parameter>open_entity_names</parameter></term>
69
45
<listitem>
70
46
<simpara>
71
-
The second parameter, <parameter>open_entity_names</parameter>, is a
72
-
space-separated list of the names of the entities that are open for
47
+
A space-separated list of the names of the entities that are open for
73
48
the parse of this entity (including the name of the referenced
74
49
entity).
75
50
</simpara>
...
...
@@ -80,8 +55,7 @@
80
55
<listitem>
81
56
<simpara>
82
57
This is the base for resolving the system identifier
83
-
(<parameter>system_id</parameter>) of the external entity.Currently
84
-
this parameter will always be set to an empty string.
58
+
(<parameter>system_id</parameter>) of the external entity.
85
59
</simpara>
86
60
</listitem>
87
61
</varlistentry>
...
...
@@ -89,8 +63,7 @@
89
63
<term><parameter>system_id</parameter></term>
90
64
<listitem>
91
65
<simpara>
92
-
The fourth parameter, <parameter>system_id</parameter>, is the
93
-
system identifier as specified in the entity declaration.
66
+
The system identifier as specified in the entity declaration.
94
67
</simpara>
95
68
</listitem>
96
69
</varlistentry>
...
...
@@ -98,8 +71,7 @@
98
71
<term><parameter>public_id</parameter></term>
99
72
<listitem>
100
73
<simpara>
101
-
The fifth parameter, <parameter>public_id</parameter>, is the
102
-
public identifier as specified in the entity declaration, or
74
+
The public identifier as specified in the entity declaration, or
103
75
an empty string if none was specified; the whitespace in the
104
76
public identifier will have been normalized as required by
105
77
the XML spec.
...
...
@@ -109,10 +81,12 @@
109
81
</variablelist>
110
82
</para>
111
83
<para>
112
-
If a handler function is set to an empty string, or &false;, the handler
113
-
in question is disabled.
84
+
The handler should return &true; if the entity was handled,
85
+
&false; otherwise.
86
+
When returning &false; the XML parser will stop parsing and
87
+
<function>xml_get_error_code</function> will return
88
+
<constant>XML_ERROR_EXTERNAL_ENTITY_HANDLING</constant>.
114
89
</para>
115
-
&note.func-callback;
116
90
</listitem>
117
91
</varlistentry>
118
92
</variablelist>
...
...
@@ -122,12 +96,36 @@
122
96
<refsect1 role="returnvalues">
123
97
&reftitle.returnvalues;
124
98
<para>
125
-
&return.success;
99
+
&return.true.always;
126
100
</para>
127
101
</refsect1>
128
102

129
-
</refentry>
103
+
<refsect1 role="changelog">
104
+
&reftitle.changelog;
105
+
<informaltable>
106
+
<tgroup cols="2">
107
+
<thead>
108
+
<row>
109
+
<entry>&Version;</entry>
110
+
<entry>&Description;</entry>
111
+
</row>
112
+
</thead>
113
+
<tbody>
114
+
&xml.changelog.parser-param;
115
+
<row>
116
+
<entry>7.3.0</entry>
117
+
<entry>
118
+
The return value of the <parameter>handler</parameter> is no longer
119
+
ignored if the extension has been built against libxml. Formerly, the return
120
+
value has been ignored, and parsing did never stop.
121
+
</entry>
122
+
</row>
123
+
</tbody>
124
+
</tgroup>
125
+
</informaltable>
126
+
</refsect1>
130
127

128
+
</refentry>
131
129
<!-- Keep this comment at the end of the file
132
130
Local variables:
133
131
mode: sgml
134
132