The mi_stream_init() function
The mi_stream_init() function initializes a user-defined stream.
Syntax
MI_STREAM *mi_stream_init(strm_ops, strm_data, strm_desc)
struct stream_operations *strm_ops;
void *strm_data;
MI_STREAM *strm_desc;- strm_ops
- The structure that holds the function pointers for the stream I/O functions.
- strm_data
- A pointer to the stream data.
- strm_desc
- A pointer to a stream descriptor. This MI_STREAM pointer can be a NULL-valued pointer if the stream has not been previously allocated.
| Valid in client LIBMI application? | Valid in user-defined routine? |
|---|---|
| No | Yes |
Usage
The mi_stream_init() function returns a pointer to the initialized stream, based on the stream I/O functions in the stream-operations structure that strm_ops references, and data, which strm_data references. Use this function to implement a user-defined stream class. Do not call mi_stream_init() on a predefined stream.
The third argument to mi_stream_init() is an uninterpreted data pointer that is stored in the MI_STREAM structure initialized by the call to mi_stream_init(). The stream interface does not interpret this pointer, which is for the benefit of the stream implementor.
To initialize a new stream,
the function takes the following steps:
- Determines whether to allocate a new stream descriptor
- If the strm_desc argument is a NULL-valued pointer, mi_stream_init() allocates a new stream.
- If the strm_desc argument references a valid stream, mi_stream_init() does not allocate the stream again.
- If the strm_desc argument points to valid memory, uses
the passed memory for the MI_STREAM structure descriptor
The function does not allocate the stream structure again.
- Returns a pointer to the new stream descriptor
Return values
- An MI_STREAM pointer
- A pointer to a newly allocated stream.
- NULL
- The function was not successful.