1expatapi(3) expatapi(3)
2______________________________________________________________________________
6
8 CheckExpatParserObj, CHandlerSetInstall, CHandlerSetRemove, CHandler‐
9 SetCreate, CHandlerSetGetUserData, GetExpatInfo - Functions to create,
10 install and remove expat parser object extensions.
11
13 #include <tclexpat.h>
14 int
16 CheckExpatParserObj (interp, nameObj)
17 int
19 CHandlerSetInstall (interp, expatObj, handlerSet)
20 int
22 CHandlerSetRemove (interp, expatObj, handlerSetName)
23 CHandlerSet*
25 CHandlerSetCreate (handlerSetName)
26 CHandlerSet*
28 CHandlerSetGet (interp, expatObj, handlerSetName)
29 void*
31 CHandlerSetGetUserData (interp, expatObj, handlerSetName)
32 TclGenExpatInfo*
34 GetExpatInfo (interp, expatObj)
35
38 Tcl_Interp *interp (in) Interpreter with the expat
39 parser object.
40 Tcl_Obj *expatObj (in) A Tcl Object containing the com‐
42 mand name of the expat parser
43 object to be queried or modi‐
44 fied.
45 char *handlerSetName(in) Identifier of the handler set.
47 CHandlerSet *handlerSet (in) Pointer to a C handler set.
49 Tcl_Obj *nameObj A Tcl Object containing the name
51 of a expat parser object
52_________________________________________________________________
53
55 The functions described in this manual allows to add C level coded
56 event handler to an tDOM Tcl expat parser objects. A tDOM Tcl expat
57 parser object is able to have several Tcl scripts and C functions asso‐
58 ciated with an specific event. If the event occurs, first the Tcl
59 scripts then the C functions associated with the event are called in
60 turn.
61 A tDOM Tcl expat parser extension is an ordinary Tcl extension and
63 loaded like every other Tcl extension. It must install at least one new
64 Tcl Level command, that manipulates a tDOM Tcl expat parser object.
65 A C level handler set is a data structure like this:
67 typedef struct CHandlerSet {
69 struct CHandlerSet *nextHandlerSet;
70 char *name; /* refname of the handler set */
71 int ignoreWhiteCDATAs; /* ignore 'white' CDATA sections */
72 void *userData; /* Handler set specific Data Structure;
74 the C handler set extention has to
75 malloc the needed structure in his
76 init func and has to provide a
77 cleanup func (to free it). */
78 CHandlerSet_userDataReset resetProc;
80 CHandlerSet_userDataFree freeProc;
81 /* C func for element start */
83 XML_StartElementHandler elementstartcommand;
84 /* C func for element end */
85 XML_EndElementHandler elementendcommand;
86 /* C func for character data */
87 XML_CharacterDataHandler datacommand;
88 /* C func for namespace decl start */
89 XML_StartNamespaceDeclHandler startnsdeclcommand;
90 /* C func for namespace decl end */
91 XML_EndNamespaceDeclHandler endnsdeclcommand;
92 /* C func for processing instruction */
93 XML_ProcessingInstructionHandler picommand;
94 /* C func for default data */
95 XML_DefaultHandler defaultcommand;
96 /* C func for unparsed entity declaration */
97 XML_NotationDeclHandler notationcommand;
98 /* C func for external entity */
99 XML_ExternalEntityRefHandler externalentitycommand;
100 /* C func for unknown encoding */
101 XML_UnknownEncodingHandler unknownencodingcommand;
102 /* C func for comments */
103 XML_CommentHandler commentCommand;
104 /* C func for "not standalone" docs */
105 XML_NotStandaloneHandler notStandaloneCommand;
106 /* C func for CDATA section start */
107 XML_StartCdataSectionHandler startCdataSectionCommand;
108 /* C func for CDATA section end */
109 XML_EndCdataSectionHandler endCdataSectionCommand;
110 /* C func for !ELEMENT decl's */
111 XML_ElementDeclHandler elementDeclCommand;
112 /* C func for !ATTLIST decl's */
113 XML_AttlistDeclHandler attlistDeclCommand;
114 /* C func for !DOCTYPE decl's */
115 XML_StartDoctypeDeclHandler startDoctypeDeclCommand;
116 /* C func for !DOCTYPE decl ends */
117 XML_EndDoctypeDeclHandler endDoctypeDeclCommand;
118 /* C func for !ENTITY decls's */
119 XML_EntityDeclHandler entityDeclCommand;
120 } CHandlerSet;
121 The types and the arguments of the event functions (XML_*) are exactly
124 the same like the expat lib handler functions and described in detail
125 in expat.h, see there. The extension has only to provided the handler
126 functions needed; it's perfectly OK to leave unused handler slots as
127 the are (they are initialized to NULL by CHandlerSetCreate).
128 The name of this structure is used to identify the handler set.
130 If the flag ignoreWhiteCDATAs is set, element content which contain
132 only whitespace isn't reported with the datacommand.
133 The userData element points to the handler set specific data. The event
135 handler functions are called with this pointer as userData argument.
136 resetProc and freeProc must have arguments that match the type
138 void (Tcl_Interp *interp, void *userData)
139 resetProc is called in case the parser is reseted with <parserObj>
141 reset and should do any necessary cleanup and reinitializing to prepare
142 the C handler set for a new XML document. The freeProc is called, if
143 the parser is deleted and should do memory cleanup etc.
144 CHandlerSetCreate create a C handler set, gives it the name name and
146 initializes any other element with NULL.
147 CHandlerSetInstall adds the handlerSet to the parser expatObj. The
149 parser has to be a tDOM Tcl expat parser object in the interpreter
150 interp. The name of the C handler set has to be unique for the parser.
151 Returns 0 in case of success. Returns 1 if expatObj isn't a parser
152 object in the interpreter interp. Returns 2 if this parser has already
153 a C handler set with the handlerSet name.
154 CHandlerSetRemove removes the C handler set referenced by the handler‐
156 SetName from the parser expatObj. The parser has to be a tDOM Tcl expat
157 parser object in the interpreter interp. CHandlerSetRemove calls the
158 freeProc function of the C handler set structure, removes the handler
159 set from the C handler set list and frees the handler structure.
160 Returns 0 in case of success. Returns 1 if expatObj isn't a parser
161 object in the interpreter interp. Returns 2 if this parser hasn't a C
162 handler set named handlerSetName.
163 CheckExpatParserObj returns 1, if nameObj is a tDOM Tcl expat parser
165 object in the interpreter interp, otherwise it returns 0. Example:
166 int
168 TclExampleObjCmd(dummy, interp, objc, objv)
169 ClientData dummy;
170 Tcl_Interp *interp;
171 int objc;
172 Tcl_Obj *CONST objv[];
173 {
174 char *method;
175 CHandlerSet *handlerSet;
176 int methodIndex, result;
177 simpleCounter *counter;
178 static char *exampleMethods[] = {
181 "enable", "getresult", "remove",
182 NULL
183 };
184 enum exampleMethod {
185 m_enable, m_getresult, m_remove
186 };
187 if (objc != 3) {
189 Tcl_WrongNumArgs (interp, 1, objv, example_usage);
190 return TCL_ERROR;
191 }
192 if (!CheckExpatParserObj (interp, objv[1])) {
194 Tcl_SetResult (interp, "First argument has to be a expat parser object", NULL);
195 return TCL_ERROR;
196 }
197 /* ... */
198 CHandlerSetGet returns a pointer to the C handler Set referenced by the
201 name handlerSetName of the parser object expatObj. expatObj has to be
202 an expat parser object in the interpreter interp. Returns NULL in case
203 of error.
204 CHandlerSetGetUserData returns a pointer to the userData of the C han‐
206 dler set referenced by the name handlerSetName of the parser object
207 expatObj. expatObj has to be an expat parser object in the interpreter
208 interp. Returns NULL in case of error.
209 GetExpatInfo Is a helper function that returns a pointer to the TclGen‐
211 ExpatInfo structure of the tDOM Tcl expat parser object expatObj. The
212 expatObj has to be a tDOM Tcl expat parser object in the interpreter
213 interp. This is most useful, to set the application status of the
214 parser object.
215 See the simple but full functionally example in the extensions/example
217 dir or the more complex example tnc in the extensions/tnc dir (a simple
218 DTD validation extension).
219
221 expat
222
224 C handler set
225Tcl expatapi(3)