File System Stream Handler

The File System Stream Handler DLL transports data to or from file system devices (local or remote) on behalf of a real-time application. This handler is unique in that it utilizes the MMIO subsystem to interface to a very wide variety of devices, such as hard disk drives, diskette drives, CD-ROM drives, WORM drives, and so forth. These devices can be physically installed in the local system hardware, or they can be accessed across a LAN on a server machine.

In a playback scenario (for example, waveform audio from a RIFF file), the File System Stream Handler uses MMIO to perform I/O on specified data files, and then performs stream processing to maintain a continuously available supply which is then streamed to a target stream handler; for example, the Waveform Audio Stream Handler. This handler does not operate fully in a real-time mode, but it must support continuous data streaming. It also does not support synchronization mastering, because the file system devices are not real-time devices.

External Interface Description

The description for the File System Stream Handler external interface follows:

File Name
FSSH.DLL
Handler Name
FSSH
Handler Class
FILESYS
PDD/DLL
DLL
Source
This stream handler can be the source in a stream.
Target
This stream handler can be the target in a stream.

Device Control Blocks

None.

Associate Control Blocks

This handler supports type ACBTYPE_MMIO associate control blocks.

 /******************************************************  * FSSH - File System Stream Handler MMIO Object ACB
  ******************************************************/
  #define ACBTYPE_MMIO      0x0001L       /* MMIO object             */

  typedef struct _acb_mmio                /* acbmmio  - MMIO ACB     */
     {
     ULONG   ulACBLen;                    /* Length of structure     */
     ULONG   ulObjType;                   /* ACB_MMIO                */
     HMMIO   hmmio;                       /* Handle of MMIO object   */
     } ACB_MMIO;

Implicit (EVENT_IMPLICIT_TYPE) Events Supported

The following implicit (EVENT_IMPLICIT_TYPE) events for the File System Stream Handler are supported:

• EVENT_ERROR

  The error type will be set in the ulFlag field of the event control block. The three types of errors that will be reported are:

  • Temporary Error - TEMPORARY_ERROR 0x0000L

    An error occurred during streaming but the stream handler, the SSM, or both the stream handler and the SSM were able to continue streaming.

  • Recoverable Error - RECOVERABLE_ERROR 0x0001L

    An error occurred that required the stream to be stopped. The application can restart the stream if appropriate.

  • NonRecoverable Error - NONRECOVERABLE_ERROR 0x0002L

    A severe error occurred causing the stream handler to stop this stream. The stream cannot be restarted. The application must issue a call to SpiDestroyStream.

  The ulStatus field will contain the error code. No error codes are generated and returned by this stream handler.

  Also, errors from the following APIs can be returned:

  • DosGetInfoBlocks
    
  • SMHEntryPoint SMH_NOTIFY
    
  • mmioRead (If source, extended error code obtained by mmioGetLastError)
    
  • mmioWrite (If target, extended error code obtained by mmioGetLastError)

EVENT_PLAYLISTCUEPOINT

This will be generated only when this stream handler is a target and it finds a cuepoint indicator in the buffer table from the Sync/Stream Manager. The event will be reported after the data has been written to the file system using MMIO. The ulMessageParm field of the PLAYL_EVCB will be filled in with the message supplied in the playlist instruction. The mmtimeStream field will not be filled in.

Explicit Events Supported

No explicit events are supported for the File System Stream Handler.

Stream Handler Commands Supported

The following stream handler commands (SHCs) are supported. Refer to the OS/2 Multimedia Programming Reference for a description of these SHC commands and the error return codes.

