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:
Table 2-1 summarizes the methods of 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. |
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
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
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
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
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 |
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 |
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 |
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
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
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