Stream Protocols

The Stream Protocol Control Block (SPCB) defines key parameters that control the behavior of a data stream. The application can query, install, or deinstall a specific SPCB from a stream handler. SPCB information is installed in the SPI.INI file by means of a resource file. (See Installing a Stream Handler for a description of how to install stream protocol.)

Each stream handler supports one or more stream protocols. Each SPCB is uniquely identified by the value of the stream data type (SPCB key). One field in the SPCB key allows the stream handler to have multiple SPCBs installed for the same data type. This field can be used by an application to specify which SPCB, for any data type, it wants to use. Each application in the system could define multiple SPCBs for the same data type (see the ulType field in the SPCBKEY data structure). The application can modify a stream protocol by installing a new SPCB and deinstalling the old SPCB.

The parameters in the SPCB are:

Fields

Meaning
SPCB Length
Length of SPCB structure. Provided for future expansion of the SPCB.
SPCB Key
Data stream type and internal key. The internal key is used to differentiate between multiple SPCB's of the same data stream type.

• Data Type - The data type of the stream (for example, waveform or MIDI).
  
• Data Subtype - The subtype of the stream (for example, 16-bit stereo PCM).
  
• Internal Key - Used to differentiate between multiple SPCB's of the same data type and subtype.
Data Flag
Attributes of the data type. (that is, specifies whether data or time cuepoints are supported by this data type).

• SPCBDATA_CUETIME - This data type can support time cuepoint events.
  
• SPCBDATA_CUEDATA - This data type can support data cuepoint events.
  
• SPCBDATA_NOSEEK - Seeking cannot be done on this data type.
Number of Records
Maximum number of records per buffer. (This is only valid for split streams).
Data Block Size
Size of a block. A block is an atomic piece of data. For example, for digital audio data type PCM 16-bit stereo at a 44.1 kHz sampling rate, the block size would be 4 bytes.
Data Buffer Size
Size of buffer to be used while streaming. Maximum buffer size is 64KB.
Min Number of Buffers
Minimum number of buffers needed to maintain a constant data stream.
Max Number of Buffers
Maximum number of buffers needed (ideal number). For normal streams, this means the number of buffers that will be allocated for the stream. For user provided buffer streaming, this means the number of buffers that the Sync/Stream Manager can queue up for a consumer. This can be used by a source stream handler that gives the same set of buffers to the Sync/Stream Manager repeatedly. If the number of buffers is set to the number of buffers in the set minus one, the source stream handler will be able to detect when the target has consumed a buffer and it can be reused. Assuming that the set of buffers is an ordered set and each buffer is used in the same order each time.
Source Start Number
Number of EMPTY buffers required to start the source stream handler. The value should be at least as big as the maximum number of buffers that would be requested by the source stream handler.
Target Start Number
Number of FULL buffers required to start the target stream handler. The value should be at least as big as the maximum number of buffers that would be requested by the target stream handler. Usually, a target will require at least two buffers at the start of the stream.
Buffer Flag
Buffer attributes (that is, the user provides buffers, fixed block size, interleaved data type, and maximum buffer size).

• SPCBBUF_USERPROVIDED - User provides buffers for streaming. The Sync/Stream Manager will not allocate buffers, but attempt to lock down user provided buffers or copy the data to locked buffers. Using this flag will affect the performance of streaming. Only a source stream handler can set this flag. This flag is mutually exclusive with the SPCBBUF_INTERLEAVEDflag .TheSPCBBUF _ FIXEDBUFcannotbeusedwiththisflagset .
  
• SPCBBUF_FIXEDBUF - The buffer size for this stream handler must be a particular fixed size (for this data type). This flag cannot be used with the SPCBBUF_USERPROVIDED flag. The SPCBBUF_INTERLEAVED flag (split stream) implies SPCBBUF_FIXEDBUF.
  
• SPCBBUF_NONCONTIGUOUS - Each data buffer is allocated contiguously in physical memory unless both stream handlers set the non-contiguous flag (SPCBBUF_NONCONTIGUOUS). This flag allows the system flexibility in allocating memory. A device driver stream handler may require contiguous memory, while a DLL stream handler may not.
  
• SPCBBUF_INTERLEAVED - This stream is a split stream. It consists of one input stream of interleaved data that is split into multiple streams of individual data types. Only the source stream handler can set this flag. This flag is mutually exclusive with the SPCBBUF_USERPROVIDED flag. The SPCBBUF_FIXEDBUF cannot be used with this flag set.
  
• SPCBBUF_MAXSIZE - The ulBufSize field contains that maximum size buffer that this stream handler can handle.
  
• SPCBBUF_16MEG - The stream buffers may be allocated above 16MB. This is used by stream handlers device drivers that can support greater than 16MB addresses.
Handler Flag
Stream handler flags (that is, the handler can generate and receive sync pulses, and use the Sync/Stream Manager timer as the master, non-streaming handler).

• SPCBHAND_GENSYNC - This stream handler can generate sync pulses.
  
• SPCBHAND_RCVSYNC - This stream handler can receive sync pulses.
  
• SPCBHAND_NONSTREAM - This stream handler is a non-streaming handler (that is, a stream handler that can participate in synchronization, but does not stream).
  
• SPCBHAND_GENTIME - This stream handler can keep track of the real stream time. This handler also supports the SpiGetTime and cuepoint events.
  
• SPCBHAND_NOPREROLL - This stream handler cannot preroll its device (that is, for recording streams, the source stream handler cannot be prerolled). The Sync/Stream Manager will treat this stream as if it were prerolled if asked to preroll this stream.
  
• SPCBHAND_NOSYNC - This stream handler can be in a sync group but does not receive or generate sync pulses. (It is useful to group streams together so that they can be manipulated as a group).
  
• SPCBHAND_PHYS_SEEK - This stream handler does a seek to a physical device. Other stream handlers only adjust stream time on a seek request. The Sync/Stream Manager will always call this stream handler first on a call to the SpiSeekStream function.
Resync Tolerance
Resync tolerance value. It is used to determine whether to send a sync pulse to this specific slave stream handler, if it is a slave.
Sync Pulse Granularity
Time interval in MMTIME units between sync pulses. Used to save sync pulse generation granularity if this stream handler is a master, but cannot generate its own sync pulse.
Bytes Per Unit
Bytes per unit of time. This is used to do seeks on linear data that is not compressed or of variable length. It is also used for SHC_GETTIME queries in a stream handler.
MMTIME Per Unit
The amount of MMTIME each unit represents. This is also used for the seek and "get time" functions of a stream handler.

Refer to the OS/2 Multimedia Programming Reference for further information on structure and flag definitions.

---

[Back: Null Stream Handler]
[Next: Stream Protocol Negotiation at Stream Creation Time]