5 Package Orastream APIs for C

Orastream APIs support handling of of text and binary nodes that exceed 64K in an XML document.

Orastream contains the following group of interfaces:

The datatypes used by Orastream are found in Chapter 1, "Datatypes for C"; they include oracheck, oraerr, oraprop_id, oramemctx, oraprop, oraprop_t, oraprop_v, orastream, and orastreamhdl.

The error codes for the Orastream interfaces are described in Table 5-1.

Table 5-1 Orastream Error Codes

Error Code Description

ORASTREAM_ERR_NULL_POINTER

Null pointer encountered.

ORASTREAM_ERR_BAD_STREAM

Invalid stream object.

ORASTREAM_ERR_WRONG_DIRECTION

Stream object is defined for the opposite I/O direction.

ORASTREAM_ERR_UNKNOWN_PROPERTY

Unknown creation property.

ORASTREAM_ERR_NO_DIRECTION

The I/O direction of the stream is undefined.

ORASTREAM_ERR_BI_DIRECTION

The stream direction is incorrectly defined as using both I/O directions.

ORASTREAM_ERR_NOT_OPEN

The stream is not open.

ORASTREAM_ERR_WRONG_MODE

The stream is defined for the opposite char/byte mode.

ORASTREAM_ERR_CANT_OPEN

The stream cannot be opened.

ORASTREAM_ERR_CANT_CLOSE

The stream cannot be closed.


For more information on Orastream interfaces, see Oracle XML Developer's Kit Programmer's Guide.


OraStream Interfaces

These methods support unidirectional streams used to move data piecewise. The direction and mode of the stream is determined by the paramters that initialize the stream in the OraStreamInit() method.

Table 5-2 Summary of OraStream Methods; Package Orastream

Function Summary

OraStreamClose()

Closes the stream.

OraStreamHandle()

Returns the handle to the stream.

OraStreamInit()

Initializes the stream.

OraStreamIsOpen()

Determines if the stream is open.

OraStreamOpen()

Opens the stream.

OraStreamRead()

Reads bytes from the stream.

OraStreamReadable()

Determines if the stream is readable.

OraStreamReadChar()

Reads characters from the stream.

OraStreamSid()

Sets the SID of a stream.

OraStreamTerm()

Destroys the stream.

OraStreamWrite()

Writes bytes to the stream.

OraStreamWritable()

Determines if the stream is writable.

OraStreamWriteChar()

Writes characters to the stream.



OraStreamClose()

Closes the orastream object.

The function is used to close the given stream by calling the 'close' callback function of the stream.

Returns ORAERR_OK for success, or the error code for failure. See Table 5-1.

Syntax

oraerr OraStreamClose(
  orastream *stream);
Parameter In/Out Description
stream
IN
Stream that is closed


OraStreamHandle()

Returns the handle of the orastream object.

The handle contains the generic pointers and file descriptors.

Syntax

orastreamhdl *OraStreamHandle(
  orastream *stream);
Parameter In/Out Description
stream
IN
Stream whose handle is returned


OraStreamInit()

Creates and initializes a orastream object.

Syntax

orastream *OraStreamInit(
  void *sctx,
  void *sid,
  oraerr *err,
  list);
Parameter In/Out Description
sctx
IN
The input context; may be NULL
sid
IN
The user-defined stream context identifier
err
OUT
The error, if any. ORAERR_OK for success, or the error code for failure. See Table 5-1
list
IN
NULL-terminated list of name-value pairs of arguments that specify the properties of the new orastream oject. These are:
  • The open property name is for the open function, and its value follows.

    ORASTREAM_OPEN_F((*), sctx, sid, hdl, length)
    
  • The close property name is for the close function, and its value follows.

    ORASTREAM_CLOSE_F((*), sctx, sid, hdl)
    
  • The read property name is for reading byte data from the stream to the buffer. Note that nread returns the number of bytes actually read.

    ORASTREAM_READ_F((*), sctx, sid, hdl, dest,
      size, start, nread, eoi)
    
  • The write property name is for writing byte data from the buffer to the stream. Note that written returns the number of bytes actually written.

    ORASTREAM_WRITE_F((*), sctx, sid, hdl, src,
      size, written)
    
  • The read_char property name is for reading character data from the stream to the buffer. Note that nread returns the number of characters actually read.

    ORASTREAM_READ_F((*), sctx, sid, hdl, dest,
      size, start, nread, eoi)
    
  • The write_char property name is for writing character data from the buffer to the stream. Note that written returns the number of characters actually written.

    ORASTREAM_WRITE_F((*), sctx, sid, hdl, src,
      size, written)
    


