Skip Headers

Oracle® XML API Reference 10g Release 1 (10.1) Part No. B10789-01 |
| Contents

## 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

See Also: XML_ACCESS_OPEN_F, XML_ACCESS_READ_F

### 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

See Also: XML_ACCESS_CLOSE_F, XML_ACCESS_READ_F

### 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

See Also: XML_ACCESS_OPEN_F, XML_ACCESS_CLOSE_F

### 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

See Also: XmlCreate in Chapter 9, " Package XML APIs for C"

### 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

See Also: XML_STREAM_OPEN_F, XML_STREAM_READ_F, XML_STREAM_WRITE_F

### 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

See Also: XML_STREAM_CLOSE_F, XML_STREAM_READ_F, XML_STREAM_WRITE_F

### 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

See Also: XML_STREAM_OPEN_F, XML_STREAM_CLOSE_F, XML_STREAM_WRITE_F

### 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

See Also: XML_STREAM_OPEN_F, XML_STREAM_CLOSE_F, XML_STREAM_READ_F