Skip Headers

Oracle® XML API Reference
10g Release 1 (10.1)
Part No. B10789-01
  Go To Table Of Contents
Contents

Previous Next  

Callback Methods

Table 3-1 summarizes the methods of available through the Callback interface.

Table 3-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
Handle 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