Compact Disc-Digital Audio Stream Handler

Many CDs have CD-DA ("Redbook audio") tracks that contain digital audio. These audio tracks can be played using the built-in DAC or the data can be read into the system and streamed to an adapter with DAC hardware KB (for example, ACPA card). For the latter case, the CD-DA Stream Handler DLL is required and acts as the source 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 of the lack of real-time nature of CD devices.

This handler operates on the specific CD addresses. Most CD-DA do not have data in approximately the first 2 seconds of the CD, but some discs do. CD-DA tracks can also be placed between other data tracks on mixed-mode disks. Because of this operation, the CD-DA Stream Handler will interpret the absolute beginning of the disc as MMTIME 0. The calling program must query the disc and find where the desired CD-DA track begins and call SpiSeekStream before starting the stream. The CD Audio media control interface driver does this operation for the applications coding to the media control interface.

External Interface Description

The description for the Compact Disc-Digital Audio Stream Handler external interface follows:

File Name

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

Device Control Blocks

None.

Associate Control Blocks

This handler supports type ACBTYPE_CDDA associate control blocks.

 /******************************************************  * CDDASH - CD DA Stream Handler Object ACB
  ******************************************************/
  #define ACBTYPE_CDDA        0x0004L   /* Compact disc - digital audio */
  typedef struct _acb_CDDA        /* acbcdda - CD Assoc. Control Block  */
     {
     ULONG   ulACBLen;              /* Length of structure     */
     ULONG   ulObjType;             /* ACB_CDDA                */
     CHAR    bCDDrive;              /* CD drive letter         */
     } ACB_CDDA;

Implicit (EVENT_IMPLICIT_TYPE) Events Supported

The following implicit (EVENT_IMPLICIT_TYPE) events for the Compact Disc-Digital Audio Stream Handler are supported:

• EVENT_ERROR

  The error type will be set in the ulFlag field of the event implicit control block (EVCB). 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 Sync/Stream Manager or both the stream handler and the Sync/Stream Manager 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 can not be restarted. The application must issue an SpiDestroyStream.

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

  • None
  Also, errors from the following APIs can be returned:

  • DosGetInfoBlocks
    
  • SMHEntryPoint SMH_NOTIFY
    
  • DosDevIOCtl (from ReadLong command to CD device driver).

  Explicit Events Supported

  No explicit events are supported for the Compact Disc-Digital Audio 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 drive letter 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_CDDA 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 -
        DosOpen (for CD device).
        
        SHC_CREATE

        Note: The only data type supported is 16-bit PCM Stereo sampled at 44.1 kHz.

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

        • DosRequestMutexSem
          
        • DosResumeThread
          
        • DosSuspendThread
        
        SHC_SEEK

        Note: Keep in mind that SEEK will go to the specified address in absolute terms. The absolute address from the beginning of the disc might not be the beginning of the CD-DA music.

        Also the seekpoint is granular to the mmtimePerUnit specified in the SPCB.

        Possible return codes:

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

          
          

        • ERROR_SEEK_PAST_END
          
        • ERROR_SEEK_BEFORE_BEGINNING
        Return codes from the following APIs are also returned:

        • DosRequestMutexSem
          
        • DosDevIOCtl (DiskInfo command for Seek_End)
          
        • DosDevIOCtl (Seek command)
        
        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 Compact Disc-Digital Audio Stream Handler has only 1 base SPCB. It is DATATYPE_WAVEFORM with DataSubType WAVE_FORMAT_4S16. This SPCB has the following defaults:

        ┌────────────────────┬────────────────────────────────────────┐│SPCB Field          │DATATYPE_WAVEFORM Values                │
        ├────────────────────┼────────────────────────────────────────┤
        │ulBufSize           │48KB                                    │
        ├────────────────────┼────────────────────────────────────────┤
        │ulMinBuf            │8                                       │
        ├────────────────────┼────────────────────────────────────────┤
        │ulMaxBuf            │12                                      │
        ├────────────────────┼────────────────────────────────────────┤
        │ulSrcStart          │1                                       │
        ├────────────────────┼────────────────────────────────────────┤
        │ulTgtStart          │7                                       │
        ├────────────────────┼────────────────────────────────────────┤
        │ulBufFlag           │SPCBBUF_FIXEDBUF                        │
        ├────────────────────┼────────────────────────────────────────┤
        │ulHandFlag          │SPCBHAND_NOSYNC | SPCBHAND_PHYS_SEEK    │
        ├────────────────────┼────────────────────────────────────────┤
        │ulBytesPerUnit      │588                                     │
        ├────────────────────┼────────────────────────────────────────┤
        │mmtimePerUnit       │10                                      │
        └────────────────────┴────────────────────────────────────────┘
        

        Stream Handler Limits

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

        ---

        [Back: Memory Stream Handler]
        [Next: CD-ROM XA Stream Handler]