1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
<html>
<head>
<link rel="stylesheet" href="manpage.css"><title>tDOM manual: expatapi</title><meta name="xsl-processor" content="Jochen Loewer (loewerj@hotmail.com), Rolf Ade (rolf@pointsman.de) et. al."><meta name="generator" content="$RCSfile: tmml-html.xsl,v $ $Revision: 1.11 $"><meta charset="utf-8">
</head><body>
<div class="header">
<div class="navbar" align="center">
<a href="#SECTid0x5569427a27e0">NAME</a> · <a href="#SECTid0x556942858880">SYNOPSIS</a> · <a href="#SECTid0x556942813080">ARGUMENTS</a> · <a href="#SECTid0x556942815140">DESCRIPTION</a> · <a href="#SECTid0x55694286ee00">SEE ALSO</a> · <a href="#SECTid0x55694286f0a0">KEYWORDS</a>
</div><hr class="navsep">
</div><div class="body">
<h2><a name="SECTid0x5569427a27e0">NAME</a></h2><p class="namesection">
<b class="names">CheckExpatParserObj, CHandlerSetInstall, CHandlerSetRemove,
CHandlerSetCreate, CHandlerSetGetUserData, GetExpatInfo - </b><br>Functions to create, install and remove expat parser object
extensions.</p>
<h2><a name="SECTid0x556942858880">SYNOPSIS</a></h2><pre class="syntax">#include <tclexpat.h>
int
<b class="fun">CheckExpatParserObj</b> (<a href="#ARG-interp"><i>interp</i></a>, <a href="#ARG-nameObj"><i>nameObj</i></a>)
int
<b class="fun">CHandlerSetInstall</b> (<a href="#ARG-interp"><i>interp</i></a>, <a href="#ARG-expatObj"><i>expatObj</i></a>, <a href="#ARG-handlerSet"><i>handlerSet</i></a>)
int
<b class="fun">CHandlerSetRemove</b> (<a href="#ARG-interp"><i>interp</i></a>, <a href="#ARG-expatObj"><i>expatObj</i></a>, <a href="#ARG-handlerSetName"><i>handlerSetName</i></a>)
CHandlerSet*
<b class="fun">CHandlerSetCreate</b> (<a href="#ARG-handlerSetName"><i>handlerSetName</i></a>)
CHandlerSet*
<b class="fun">CHandlerSetGet</b> (<a href="#ARG-interp"><i>interp</i></a>, <a href="#ARG-expatObj"><i>expatObj</i></a>, <a href="#ARG-handlerSetName"><i>handlerSetName</i></a>)
void*
<b class="fun">CHandlerSetGetUserData</b> (<a href="#ARG-interp"><i>interp</i></a>, <a href="#ARG-expatObj"><i>expatObj</i></a>, <a href="#ARG-handlerSetName"><i>handlerSetName</i></a>)
TclGenExpatInfo*
<b class="fun">GetExpatInfo</b> (<a href="#ARG-interp"><i>interp</i></a>, <a href="#ARG-expatObj"><i>expatObj</i></a>)
</pre>
<h2><a name="SECTid0x556942813080">ARGUMENTS</a></h2><div class="arglist"><table width="100%" rules="none" cellpadding="5%">
<thead><tr class="heading">
<th width="20%">Type</th><th width="70%">Name</th><th width="10%">Mode</th>
</tr></thead><tr class="syntax">
<td class="type" width="20%" align="left">Tcl_Interp</td><td class="name" width="70%" align="left"><a name="ARG-interp">*interp</a></td><td class="mode" width="10%" align="center">in</td>
</tr><tr class="desc">
<td class="padding" width="20%"> </td><td class="argdesc" width="80%" align="left" colspan="2">Interpreter with the expat parser object.</td>
</tr><tr class="syntax">
<td class="type" width="20%" align="left">Tcl_Obj</td><td class="name" width="70%" align="left"><a name="ARG-expatObj">*expatObj</a></td><td class="mode" width="10%" align="center">in</td>
</tr><tr class="desc">
<td class="padding" width="20%"> </td><td class="argdesc" width="80%" align="left" colspan="2">A Tcl Object containing the command name of the expat parser object to be queried or modified.</td>
</tr><tr class="syntax">
<td class="type" width="20%" align="left">char</td><td class="name" width="70%" align="left"><a name="ARG-handlerSetName">*handlerSetName</a></td><td class="mode" width="10%" align="center">in</td>
</tr><tr class="desc">
<td class="padding" width="20%"> </td><td class="argdesc" width="80%" align="left" colspan="2">Identifier of the handler set.</td>
</tr><tr class="syntax">
<td class="type" width="20%" align="left">CHandlerSet</td><td class="name" width="70%" align="left"><a name="ARG-handlerSet">*handlerSet</a></td><td class="mode" width="10%" align="center">in</td>
</tr><tr class="desc">
<td class="padding" width="20%"> </td><td class="argdesc" width="80%" align="left" colspan="2">Pointer to a C handler set.</td>
</tr><tr class="syntax">
<td class="type" width="20%" align="left">Tcl_Obj</td><td class="name" width="70%" align="left"><a name="ARG-nameObj">*nameObj</a></td><td class="mode" width="10%" align="center"></td>
</tr><tr class="desc">
<td class="padding" width="20%"> </td><td class="argdesc" width="80%" align="left" colspan="2">A Tcl Object containing the name of a expat parser object</td>
</tr>
</table></div>
<h2><a name="SECTid0x556942815140">DESCRIPTION</a></h2><p>The functions described in this manual allows one to add C level coded event
handler to an tDOM Tcl expat parser objects. A tDOM Tcl expat parser object is
able to have several Tcl scripts and C functions associated with an specific
event. If the event occurs, first the Tcl scripts then the C functions
associated with the event are called in turn.</p><p>A tDOM Tcl expat parser extension is an ordinary Tcl extension and loaded
like every other Tcl extension. It must install at least one new Tcl Level
command, that manipulates a tDOM Tcl expat parser object.</p><p>A C level handler set is a data structure like this:</p><pre class="example">
typedef struct CHandlerSet {
struct CHandlerSet *nextHandlerSet;
char *name; /* refname of the handler set */
int ignoreWhiteCDATAs; /* ignore 'white' CDATA sections */
void *userData; /* Handler set specific Data Structure;
the C handler set extension has to
malloc the needed structure in his
init func and has to provide a
cleanup func (to free it). */
CHandlerSet_userDataReset resetProc;
CHandlerSet_userDataFree freeProc;
/* C func for element start */
XML_StartElementHandler elementstartcommand;
/* C func for element end */
XML_EndElementHandler elementendcommand;
/* C func for character data */
XML_CharacterDataHandler datacommand;
/* C func for namespace decl start */
XML_StartNamespaceDeclHandler startnsdeclcommand;
/* C func for namespace decl end */
XML_EndNamespaceDeclHandler endnsdeclcommand;
/* C func for processing instruction */
XML_ProcessingInstructionHandler picommand;
/* C func for default data */
XML_DefaultHandler defaultcommand;
/* C func for unparsed entity declaration */
XML_NotationDeclHandler notationcommand;
/* C func for external entity */
XML_ExternalEntityRefHandler externalentitycommand;
/* C func for unknown encoding */
XML_UnknownEncodingHandler unknownencodingcommand;
/* C func for comments */
XML_CommentHandler commentCommand;
/* C func for "not standalone" docs */
XML_NotStandaloneHandler notStandaloneCommand;
/* C func for CDATA section start */
XML_StartCdataSectionHandler startCdataSectionCommand;
/* C func for CDATA section end */
XML_EndCdataSectionHandler endCdataSectionCommand;
/* C func for !ELEMENT decl's */
XML_ElementDeclHandler elementDeclCommand;
/* C func for !ATTLIST decl's */
XML_AttlistDeclHandler attlistDeclCommand;
/* C func for !DOCTYPE decl's */
XML_StartDoctypeDeclHandler startDoctypeDeclCommand;
/* C func for !DOCTYPE decl ends */
XML_EndDoctypeDeclHandler endDoctypeDeclCommand;
/* C func for !ENTITY decls's */
XML_EntityDeclHandler entityDeclCommand;
} CHandlerSet;
</pre><p>The types and the arguments of the event functions (XML_*) are exactly
the same like the expat lib handler functions and described in detail in
expat.h, see there. The extension has only to provided the handler functions
needed; it's perfectly OK to leave unused handler slots as the are (they are
initialized to NULL by CHandlerSetCreate).</p><p>The <i class="m">name</i> of this structure is used to identify the handler set.
</p><p>If the flag <i class="m">ignoreWhiteCDATAs</i> is set, element content which
contain only whitespace isn't reported with the datacommand. </p><p>The <i class="m">userData</i> element points to the handler set specific data. The
event handler functions are called with this pointer as userData argument.
</p><p>
<i class="m">resetProc</i> and <i class="m">freeProc</i> must have arguments that match the
type</p><pre class="syntax">void (Tcl_Interp *interp, void *userData)</pre><p>
<i class="m">resetProc</i> is called in case the parser is reset with
<tt class="samp"><parserObj> reset</tt> and should do any necessary cleanup and
reinitializing to prepare the C handler set for a new XML document. The
<i class="m">freeProc</i> is called, if the parser is deleted and should do memory
cleanup etc. </p><p> <i class="m">CHandlerSetCreate</i> create a C handler set, gives it the name
<i class="m">name</i> and initializes any other element with NULL.</p><p> <i class="m">CHandlerSetInstall</i> adds the <i class="m">handlerSet</i> to the parser
<i class="m">expatObj</i>. The parser has to be a tDOM Tcl expat parser object in the
interpreter <i class="m">interp</i>. The name of the C handler set has to be unique for
the parser. Returns 0 in case of success. Returns 1 if <i class="m">expatObj</i> isn't a
parser object in the interpreter <i class="m">interp</i>. Returns 2 if this parser has
already a C handler set with the handlerSet name.</p><p> <i class="m">CHandlerSetRemove</i> removes the C handler set referenced by the
<i class="m">handlerSetName</i> from the parser <i class="m">expatObj</i>. The parser has to be a
tDOM Tcl expat parser object in the interpreter
<i class="m">interp</i>. <i class="m">CHandlerSetRemove</i> calls the freeProc function of the C
handler set structure, removes the handler set from the C handler set list and
frees the handler structure. Returns 0 in case of success. Returns 1 if
<i class="m">expatObj</i> isn't a parser object in the interpreter <i class="m">interp</i>. Returns
2 if this parser hasn't a C handler set named <i class="m">handlerSetName</i>.</p><p>
<i class="m">CheckExpatParserObj</i> returns 1, if <i class="m">nameObj</i> is a tDOM Tcl expat
parser object in the interpreter <i class="m">interp</i>, otherwise it returns
0. Example:</p><pre class="example">
int
TclExampleObjCmd(dummy, interp, objc, objv)
ClientData dummy;
Tcl_Interp *interp;
int objc;
Tcl_Obj *const objv[];
{
char *method;
CHandlerSet *handlerSet;
int methodIndex, result;
simpleCounter *counter;
static char *exampleMethods[] = {
"enable", "getresult", "remove",
NULL
};
enum exampleMethod {
m_enable, m_getresult, m_remove
};
if (objc != 3) {
Tcl_WrongNumArgs (interp, 1, objv, example_usage);
return TCL_ERROR;
}
if (!CheckExpatParserObj (interp, objv[1])) {
Tcl_SetResult (interp, "First argument has to be a expat parser object", NULL);
return TCL_ERROR;
}
/* ... */
</pre><p> <i class="m">CHandlerSetGet</i> returns a pointer to the C handler Set referenced
by the name <i class="m">handlerSetName</i> of the parser object
<i class="m">expatObj</i>. <i class="m">expatObj</i> has to be an expat parser object in the
interpreter <i class="m">interp</i>. Returns NULL in case of error.</p><p>
<i class="m">CHandlerSetGetUserData</i> returns a pointer to the userData of the C
handler set referenced by the name <i class="m">handlerSetName</i> of the parser object
<i class="m">expatObj</i>. <i class="m">expatObj</i> has to be an expat parser object in the
interpreter <i class="m">interp</i>. Returns NULL in case of error.</p><p> <i class="m">GetExpatInfo</i> Is a helper function that returns a pointer to the
TclGenExpatInfo structure of the tDOM Tcl expat parser object
<i class="m">expatObj</i>. The <i class="m">expatObj</i> has to be a tDOM Tcl expat parser object
in the interpreter <i class="m">interp</i>. This is most useful, to set the application
status of the parser object.</p><p>See the simple but full functionally example in the extensions/example
dir or the more complex example tnc in the extensions/tnc dir (a simple DTD
validation extension).</p>
<h2><a name="SECTid0x55694286ee00">SEE ALSO</a></h2><p class="seealso">expat</p>
<h2><a name="SECTid0x55694286f0a0">KEYWORDS</a></h2><p class="keywords"><a class="keyword" href="keyword-index.html#KW-Chandlerset">C handler set</a></p>
</div><hr class="navsep"><div class="navbar" align="center">
<a class="navaid" href="index.html">Contents</a> · <a class="navaid" href="category-index.html">Index</a> · <a class="navaid" href="keyword-index.html">Keywords</a> · <a class="navaid" href="http://tdom.org">Repository</a>
</div>
</body>
</html>
|
