2 Package Callback APIs for C

Callback Methods

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

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);

ctx

IN

uh

IN

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);

ctx

IN

uri

IN

parts

IN

length

OUT

uh

IN

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);

ctx

IN

uh

IN

data

IN/OUT

nraw

OUT

eoi

OUT

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);

mctx

IN

size

IN

Returns

(void *) allocated memory

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);

ectx

IN

msg

IN

err

IN

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);

mctx

IN

ptr

IN

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);

xctx

IN

sctx

IN

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);

xctx

IN

sctx

IN

path

IN

parts

IN

length

(OUT)

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);

xctx

IN

sctx

IN

path

IN

dest

(OUT)

size

IN

nraw

(OUT)

eoi

(OUT)

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);

xctx

IN

sctx

IN

path

IN

src

IN

size

IN

Returns

(xmlerr) numeric error code, 0 on success