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

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