Memory Stream Handler

There are many multimedia application scenarios where data streaming might be performed to or from system memory. For example, an application can create a waveform data object dynamically, allocating application data buffers in which to store the waveform data. This data is not read from a device but is generated by an application algorithm. This waveform data can then be streamed to the Waveform Audio Stream Handler (target).

Another example where system memory is used for streaming is when the application must process or convert data read from a file before it can be used as the source of a stream. There can be some cases where application-unique data compression is used. In these cases, the application can stream data from a "flat file" into an application buffer. Then, after decompression (or other operation) this data in system memory can be streamed using the Memory Stream Handler as the source, perhaps sending the data to the Waveform Audio Stream Handler.

The Memory Stream Handler does not support synchronization.

Memory playlists are used to specify the memory addresses to play from or record into.

External Interface Description

The description for the Memory Stream Handler external interface follows:

File Name

MEMSH.DLL
Handler Name
MEMSH
Handler Class
MEMSYS
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_MEM_PLAYL associate control blocks.

/******************************************************
 * MEMSH - Memory Stream Handler Playlist Object ACB
 ******************************************************/
#define ACBTYPE_MEM_PLAYL     0x0003L  /* Memory playlist object     */

typedef struct _acb_mem_playl
   {
   ULONG   ulACBLen;              /* Length of structure             */
   ULONG   ulObjType;             /* ACBTYPE_MEM_PLAYL               */
   PVOID   pMemoryAddr;           /* Starting address of playlist    */
   } ACB_MEM_PLAYL;

Implicit (EVENT_IMPLICIT_TYPE) Events Supported

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

• EVENT_ERROR

  The error type will be set in the ulFlag field of the event implicit control block (EVCB). These error types and the flag values are described in the file system stream handler section.

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

  • ERROR_PLAYLIST_STACK_OVERFLOW (too many CALL instructions encountered. The maximum CALL depth is 20 calls.)
    
  • ERROR_PLAYLIST_STACK_UNDERFLOW (too many RETURN instructions encountered. There should be exactly one RETURN instruction executed for each CALL instruction.)
    
  • ERROR_INVALID_FUNCTION (invalid playlist opcode encountered.)
    
  • ERROR_INVALID_BLOCK (playlist is not read/write accessible or data is not read (play) or write (record) accessible.)
    
  • ERROR_END_OF_PLAYLIST (when recording into a playlist, the EXIT opcode was encountered before EOS. The stream handler stops).
  Also, errors from the following APIs can be returned:

  • DosGetInfoBlocks
    
  • DosQueryMem
    
  • SMHEntryPoint SMH_NOTIFY (GiveBuf function for Play)
    
  • SMHEntryPoint SMH_NOTIFY (GetFull, ReturnEmpty for Record)
    
  • SMHEntryPoint SMH_REPORTEVENT
  
  EVENT_PLAYLISTCUEPOINT

  The Memory Stream Handler does not receive playlist cuepoint indicators within the stream. This handler will place a cuepoint indicator into a stream when it interprets a CUEPOINT playlist operation. Therefore this stream handler does not generate the EVENT_PLAYLISTCUEPOINT, but it enables it in the stream for the target stream handler. Check the description of the target stream handler to determine if it supports this EVENT_PLAYLISTCUEPOINT.

  
  EVENT_PLAYLISTMESSAGE

  This is generated when a MESSAGE instruction is encountered. The ulMessageParm field of the PLAYL_EVCB will be filled in with the message supplied in the message parameter (operand2) of the playlist MESSAGE instruction. The ulStatus field contains the playlist instruction number.

  Explicit Events Supported

  No explicit events are supported for the Memory 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

    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 hstream and hid passed) -
      ERROR_INVALID_OBJTYPE (only ACBTYPE_MEM_PLAYL is supported)
      -
      ERROR_INVALID_BUFFER_SIZE (ulAcbLen is smaller than needed)
      -
      ERROR_STREAM_NOT_STOP (stream must be stopped to associate)
      -
      ERROR_INVALID_BLOCK (invalid memory address - not read/write accessible)
      Return codes from the following APIs are also returned:

      • DosRequestMutexSem -
        DosQueryMem
      
      SHC_CREATE

      Note: If the SPCBKEY passed does not match any of the installed protocols, the last installed SPCB with DATATYPE_GENERIC will be used. If the MEMSH is the source, create will always set the SPCBBUF_USERPROVIDED flag in the spcb.ulBufFlag field.

      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 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 hid-or both-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 hid-or both-passed)
        
      • ERROR_STREAM_NOT_STARTED
      Return codes from the following APIs are also returned:

      • DosRequestMutexSem
        
      • DosResumeThread
        
      • DosSuspendThread
      
      SHC_SEEK

      Note: Seeking backward is not supported. SEEK_END is only supported if the lSeekPoint is 0. A playlist seek is accomplished by going back to the beginning of the playlist and executing each instruction without playing the data, but counting the time it takes. The Seek operates on the current playlist, that means that if the playlist was modified by the application the Seek uses the modified playlist to calculate the seek position. When a seek absolute is performed all LOOP iterations are reset to 0 before the Seek starts calculating the position.

      Possible return codes:

      • ERROR_INVALID_STREAM (invalid hstream or hid-or both-passed)
        
      • ERROR_NOT_SEEKABLE_BY_TIME
        
      • ERROR_DATA_ITEM_NOT_SEEKABLE
        
      • ERROR_STREAM_NOT_STOP
        
      • ERROR_SEEK_BACK_NOT_SUPPORTED
        
      • ERROR_SEEK_PAST_END
        
      • ERROR_INVALID_BLOCK
        
      • ERROR_PLAYLIST_STACK_OVERFLOW
        
      • ERROR_PLAYLIST_STACK_UNDERFLOW
        
      • ERROR_INVALID_FUNCTION
        
      • ERROR_DATA_ITEM_NOT_SPECIFIED
      Return codes from the following APIs are also returned:

      • DosRequestMutexSem
        
      • DosQueryMem
      
      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 hid-or both-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 Block Data Types Supported

      The Memory Stream Handler has only 1 base stream protocol control block (SPCB). It is DATATYPE_GENERIC. When a stream is created with a SPCBKEY that is not one 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       │3                                            │
      ├───────────────┼─────────────────────────────────────────────┤
      │ulMaxBuf       │10                                           │
      ├───────────────┼─────────────────────────────────────────────┤
      │ulSrcStart     │1                                            │
      ├───────────────┼─────────────────────────────────────────────┤
      │ulTgtStart     │1                                            │
      ├───────────────┼─────────────────────────────────────────────┤
      │ulBufFlag      │SPCBBUF_NONCONTIGUOUS                        │
      ├───────────────┼─────────────────────────────────────────────┤
      │ulHandFlag     │SPCBHAND_NOSYNC | SPCBHAND_PHYS_SEEK         │
      └───────────────┴─────────────────────────────────────────────┘
      

      Stream Handler Limits

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

      ---

      [Back: File System Stream Handler]
      [Next: Compact Disc-Digital Audio Stream Handler]