expatapi(3) expatapi(3)
NAME
CheckExpatParserObj, CHandlerSetInstall, CHandlerSetRemove, CHandler-
SetCreate, CHandlerSetGetUserData, GetExpatInfo - Functions to create,
install and remove expat parser object extensions.
SYNOPSIS
#include
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
TclInterp *interp (in) Interpreter with the expat
parser object.
TclObj *expatObj (in) A Tcl Object containing the com-
mand name of the expat parser
object to be queried or modi-
fied.
char *handlerSetName(in) Identifier of the handler set.
CHandlerSet *handlerSet (in) Pointer to a C handler set.
TclObj *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 asso-
ciated 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). */
CHandlerSetuserDataReset resetProc;
CHandlerSetuserDataFree freeProc;
/* C func for element start */
XMLStartElementHandler elementstartcommand;
/* C func for element end */
XMLEndElementHandler elementendcommand;
/* C func for character data */
XMLCharacterDataHandler datacommand;
/* C func for namespace decl start */
XMLStartNamespaceDeclHandler startnsdeclcommand;
/* C func for namespace decl end */
XMLEndNamespaceDeclHandler endnsdeclcommand;
/* C func for processing instruction */
XMLProcessingInstructionHandler picommand;
/* C func for default data */
XMLDefaultHandler defaultcommand;
/* C func for unparsed entity declaration */
XMLNotationDeclHandler notationcommand;
/* C func for external entity */
XMLExternalEntityRefHandler externalentitycommand;
/* C func for unknown encoding */
XMLUnknownEncodingHandler unknownencodingcommand;
/* C func for comments */
XMLCommentHandler commentCommand;
/* C func for "not standalone" docs */
XMLNotStandaloneHandler notStandaloneCommand;
/* C func for CDATA section start */
XMLStartCdataSectionHandler startCdataSectionCommand;
/* C func for CDATA section end */
XMLEndCdataSectionHandler endCdataSectionCommand;
/* C func for !ELEMENT decl's */
XMLElementDeclHandler elementDeclCommand;
/* C func for !ATLIST decl's */
XMLAttlistDeclHandler attlistDeclCommand;
/* C func for !DOCTYPE decl's */
XMLStartDoctypeDeclHandler startDoctypeDeclCommand;
/* C func for !DOCTYPE decl ends */
XMLEndDoctypeDeclHandler endDoctypeDeclCommand;
/* C func for !ENTITY decls's */
XMLEntityDeclHandler 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 NUL 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 (TclInterp *interp, void *userData)
resetProc is called in case the parser is reseted with <>
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 NUL.
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 handler-
SetName 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;
TclInterp *interp;
int objc;
TclObj *CONST objv[];
{
char *method;
CHandlerSet *handlerSet;
int methodIndex, result;
simpleCounter *counter;
static char *exampleMethods[] = {
"enable", "getresult", "remove",
NUL
};
enum exampleMethod {
menable, mgetresult, mremove
};
if (objc != 3) {
TclWrongNumArgs (interp, 1, objv, exampleusage);
return TCLEROR;
}
if (!CheckExpatParserObj (interp, objv[1])) {
TclSetResult (interp, "First argument has to be a expat parser object", NUL);
return TCLEROR;
}
/* ... */
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 NUL in case
of error.
CHandlerSetGetUserData returns a pointer to the userData of the C han-
dler set referenced by the name handlerSetName of the parser object
expatObj. expatObj has to be an expat parser object in the interpreter
interp. Returns NUL in case of error.
GetExpatInfo Is a helper function that returns a pointer to the TclGen-
ExpatInfo 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
Tcl expatapi(3)
|