• SHC_ASSOCIATE

  Note: A stream requires a file to be opened and associated to the stream before a stream can be started. Reassociating a new object without stopping the stream is not supported.

  Possible return codes:

  • ERROR_INVALID_STREAM (invalid hstream or hid-or both-passed) -
    ERROR_INVALID_OBJTYPE (only ACBTYPE_MMIO is supported)
    -
    ERROR_INVALID_BUFFER_SIZE (ulAcbLen is smaller than needed)
    -
    ERROR_STREAM_NOT_STOP (stream must be stopped to associate)
    Return codes from the following APIs are also returned:

    • DosRequestMutexSem
    
    SHC_CREATE

    Note: If the spcbkey passed does not match any of the installed protocols, the last installed stream protocol control block with DATATYPE_GENERIC will be used.

    Possible return codes:

    • ERROR_INVALID_SPCBKEY -
      ERROR_ALLOC_RESOURCES
      Return codes from the following APIs are also returned:

      • DosRequestMutexSem
        
      • DosCreateThread
      
      SHC_DESTROY

      Possible return codes:

      • ERROR_INVALID_STREAM (invalid hstream or both hstream and hid passed)
      Return codes from the following APIs are also returned:

      • DosRequestMutexSem
      
      SHC_START

      Possible return codes:

      • ERROR_INVALID_STREAM (invalid hstream or both hstream and hid passed)
        
      • ERROR_DATA_ITEM_NOT_SPECIFIED (stream must be associated before it is started).
      Return codes from the following APIs are also returned:

      • DosRequestMutexSem
      
      SHC_STOP

      Possible return codes:

      • ERROR_INVALID_STREAM (invalid hstream or both hstream and hid passed)
        
      • ERROR_STREAM_NOT_STARTED
      Return codes from the following APIs are also returned:

      • DosRequestMutexSem
        
      • DosResumeThread
        
      • DosSuspendThread
      
      SHC_SEEK

      Note: If you are adding support in the system for a new nonlinear data type, you can write a MMIO IOProc to support the MMIOM_SEEKBYTIME message. This message will be sent (mmioSendMessage) when the File System Stream Handler gets a seek by time (for information on the SpiSeekStream SPI_SEEKMMTIME parameter, refer to the OS/2 Multimedia Programming Reference.) and the SPCB indicates this is a nonlinear data type by having a 0 in the spcb.ulBytesPerUnit field, the spcb.mmtimePerUnit fields, or both fields.

      Possible return codes:

      • ERROR_INVALID_STREAM (invalid hstream or both hstream and hid passed)
        
      • ERROR_NOT_SEEKABLE_BY_TIME
        
      • ERROR_DATA_ITEM_NOT_SEEKABLE
        
      • ERROR_DATA_ITEM_NOT_SPECIFIED
        
      • ERROR_STREAM_NOT_STOP

      Return codes from the following APIs are also returned:

      • DosRequestMutexSem
        
      • mmioSeek (the extended error code from mmioGetLastError)
        
      • mmioSendMessage - MMIOM_SEEKBYTIME (the extended error code from mmioGetLastError)
      
      SHC_GET_PROTOCOL

      Possible return codes:

      • ERROR_INVALID_SPCBKEY
      Return codes from the following APIs are also returned:

      • DosRequestMutexSem
      
      SHC_INSTALL_PROTOCOL

      Note: This stream handler allows any data type and subtype to be installed.

      Possible return codes:

      • ERROR_INVALID_SPCBKEY
        
      • ERROR_ALLOC_RESOURCES
      Return codes from the following APIs are also returned:

      • DosRequestMutexSem
      
      SHC_ENUMERATE_PROTOCOLS

      Possible return codes:

      • ERROR_INSUFF_BUFFER
      Return codes from the following APIs are also returned:

      • DosRequestMutexSem
      
      SHC_NEGOTIATE_RESULT

      Possible return codes:

      • ERROR_INVALID_STREAM (invalid hstream or both hstream and hid passed)
        
      • ERROR_INVALID_FUNCTION (must only be called directly after create)
      Return codes from the following APIs are also returned:

      • DosRequestMutexSem

      Base Stream Protocol Control Blocks Data Types Supported

      The File System Stream Handler has only 1 base SPCB. It is DATATYPE_GENERIC. When a stream is created with a SPCBKEY that is not installed, this stream handler copies over the last installed SPCB of type DATATYPE_GENERIC and uses it. The data type, subtype and intkey passed are used in place of the generic values for these fields. The base generic SPCB has:

      ┌───────────────┬─────────────────────────────────────────────┐│SPCB Field     │DATATYPE_GENERIC Values                      │
      ├───────────────┼─────────────────────────────────────────────┤
      │ulBufSize      │16KB                                         │
      ├───────────────┼─────────────────────────────────────────────┤
      │ulMinBuf       │2                                            │
      ├───────────────┼─────────────────────────────────────────────┤
      │ulMaxBuf       │5                                            │
      ├───────────────┼─────────────────────────────────────────────┤
      │ulSrcStart     │1                                            │
      ├───────────────┼─────────────────────────────────────────────┤
      │ulTgtStart     │1                                            │
      ├───────────────┼─────────────────────────────────────────────┤
      │ulBufFlag      │SPCBBUF_NONCONTIGUOUS                        │
      ├───────────────┼─────────────────────────────────────────────┤
      │ulHandFlag     │SPCBHAND_NOSYNC | SPCB_PHYS_SEEK             │
      └───────────────┴─────────────────────────────────────────────┘
      

      Stream Handler Limits

      Maximum number of streams (only limited by available memory).

      ---

      [Back: MIDI Mapper Stream Handler]
      [Next: Memory Stream Handler]