MIDI Mapper Stream Handler

The MIDI Mapper Stream Handler is used to map MIDI data. This stream handler does not interface with an audio device driver directly but is basically a "filter" stream handler that filters the MIDI data. The Audio Stream Handler is used to interface to the audio device drivers.

This module is implemented as an OS/2 DLL running at ring 3.

Flushing a Filter Stream Group

A filter stream group requires some extra steps to properly erase its contents. Stop flushes must be sent separately to each stream. An example stream group of one master stream connected through a filter handler to a slave stream would need a stop flush sent first to the master stream. When the master stop event is received, the second stop flush must then be sent to the slave stream. Refer to the SHC_STOP command message in the OS/2 Multimedia Programming Reference.

Application and Media Driver Capabilities

For optimum performance, each application and media driver should have the following capabilities:

SEEK

Seeks the source stream and then the target streams. (The stream time will not be correct if you use another other method.)
STOP DISCARD
Stops the target streams and waits for all stop events. Next, it stops the source stream and waits for the event. If a stream is at EOS, an error stream that is already stopped will be returned. Failure to wait for events on the source stream will deadlock.
STOP FLUSH
Stops the source stream and waits for the stop event. Next, it stops the target streams and waits for the stop events. Failure to wait for events on the source stream will cause deadlock.
STOP PAUSE
Always pauses all streams at the same time. Pausing one stream while leaving another running can cause deadlock.
START
Starts the source stream and then starts the target streams. Small MIDI files will produce a quick EOS on the source stream. Do not attempt to START or START PREROLL a target stream without first starting the source stream. An attempt to do this will deadlock.
START PREROLL
Starts (nonpreroll) the source stream and then starts preroll target streams. If you attempt to START PREROLL all streams, you will deadlock.
DESTROY
Destroys all streams at the same time. Do not try to destroy one stream and then continue to use another stream.
CREATE and ASSOCIATE
All streams must be created and associated before any streams can accept commands. Do not attempt to add another stream later on.

External Interface Description

The description for the MIDI Mapper Stream Handler external interface follows:

File Name

MISH.DLL
Handler Name
MISH
Handler Class
MIDISYS
PDD/DLL
DLL
Source and Target
This stream handler is a filter. Therefore, it is both a source and a target stream handler at the same time. It consumes MIDI data from the source stream and produces mapped MIDI data that goes into the target stream or streams. The MIDI Mapper Stream Handler can have one source stream (the master stream).

This stream handler does not generate or receive sync pulses, but it can be included in a sync group. In fact, MIDI mapping is done by grouping the input stream (master stream) with the output streams (slave streams) to create a sync group. A stream will be created for each output port. The MIDI sync group can be started, stopped, and seeked as a group by using the "slaves" flag with each of these calls.

Device Control Blocks

The MIDI Mapper Stream Handler does not support a device control block.

Associate Control Blocks

The MIDI Mapper Stream Handler supports the following associate control blocks shown in the following figure.

  /******************************************************  * MISH - MIDI stream handler port-stream table ACB
  ******************************************************/
  #define ACBTYPE_MISH       0x0005L   /* MIDI port-stream table        */
  typedef struct _acb_MISH     /* acbmish - MIDI Assoc. Control Block   */
     {
     ULONG     ulACBLen;               /* Length of structure           */
     ULONG     ulObjType;              /* ACB_MISH                      */
     HSTREAM   hstreamDefault;         /* Default hstream to use when   */
                                       /*  mapper is turned off.        */
     ULONG     ulReserved1;
     ULONG     ulReserved2;
     ULONG     ulNumInStreams;
     HSTREAM   hstreamInMAX[_PORTS];   /* Array of Input streams        */
     ULONG     ulNumOutStreams;
     HSTREAM   hstreamOut[MAX_PORTS];  /* Array of Output streams       */
                                       /* The index into the array is   */
                                       /*  the source channel for that  */
                                       /*  stream.                      */
     } ACB_MISH;


 /******************************************************
  * MISH - MIDI stream handler SET ACB
  ******************************************************/
  #define ACBTYPE_SET       0x0006L    /* MIDI set function             */
  typedef struct _acb_set      /* acbset - Set Assoc. Control Block     */
     {
     ULONG     ulACBLen;               /* Length of structure           */
     ULONG     ulObjType;              /* ACB_SET                       */
     ULONG     ulFlag;                 /* Set flag                      */
     ULONG     ulTempo;                /* Not used.                     */
     } ACB_SET;

  /* ulFlag defines:   */
  #define MIDI_MAP_ON        0x0000L   /* turn mapping function on      */
  #define MIDI_MAP_OFF       0x0001L   /* turn mapping function off     */

