osCreateStream function
Declaration:
HANDLE osCreateStream(
  SYSNAME Name,
  UINT8 Mode,
  SIZE BufferSize
);
Parameters:
Name

Name of the object (may be NULL).

Mode

Mode flags (see the description section below).

BufferSize

Stream data buffer size. It may be set to zero, when direct read-write is enabled (see the description section below).

Return value:

The return value is a handle to the created stream object when success or NULL_HANDLE on failure. Use osGetLastError function to obtain extended error information.

Description:

Function creates a stream object.

Stream objects are used to read, write, and manage a stream of binary data.

During stream creation, an optional stream name may be specified. It makes tasks able to open it by osOpenStream function. The non-used stream should be closed with the osCloseHandle. Stream will be deleted when it is closed by all tasks that opened it. More information you can find in the system objects managementsection.

If all of the osOpen* functions are not used, the system ignores an object name and the code used to name management will be removed. It will reduce final size of the output code. For more information about the names and object opening see the system objects managementsection.

A variable number of data bytes can be read or written from this buffer and it is performed by two system functions i.e. osRead and osWrite. The data are put on the stream byte per byte and read from it in order they were put.

Access to stream synchronization is realized in three ways. It may be protected by mutex, auto-reset event, or by interrupt disabling for data copy time. The last way can be realized only when small portions of data are transferred to or from a stream. The way of synchronization is chosen during stream creation by using OS_IPC_PROTECT_MUTEX, OS_IPC_PROTECT_EVENT or OS_IPC_PROTECT_INT_CTRL mode flag. Synchronization mode by mutex or auto-reset event is available only when corresponding constant OS_STREAM_PROTECT_MUTEX and OS_STREAM_PROTECT_EVENT are set to 1.

When read operation is performed on the stream with an empty buffer, or write operation when the buffer is full, the operation will be finished with an error. If only part of data is transferred to or from buffer, the operation will be performed only for the available number of bytes and just after it will be finished with success.

The task may also be waiting for a completion of read or write operation and it is resumed when all data will be successfully transferred, or specified timeout interval elapses. It is realized by specifying the appropriate mode flags OS_IPC_WAIT_IF_EMPTY and OS_IPC_WAIT_IF_FULL during the stream creation. These operations are available only when the corresponding constants OS_STREAM_ALLOW_WAIT_IF_EMPTY and OS_STREAM_ALLOW_WAIT_IF_FULL are set to 1.

When the wait for operation completion is enabled, the data can be sending directly from one task to another, without storing data in the buffer. To enable this feature, it should be set OS_IPC_DIRECT_READ_WRITE mode flag and it is only available when OS_STREAM_ALLOW_DIRECT_RW is set to 1.

Function is available only, when the value of OS_USE_STREAM constant is set to 1.

SpaceShadow documentation