2 Package Callback APIs for C

This package defines macros which declare functions (or function pointers) for XML callbacks. Callbacks are used for error-message handling, memory allocation and freeing, and stream operations.

This chapter contains the following section:

Callback Methods

See Also:

Callback Methods

Table 2-1 summarizes the methods available through the Callback interface.

Table 2-1 Summary of Callback Methods

Function	Summary
XML_ACCESS_CLOSE_F()	User-defined access method close callback.
XML_ACCESS_OPEN_F()	User-defined access method open callback.
XML_ACCESS_READ_F()	User-defined access method read callback.
XML_ALLOC_F()	Low-level memory allocation.
XML_ERRMSG_F()	Handles error message.
XML_FREE_F()	Low-level memory freeing.
XML_STREAM_CLOSE_F()	User-defined stream close callback.
XML_STREAM_OPEN_F()	User-defined stream open callback.
XML_STREAM_READ_F()	User-defined stream read callback.
XML_STREAM_WRITE_F()	User-defined stream write callback.

XML_ACCESS_CLOSE_F()

This macro defines a prototype for the close function callback used to access a URL.

Syntax

#define XML_ACCESS_CLOSE_F(func, ctx, uh)
xmlerr func(
   void *ctx,
    xmlurlhdl *uh);

Parameter	In/Out	Description
ctx	IN	user-defined context
uh	IN	URL handle(s)

Returns

(xmlerr) numeric error code, 0 on success

XML_ACCESS_OPEN_F()

This macro defines a prototype for the open function callback used to access a URL.

Syntax

#define XML_ACCESS_OPEN_F(func, ctx, uri, parts, length, uh)
xmlerr func(
   void *ctx,
   oratext *uri, 
   xmlurlpart *parts,
   ubig_ora *length, 
   xmlurlhdl *uh);

Parameter	In/Out	Description
ctx	IN	user-defined context
uri	IN	URI to be opened
parts	IN	URI broken into components
length	OUT	total length of input data if known, `0` otherwise
uh	IN	URL handle(s)

Returns

(xmlerr) numeric error code, 0 on success

XML_ACCESS_READ_F()

This macro defines a prototype for the read function callback used to access a URL.

Syntax

#define XML_ACCESS_READ_F(func, ctx, uh, data, nraw, eoi)
xmlerr func(
   void *ctx, 
   xmlurlhdl *uh, 
   oratext **data, 
   ubig_ora *nraw,
   ub1 *eoi);

Parameter	In/Out	Description
ctx	IN	user-defined context
uh	IN	URL handle(s)
data	IN/OUT	recipient data buffer; reset to start of data
nraw	OUT	number of real data bytes read
eoi	OUT	signal to end of information; last chunk

Returns

(xmlerr) numeric error code, 0 on success

XML_ALLOC_F()

This macro defines a prototype for the low-level memory alloc function provided by the user. If no allocator is provided, malloc is used. Memory should not be zeroed by this function. Matches XML_FREE_F().

Syntax

#define XML_ALLOC_F(func, mctx, size)
void *func(
   void *mctx,
   size_t size);

Parameter	In/Out	Description
mctx	IN	low-level memory context
size	IN	number of bytes to allocated

Returns

(void *) allocated memory

See Also:

XML_FREE_F()

XML_ERRMSG_F()

This macro defines a prototype for the error message handling function. If no error message callback is provided at XML initialization time, errors will be printed to stderr. If a handler is provided, it will be invoked instead of printing to stderr.

Syntax

#define XML_ERRMSG_F(func, ectx, msg, err)
void func(
   void *ectx,
   oratext *msg,
   xmlerr err);

Parameter	In/Out	Description
ectx	IN	error message context
msg	IN	text of error message
err	IN	numeric error code

XML_FREE_F()

This macro defines a prototype for the low-level memory free function provided by the user. If no allocator is provided, free() is used. Matches XML_ALLOC_F().

Syntax

#define XML_FREE_F(func, mctx, ptr)
void func(
   void *mctx,
   void *ptr);

Parameter	In/Out	Description
mctx	IN	low-level memory context
ptr	IN	memory to be freed

XML_STREAM_CLOSE_F()

This macro defines a prototype for the close function callback, called to close an open source and free its resources.

Syntax

#define XML_STREAM_CLOSE_F(func, xctx, sctx)
void func(
   xmlctx *xctx,
   void *sctx);

Parameter	In/Out	Description
xctx	IN	XML context
sctx	IN	user-defined stream context

XML_STREAM_OPEN_F()

This macro defines a prototype for the open function callback, which is called once to open the input source. This function should return XMLERR_OK on success.

Syntax

#define XML_STREAM_OPEN_F(func, xctx, sctx, path, parts, length)
xmlerr func(
   xmlctx *xctx,
   void *sctx,
   oratext *path,
   void *parts,
   ubig_ora *length);

Parameter	In/Out	Description
xctx	IN	XML context
sctx	IN	user-defined stream context
path	IN	full path of the URI to be opened
parts	IN	URI broken down into components (opaque pointer)
length	(OUT)	total length of input data if known, `0` if not known

Returns

(xmlerr) numeric error code, 0 on success

XML_STREAM_READ_F()

This macro defines a prototype for the read function callback, called to read data from an open source into a buffer, returning the number of bytes read (< 0 on error). The eoi flag determines if this is the final block of data.

On EOI, the close function will be called automatically.

Syntax

#define XML_STREAM_READ_F(func, xctx, sctx, path, dest, size, nraw, eoi)
xmlerr func(
   xmlctx *xctx,
   void *sctx,
   oratext *path,
   oratext *dest,
   size_t size,
   sbig_ora *nraw,
   boolean *eoi);

Parameter	In/Out	Description
xctx	IN	XML context
sctx	IN	user-defined stream context
path	IN	full URI of the open source (for error messages)
dest	(OUT)	destination buffer to read data into
size	IN	size of destination buffer
nraw	(OUT)	number of bytes read
eoi	(OUT)	signal to end of information; last chunk

Returns

(xmlerr) numeric error code, 0 on success

XML_STREAM_WRITE_F()

This macro defines a prototype for the write function callback, called to write data to a user-defined stream.

Syntax

#define XML_STREAM_WRITE_F(func, xctx, sctx, path, src, size)
xmlerr func(
   xmlctx *xctx,
   void *sctx,
   oratext *path,
   oratext *src,
   size_t size);

Parameter	In/Out	Description
xctx	IN	XML context
sctx	IN	user-defined stream context
path	IN	full URI of the open source (for error messages)
src	IN	source buffer to read data from
size	IN	size of source in bytes

Returns

(xmlerr) numeric error code, 0 on success