Support for stream access

To provide access to the data in your user-defined stream, you must implement the appropriate generic stream I/O functions.

The following table shows which stream I/O functions to implement for the stream characteristics that your stream supports.

Stream characteristic	Description	Stream I/O function
Stream seek position	The location within the data at which the next read or write operation begins	mi_stream_seek(), mi_stream_tell(), mi_stream_getpos(), mi_stream_setpos()
Stream length	The size of the data This length can be the size of the data when the stream is initialized or the current size of the data.	mi_stream_length()
Stream mode	Which operations are valid: read-only, read/write, or write-only	mi_stream_read(), mi_stream_write()

Tip: You do not have to implement the stream I/O functions mi_stream_get_error() and mi_stream_eof() for your user-defined stream. The implementation of these functions is generic for any stream.

Consider the following information when deciding which stream I/O functions to implement:

Implement only those stream I/O functions needed to support the selected stream mode.
If your stream is to be read-only, you need to implement the mi_stream_read() function but not the mi_stream_write() function. For a write-only stream, implement only the mi_stream_write() function. For a read/write stream, implement both mi_stream_read() and mi_stream_write().
Implement stream I/O functions that access the stream seek position only if your stream supports a seek position.
If your stream supports a seek position, you must maintain the st_pos field of the stream descriptor. You can choose whether to support one or two methods of accessing the stream seek position:
- The mi_stream_seek() function provides specification of the stream seek position through an offset and a “whence” stream position.
- The mi_stream_getpos() function provides specification of the stream seek position through an absolute position.
The mi_stream_tell() function returns the current stream seek position as its return value. This function cannot return any negative error value to indicate the cause of an error.

The mi_stream_setpos() function returns the current stream seek position as one of its parameters. This function can return an integer status value.

If your stream does not have a seek position, you do not need to write any of the following functions: mi_stream_seek(), mi_stream_tell(), mi_stream_getpos(), or mi_stream_setpos().
Implement an mi_stream_close() function to deallocate stream resources.
The type-specific implementation of mi_stream_close() must explicitly free any memory that the associated stream-open function (or any other of the generic stream I/O functions) has allocated. For information, see Release stream resources.

The following general rules apply to values that the generic stream I/O functions return:

All stream I/O functions except mi_stream_tell() must return the following values:
- On success, MI_OK
- On failure, a negative integer defined in the mistream.h header file
The mi_stream_tell() function must return the following values:
- On success, a valid pointer to the current stream seek position, an mi_int8 value
- On failure, a NULL-valued pointer