<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 &lt;tclexpat.h&gt;

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">&lt;parserObj&gt; 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>
