expatapi(3tcl)
NAME
CheckExpatParserObj, CHandlerSetInstall, CHandlerSetRemove, CHandlerSetCreate, CHandlerSetGetUserData, GetExpatInfo - Functions to create,
install and remove expat parser object extensions.
SYNOPSIS
#include <tclexpat.h> int CheckExpatParserObj (interp, nameObj) int CHandlerSetInstall (interp, expatObj, handlerSet) int CHandlerSetRemove (interp, expatObj, handlerSetName) CHandlerSet* CHandlerSetCreate (handlerSetName) CHandlerSet* CHandlerSetGet (interp, expatObj, handlerSetName) void* CHandlerSetGetUserData (interp, expatObj, handlerSetName) TclGenExpatInfo* GetExpatInfo (interp, expatObj)
ARGUMENTS
- Tcl_Interp *interp (in) Interpreter with the expat
- parser object.
- Tcl_Obj *expatObj (in) A Tcl Object containing the com
- mand name of the expat parser object to be queried or modified.
- char *handlerSetName(in) Identifier of the handler set.
- CHandlerSet *handlerSet (in) Pointer to a C handler set.
- Tcl_Obj *nameObj A Tcl Object containing the name
- of a expat parser object
- _________________________________________________________________
DESCRIPTION
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.
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.
- A C level handler set is a data structure like this:
- 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;
- 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).
- The name of this structure is used to identify the handler set.
- If the flag ignoreWhiteCDATAs is set, element content which contain only whitespace isn't reported with the datacommand.
- The userData element points to the handler set specific data. The event handler functions are called with this pointer as userData argument.
- resetProc and freeProc must have arguments that match the type
- void (Tcl_Interp *interp, void *userData)
- resetProc is called in case the parser is reseted with <parserObj> reset and should do any necessary cleanup and reinitializing to prepare the C handler set for a new XML document. The freeProc is called, if the parser is deleted and should do memory cleanup etc.
- CHandlerSetCreate create a C handler set, gives it the name name and initializes any other element with NULL.
- CHandlerSetInstall adds the handlerSet to the parser expatObj. The parser has to be a tDOM Tcl expat parser object in the interpreter interp. The name of the C handler set has to be unique for the parser. Returns 0 in case of success. Returns 1 if expatObj isn't a parser object in the interpreter interp. Returns 2 if this parser has already a C handler set with the handlerSet name.
- CHandlerSetRemove removes the C handler set referenced by the handlerSetName from the parser expatObj. The parser has to be a tDOM Tcl expat parser object in the interpreter interp. CHandlerSetRemove 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 expatObj isn't a parser object in the interpreter interp. Returns 2 if this parser hasn't a C handler set named handlerSetName.
- CheckExpatParserObj returns 1, if nameObj is a tDOM Tcl expat parser object in the interpreter interp, otherwise it returns 0. 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;}
/* ... */ - CHandlerSetGet returns a pointer to the C handler Set referenced by the name handlerSetName of the parser object expatObj. expatObj has to be an expat parser object in the interpreter interp. Returns NULL in case of error.
- CHandlerSetGetUserData returns a pointer to the userData of the C handler set referenced by the name handlerSetName of the parser object expatObj. expatObj has to be an expat parser object in the interpreter interp. Returns NULL in case of error.
- GetExpatInfo Is a helper function that returns a pointer to the TclGenExpatInfo structure of the tDOM Tcl expat parser object expatObj. The expatObj has to be a tDOM Tcl expat parser object in the interpreter interp. This is most useful, to set the application status of the parser object.
- 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).
SEE ALSO
expat
KEYWORDS
- C handler set