/* -*- c -*-
    Copyright (C) 2005, 2007, 2008 Rocky Bernstein <rocky@gnu.org>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

/** \file audio.h 
 *
 *  \brief The top-level header for CD audio-related libcdio
 *         calls.  These control playing of the CD-ROM through its 
 *         line-out jack.
 */
#ifndef CDIO_AUDIO_H_
#define CDIO_AUDIO_H_

#include <cdio/types.h>

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

  /*! This struct is used by the cdio_audio_read_subchannel */
  typedef struct cdio_subchannel_s 
  {
    uint8_t format;
    uint8_t audio_status;
    uint8_t address:	4;
    uint8_t control:	4;
    uint8_t track;
    uint8_t index;
    msf_t   abs_addr;
    msf_t   rel_addr;
  } cdio_subchannel_t;
  
  /*! This struct is used by cdio_audio_get_volume and cdio_audio_set_volume */
  typedef struct cdio_audio_volume_s
  {
    uint8_t level[4];
  } cdio_audio_volume_t;
  

  /*! This struct is used by the CDROMPLAYTRKIND ioctl */
  typedef struct cdio_track_index_s
  {
    uint8_t	i_start_track;	/**< start track */
    uint8_t	i_start_index;	/**< start index */
    uint8_t	i_end_track;	/**< end track */
    uint8_t	i_end_index;	/**< end index */
  } cdio_track_index_t;

  /*!
    Get volume of an audio CD.
    
    @param p_cdio the CD object to be acted upon.
    @param p_volume place to put the list of volume outputs levels

    p_volume can be NULL in which case we return only whether the driver
    has the ability to get the volume or not.

  */
  driver_return_code_t cdio_audio_get_volume (CdIo_t *p_cdio,  /*out*/
					      cdio_audio_volume_t *p_volume);

  /*! 
    Return the number of seconds (discarding frame portion) of an MSF 
  */
  uint32_t cdio_audio_get_msf_seconds(msf_t *p_msf);

  /*!
    Pause playing CD through analog output

    @param p_cdio the CD object to be acted upon.
  */
  driver_return_code_t cdio_audio_pause (CdIo_t *p_cdio);

  /*!
    Playing CD through analog output at the given MSF.

    @param p_cdio the CD object to be acted upon.
    @param p_start_msf pointer to staring MSF
    @param p_end_msf pointer to ending MSF
  */
  driver_return_code_t cdio_audio_play_msf (CdIo_t *p_cdio, 
					    /*in*/msf_t *p_start_msf,
					    /*in*/ msf_t *p_end_msf);

  /*!
    Playing CD through analog output at the desired track and index

    @param p_cdio the CD object to be acted upon.
    @param p_track_index location to start/end.
  */
  driver_return_code_t cdio_audio_play_track_index 
  ( CdIo_t *p_cdio,  cdio_track_index_t *p_track_index);

  /*!
    Get subchannel information.

    @param p_cdio the CD object to be acted upon.
    @param p_subchannel place for returned subchannel information
  */
  driver_return_code_t cdio_audio_read_subchannel (CdIo_t *p_cdio, 
						   /*out*/ cdio_subchannel_t *p_subchannel);

  /*!
    Resume playing an audio CD.
    
    @param p_cdio the CD object to be acted upon.

  */
  driver_return_code_t cdio_audio_resume (CdIo_t *p_cdio);

  /*!
    Set volume of an audio CD.
    
    @param p_cdio the CD object to be acted upon.
    @param p_volume place for returned volume-level information

  */
  driver_return_code_t cdio_audio_set_volume (CdIo_t *p_cdio, /*out*/
					      cdio_audio_volume_t *p_volume);

  /*!
    Stop playing an audio CD.
    
    @param p_cdio the CD object to be acted upon.

  */
  driver_return_code_t cdio_audio_stop (CdIo_t *p_cdio);

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* CDIO_AUDIO_H_ */