CDaddcallback(3dm)

NAME
     CDaddcallback - set a callback for the CD audio data parser

SYNOPSIS
     #include <sys/types.h>
     #include <dmedia/cdaudio.h>

     void CDaddcallback(CDPARSER* cdp, CDDATATYPES type,
                    CDCALLBACKFUNC func, void* arg)

PARAMETERS
     cdp    A pointer to the target CDPARSER.

     type   The type of callback being set.  CDDATATYPES is an enumerated type
            defined in cdaudio.h containing the following values:  cd_audio,
            cd_pnum, cd_index, cd_ptime, cd_atime, cd_catalog, cd_ident,
            cd_control.

     func   A pointer to the function to be called.

     arg    A user supplied argument that is passed to the callback function.

DESCRIPTION
     CDaddcallback(3dm) adds a callback for the specified parser.  The parser
     has callbacks for eight different types of data in the digital audio data
     stream corresponding to the enumerated types listed above.  When data of
     a particular type changes in the data stream from the disc, the parser
     invokes the corresponding callback passing it a pointer to the data.  The
     cd_audio callback is an exception to this.  It is called for every
     recorded frame regardless of whether the data changed.

     The callback is called as follows

              func(void* arg, CDDATATYPES type, void* data);


     arg is the user supplied argument provided as the fourth parameter to
     CDaddcallback(3dm). type is the particular type of callback.  It is
     passed so that a single function could be used for all eight callbacks.
     data is the data returned for this type of callback.  The argument is
     cast to void*.  Each type of callback returns a different kind of data.
     An explanation of the callback types and data structures passed to them
     is given below.  See cdframe(4) for a detailed description of each type
     of data in the digital audio data stream.

   cd_audio
     This is the audio data.  The data argument in this case is really a
     short* pointing at an array containing the byte-swapped and, if
     necessary, de-emphasized audio data ready to hand to ALwritesamps(3dm).
     If you use this callback you will want to change the handling of floating
     point underflow exceptions to achieve acceptable performance.  Put the
     following lines of code in your program:
              #include <sigfpe.h>

              sigfpe_[_UNDERFL].repls = _ZERO;
              handle_sigfpes(_ON, _EN_UNDERFL, NULL, _ABORT_ON_ERROR, NULL);


     See CDintro(3dm) for a complete explanation.

   cd_pnum
     This is the number of the current program (aka track).  The data type in
     this case is a pointer to a struct cdprognum defined in cdaudio.h as
     follows:

              typedef struct cdprognum {
                  int value;                  /* Program converted to integer */
                  struct cdpackedbcd bcd;     /* Program in BCD digits */
              } CDPROGNUM;


     Program number AA (program number not currently valid) is represented in
     the converted value by 0xaaa.  Program number BB (lead-in) is represented
     by 0xbbb and program number EE (lead-out) is represented by 0xeee.

   cd_index
     This is the index number of the current subdivision within the program.
     The data type in this case is a pointer to a struct cdprognum as
     described above.

   cd_ptime
     This is the time into the current program.  The data type is a pointer to
     a struct cdtimecode defined in cdaudio.h as follows:

              struct cdtimecode {
                  unchar mhi:4, mlo:4;
                  unchar shi:4, slo:4;
                  unchar fhi:4, flo:4;
              } ptime;


   cd_atime
     This is the time since the start of the disc (absolute time).  The data
     type is a pointer to a struct cdtimecode as described above.

   cd_catalog
     This is the catalog number of the CD.  The data type is a char* pointing
     to an array of 13 bytes.  Each byte contains 1 BCD digit in its least
     significant nibble.

   cd_ident
     This is the ISRC identification number of the recording.  The data type
     is a pointer to a struct cdident defined in cdaudio.h as follows:

              struct cdident {
                  unchar country[2];
                  unchar owner[3];
                  unchar year[2];
                  unchar serial[5];
              } ident;


     country and owner are encoded in the six-bit code converted by
     CDsbtoa(3dm). year and serial are BCD digits.

   cd_control
     This is for the control bits from the CD subcode data.  The data type is
     unchar* pointing at a single byte.  The bits in this byte include copy
     protect and preemphasis on or off.

SEE ALSO
     Cdintro(3dm), CDseekblock(3dm), CDseektrack(3dm), CDclose(3dm),
     CDcreateparser(3dm), CDopen(3dm), CDparseframe(3dm), CDreadda(3dm),
     CDseek(3dm), CDremovecallback(3dm), CDresetparser(3dm), cdframe(4),
     sigfpe(3C)

AUTHOR
     Roger Chickering, Mark Callow