Implicit Events (EVENT_IMPLICIT_TYPE) Supported

The following implicit (EVENT_IMPLICIT_TYPE) events for the MIDI Mapper Stream Handler are supported:

• EVENT_ERROR

  The ulStatus field will contain the error code. The possible error codes that can be generated and returned by this stream handler are:

  
  
  • ERROR_INVALID_BUFFER_RETURNED
    
  • ERROR_DEVICE_OVERRUN
    
  • ERROR_STREAM_STOP_PENDING

  Explicit Events Supported

  No explicit events are supported for the MIDI Mapper Stream Handler.

  Stream Handler Commands Supported

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

  • SHC_ASSOCIATE

    Possible Return Codes:

    • NO_ERROR -
      ERROR_INVALID_FUNCTION
      -
      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)
      
      SHC_CLOSE

      Possible Return Codes:

      • NO_ERROR -
        ERROR_INVALID_FUNCTION
        
        SHC_CREATE

        Possible Return Codes:

        • NO_ERROR
          
        • ERROR_INVALID_FUNCTION
          
        • ERROR_STREAM_CREATION
          
        • ERROR_INVALID_STREAM
          
        • ERROR_DEVICE_NOT_FOUND
          
        • ERROR_INVALID_BLOCK
          
        • ERROR_INVALID_SPCBKEY
          
        • ERROR_ALLOC_RESOURCES
        
        SHC_DESTROY

        Possible Return Codes:

        • NO_ERROR
          
        • ERROR_INVALID_FUNCTION
          
        • ERROR_INVALID_STREAM
        Possible Return Codes:

        • NO_ERROR
          
        • ERROR_INVALID_FUNCTION
        
        SHC_ENUMERATE_PROTOCOLS

        Possible Return Codes:

        • NO_ERROR
          
        • ERROR_INVALID_FUNCTION
          
        • ERROR_INSUFF_BUFFER
        
        SHC_GET_PROTOCOL

        Possible Return Codes:

        • NO_ERROR
          
        • ERROR_INVALID_FUNCTION
          
        • ERROR_INVALID_SPCBKEY
        
        SHC_INSTALL_PROTOCOL

        Possible Return Codes:

        • NO_ERROR
          
        • ERROR_INVALID_FUNCTION
          
        • ERROR_INVALID_SPCBKEY
          
        • ERROR_ALLOC_RESOURCES
        
        SHC_NEGOTIATE_RESULT

        Possible Return Codes:

        • NO_ERROR
          
        • ERROR_INVALID_FUNCTION
          
        • ERROR_INVALID_STREAM (invalid hstream or hid-or both-passed)
        
        SHC_SEEK

        Possible Return Codes:

        • NO_ERROR
          
        • ERROR_INVALID_FUNCTION
          
        • ERROR_STREAM_NOT_SEEKABLE
          
        • ERROR_DATA_ITEM_NOT_SEEKABLE
          
        • ERROR_INVALID_STREAM (invalid hstream or hstream and hid passed)
          
        • ERROR_NOT_SEEKABLE_BY_TIME
          
        • ERROR_STREAM_NOT_STOP
        
        SHC_START

        Possible Return Codes:

        • NO_ERROR
          
        • ERROR_INVALID_FUNCTION
          
        • ERROR_INVALID_STREAM (invalid hstream or hstream and hid passed)
          
        • ERROR_DATA_ITEM_NOT_SPECIFIED (stream must be associated)
        
        SHC_STOP

        Possible Return Codes:

        • NO_ERROR
          
        • ERROR_INVALID_FUNCTION
          
        • ERROR_INVALID_STREAM (invalid hstream or hstream and hid passed)
          
        • ERROR_STREAM_NOT_STARTED

        Base Stream Protocol Control Blocks Supported

        The MIDI Mapper Stream Handler supports the following stream protocol control blocks (SPCBs).

        • DATATYPE_MIDI

        Stream Handler Limits

        Limited by system memory.

        ---

        [Back: Audio Stream Handler]
        [Next: File System Stream Handler]