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