1expatapi(3)                                                        expatapi(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       CheckExpatParserObj,  CHandlerSetInstall,  CHandlerSetRemove, CHandler‐
9       SetCreate, CHandlerSetGetUserData, GetExpatInfo - Functions to  create,
10       install and remove expat parser object extensions.
11

SYNOPSIS

13       #include <tclexpat.h>
14
15       int
16       CheckExpatParserObj (interp, nameObj)
17
18       int
19       CHandlerSetInstall (interp, expatObj, handlerSet)
20
21       int
22       CHandlerSetRemove (interp, expatObj, handlerSetName)
23
24       CHandlerSet*
25       CHandlerSetCreate (handlerSetName)
26
27       CHandlerSet*
28       CHandlerSetGet (interp, expatObj, handlerSetName)
29
30       void*
31       CHandlerSetGetUserData (interp, expatObj, handlerSetName)
32
33       TclGenExpatInfo*
34       GetExpatInfo (interp, expatObj)
35
36

ARGUMENTS

38       Tcl_Interp      *interp      (in)      Interpreter   with   the   expat
39                                              parser object.
40
41       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
46       char            *handlerSetName(in)    Identifier of the handler set.
47
48       CHandlerSet     *handlerSet  (in)      Pointer to a C handler set.
49
50       Tcl_Obj         *nameObj               A Tcl Object containing the name
51                                              of a expat parser object
52_________________________________________________________________
53

DESCRIPTION

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
62       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
66       A C level handler set is a data structure like this:
67
68              typedef struct CHandlerSet {
69                  struct CHandlerSet *nextHandlerSet;
70                  char *name;                     /* refname of the handler set */
71                  int ignoreWhiteCDATAs;          /* ignore 'white' CDATA sections */
72
73                  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
79                  CHandlerSet_userDataReset        resetProc;
80                  CHandlerSet_userDataFree         freeProc;
81
82                  /* 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
122
123       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
129       The name of this structure is used to identify the handler set.
130
131       If  the  flag  ignoreWhiteCDATAs  is set, element content which contain
132       only whitespace isn't reported with the datacommand.
133
134       The userData element points to the handler set specific data. The event
135       handler functions are called with this pointer as userData argument.
136
137       resetProc and freeProc must have arguments that match the type
138              void (Tcl_Interp *interp, void *userData)
139
140       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
145       CHandlerSetCreate create a C handler set, gives it the  name  name  and
146       initializes any other element with NULL.
147
148       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
155       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
164       CheckExpatParserObj  returns  1,  if nameObj is a tDOM Tcl expat parser
165       object in the interpreter interp, otherwise it returns 0. Example:
166
167              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
179
180                  static char *exampleMethods[] = {
181                      "enable", "getresult", "remove",
182                      NULL
183                  };
184                  enum exampleMethod {
185                      m_enable, m_getresult, m_remove
186                  };
187
188                  if (objc != 3) {
189                      Tcl_WrongNumArgs (interp, 1, objv, example_usage);
190                      return TCL_ERROR;
191                  }
192
193                  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
199
200       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
205       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
210       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
216       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

SEE ALSO

221       expat
222

KEYWORDS

224       C handler set
225
226
227
228Tcl                                                                expatapi(3)
Impressum