214 lines
13 KiB
HTML
214 lines
13 KiB
HTML
<html>
|
||
<head>
|
||
<link rel="stylesheet" href="manpage.css"><title>tDOM manual: expatapi</title><meta name="xsl-processor" content="Jochen Loewer et. al. (loewerj@hotmail.com)"><meta name="generator" content="$RCSfile: expatapi.html,v $ $Revision: 1.2 $">
|
||
</head><body>
|
||
<div class="header">
|
||
<div class="navbar" align="center">
|
||
<a href="#SECTnode8831">NAME</a> · <a href="#SECTnode8840">SYNOPSIS</a> · <a href="#SECTnode8918">ARGUMENTS</a> · <a href="#SECTnode8999">DESCRIPTION</a> · <a href="#SECTnode9184">SEE ALSO</a> · <a href="#SECTnode9190">KEYWORDS</a>
|
||
</div><hr class="navsep">
|
||
</div><div class="body">
|
||
<h2><a name="SECTnode8831">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="SECTnode8840">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="SECTnode8918">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="SECTnode8999">DESCRIPTION</a></h2><p>The functions described in this manual allows 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 extention 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 reseted 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="SECTnode9184">SEE ALSO</a></h2><p class="seealso"><a href="expat.html">expat</a></p>
|
||
|
||
<h2><a name="SECTnode9190">KEYWORDS</a></h2><p class="keywords"><a class="keyword" href="keyword-index.html#KW-Chandlerset">C handler set</a></p>
|
||
</div><div class="footer">
|
||
<hr class="navsep"><!-- footer.html: Standard navigational footer --><div class="navbar" align="center">
|
||
<a class="navaid" href="index.html">Table of Contents</a>
|
||
· <a class="navaid" href="category-index.html">Index</a>
|
||
· <a class="navaid" href="keyword-index.html">Keywords</a>
|
||
</div>
|
||
</div>
|
||
</body>
|
||
</html>
|