<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="#SECTid0x1e7b920">NAME</a> · <a href="#SECTid0x1d90950">SYNOPSIS</a> · <a href="#SECTid0x1eef570">ARGUMENTS</a> · <a href="#SECTid0x1ef1660">DESCRIPTION</a> · <a href="#SECTid0x1ea6080">SEE ALSO</a> · <a href="#SECTid0x1ea6320">KEYWORDS</a>
</div><hr class="navsep">
</div><div class="body">
<h2><a name="SECTid0x1e7b920">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="SECTid0x1d90950">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="SECTid0x1eef570">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="SECTid0x1ef1660">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="SECTid0x1ea6080">SEE ALSO</a></h2><p class="seealso">expat</p>
<h2><a name="SECTid0x1ea6320">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>