Returns a handle to the newly created stream object upon success, or NULL_HANDLE on failure. Call the osGetLastError function to retrieve extended error information.

This function creates a stream object.

Stream objects are utilized to read, write, and manage continuous streams of binary data.

During stream creation, an optional name may be assigned to the object, allowing tasks to access it via the osOpenStream function. When a stream is no longer required, its handle should be closed using osCloseHandle. The stream object is deleted only after it has been closed by all tasks that held an open handle. For further details, refer to the System Objects Management section.

If no osOpen* functions are utilized within the application, the system ignores object names and excludes the name management logic to reduce the final executable size. For more information regarding object naming and opening, see the System Objects Management section.

Variable-length data segments can be read from or written to the stream buffer using the osRead and osWrite system functions. Data is processed byte-by-byte in the exact order it was written.

Synchronization for stream access is implemented in three ways: via a mutex, an auto-reset event, or by disabling interrupts during the data copy operation. The latter method is suitable only when small portions of data are transferred. The synchronization method is selected during creation using the OS_IPC_PROTECT_MUTEX, OS_IPC_PROTECT_EVENT, or OS_IPC_PROTECT_INT_CTRL mode flags. Mutex and event-based synchronization are available only if the OS_STREAM_PROTECT_MUTEX or OS_STREAM_PROTECT_EVENT constants are set to 1, respectively.

If a read operation is attempted on an empty buffer, or a write operation on a full buffer, the function will return an error. If only a portion of the requested data can be transferred, the operation will process the available bytes and return successfully.

A task may also block while waiting for a read or write operation to complete; the task is resumed once the transfer is finished or a specified timeout expires. This behavior is enabled by specifying the OS_IPC_WAIT_IF_EMPTY and OS_IPC_WAIT_IF_FULL mode flags during creation. These features require the OS_STREAM_ALLOW_WAIT_IF_EMPTY and OS_STREAM_ALLOW_WAIT_IF_FULL constants to be set to 1.

When blocking operations are enabled, data can be transferred directly between tasks without intermediate buffering. To enable this optimization, use the OS_IPC_DIRECT_READ_WRITE mode flag; this feature is available only when OS_STREAM_ALLOW_DIRECT_RW is set to 1.

This function is available only when the OS_USE_STREAM constant is set to 1.