OraStreamIsOpen()

Determines if the orastream is open. Returns TRUE or FALSE.

Note that the stream must be open to perform read and write operations.

Syntax

boolean OraStreamIsOpen(
  orastream *stream);
Parameter In/Out Description
stream
IN
The stream that should be open for reads or writes.


OraStreamOpen()

Opens the orastream object.

The function opens the stream by calling the 'open' callback function of the stream.

Returns ORAERR_OK for success, or the error code for failure. See Table 5-1.

Syntax

oraerr OraStreamOpen(
  orastream *stream,
  ubig_ora *length)
Parameter In/Out Description
stream
IN
The stream that is open
length
OUT
Optional parameter; not used


OraStreamRead()

Reads bytes from the orastream object.

The function is used to read the data from the stream into the specified buffer. It also returns TRUE for the eoi parameter if the end of stream is reached.

Returns ORAERR_OK for success, or the error code for failure. See Table 5-1.

Syntax

oraerr OraStreamRead(
  orastream *stream,
  oratext *dest,
  ubig_ora size,
  oratext **start,
  ubig_ora *nread,
  ub1 *eoi);
Parameter In/Out Description
stream
IN
Stream that is being read
dest
IN
The destination buffer
size
IN
The size of the data to be read
start
OUT
Pointer to the start of data being read
nread
OUT
Number of bytes actually read from the stream
eoi
OUT
Returns TRUE if end of the stream is reached; FALSE otherwise


OraStreamReadable()

Determines if an existing orastream object is readable.

Returns TRUE or FALSE.

Syntax

boolean OraStreamReadable(
  orastream *stream);
Parameter In/Out Description
stream
IN
Stream that is checked for readability


OraStreamReadChar()

Reads chars from the orastream object.

The function is used to read the data from the stream into the specified buffer. It also returns TRUE for the eoi parameter if the end of stream is reached.

Returns ORAERR_OK for success, or the error code for failure. See Table 5-1.

Syntax

oraerr OraStreamReadChar(
  orastream *stream,
  oratext *dest, 
  ubig_ora size,
  oratext **start, 
  ubig_ora *nread, 
  ub1 *eoi);
Parameter In/Out Description
stream
IN
Stream that is being read
dest
IN
The destination buffer
size
IN
The size of the data to be read
start
OUT
Pointer to the start of data being read
nread
OUT
Number of characters actually read from the stream
eoi
OUT
Returns TRUE if end of the stream is reached; FALSE otherwise


OraStreamSid()

Assigns an SID to an existing orastream object. Returns the old SID through the OUT parameter osid.

Returns ORAERR_OK for success, or the error code for failure. See Table 5-1.

Syntax

oraerr OraStreamSid(
  orastream *stream,
  void *sid,
  void **osid);
Parameter In/Out Description
stream
IN
The stream whose SID is changed
sid
IN
The new SID
osid
OUT
The previous SID of the stream


OraStreamTerm()

Destroys a orastream object and frees its associated memory.

Returns ORAERR_OK for success, or the error code for failure. See Table 5-1.

Syntax

oraerr OraStreamTerm(
  orastream *stream);
Parameter In/Out Description
stream
IN
Stream that is destroyed


OraStreamWrite()

Writes bytes to the orastream object.

The number of bytes actually read are stored by the OUT parameter nwrote.

Returns ORAERR_OK for success, or the error code for failure. See Table 5-1.

Syntax

oraerr OraStreamWrite(
  orastream *stream, 
  oratext *src, 
  ubig_ora size,
  ubig_ora *nwrote);
Parameter In/Out Description
stream
IN
Stream where the data is written
src
IN
Buffer from which the data is written
size
IN
Size of data to be written
nwrote
OUT
Number of bytes written to the stream


OraStreamWritable()

Determines if an existing orastream object is writable.

Returns TRUE or FALSE.

Syntax

boolean OraStreamWritable(
  orastream *stream);
Parameter In/Out Description
stream
IN
Stream that is checked for writability.


OraStreamWriteChar()

Writes chars to the orastream object.

The number of characters actually written are stored by the OUT parameter nwrote.

Returns ORAERR_OK for success, or the error code for failure. See Table 5-1.

Syntax

oraerr OraStreamWriteChar(
  orastream *stream, 
  oratext *src, 
  ubig_ora size,
  ubig_ora *nwrote);
Parameter In/Out Description
stream
IN
Stream where the data is written
src
IN
Buffer from which the data is written
size
IN
Size of data to be written
nwrote
OUT
Number of characters written to the stream