// Programación en C++ para Ingenieros, Ed. Thomson Paraninfo, 2006
// Apéndice B: La Biblioteca CDAudioLib

// Fichero cdaudio.h
// API CDAudioLib

#ifndef _CDAUDIO_H
#define _CDAUDIO_H

// Funciones de apertura e inicialización del CD de Audio.
// Todas estas funciones son síncronas.

   // Función para la apertura del dispositivo CD de Audio.
   // Devuelve un valor booleano que indica si se ha
   // producido algún error en el proceso de apertura.
   // Si el dispositivo ya estaba abierto no se produce
   // error. Si no se ejecuta esta función antes de utilizar
   // el dispositivo, el comportamiento del resto de funciones
   // no será correcto.
   bool OpenCDAudio();

// Funciones para el cierre del CD de Audio.
// Todas estas funciones son síncronas.

   // Función que para el CD de Audio si está en play
   // y cierra el dispositivo CD de Audio.
   // Devuelve un valor booleano que indica si se ha
   // producido algún error al cerrar el dispositivo.
   bool CloseCDAudio();

// Funciones de consulta del estado del CD de Audio.
// Todas estas funciones son síncronas.

   // Función que indica si el dispositivo está abierto.
   bool IsOpen();

   // Función que indica si el dispositivo está preparado.
   // Como el cd de audio es un dispositivo de carga automática
   // siempre devuelve cierto, pero si no se ha abierto el
   // el comportamiento de las funciones no será correcto.
   bool IsReady();

   // Función que indica si el CD de Audio está en modo play.
   bool IsPlaying();

   // Función que indica si el CD de Audio está parado.
   bool IsStopped();

   // Función que indica si el CD de Audio está en pausa.
   bool IsPaused();

// Funciones de solicitud de Información del CD de Audio.
// Todas estas funciones son síncronas.

   // Función que informa si hay un CD de Audio
   // insertado en el dispositivo.
   bool EsCDMedia();

   // Función que devuelve el número de tracks que tiene
   // el CD insertado en el dispositivo.
   // En caso de que no haya un CD de Audio insertado en
   // el dispositivo devuelve un 0.
   int NumeroDeTracks();

   // Función que devuelve el número de track en el que
   // está posicionada la cabeza lectora del dispositivo.
   // En caso de que no haya un CD de Audio insertado en
   // el dispositivo devuelve un 0.
   int TrackActual();

// Funciones de peticiones de E/S síncronas.
// Todas estas funciones devuelven un booleano
// que indica si se ha producido algún error al
// procesar la petición de E/S.

   // Función que para la reproducción y resitúa
   // la cabecera del lector del CD de Audio al
   // principio del primer track del disco.
   bool Stop();

   // Función que detiene la reproducción dejando
   // el cabezal del dispositivo en la posición
   // que estaba al detenerlo.
   bool Pause();

   // Función que reinicia una reproducción después de
   // una pausa.
   bool Resume();

   // Función que abre la puerta del dispositivo y
   // expulsa el CD.
   bool OpenDoorCD();

   // Función que cierra la puerta del dispositivo.
   // No tiene ningún efecto en aquellos dispositivos
   // que no disponen de un mecanismo de cierre
   // de la puerta automático.
   bool CloseDoorCD();

   // Función que reproduce el CD de Audio desde la
   // posición donde se encuentra situado el cabezal
   // hasta el final del CD. Como es una función sincrona
   // la función no finaliza hasta que no acaba la reproducción.
   bool Play();

   // Función que reproduce el track correspondiente al
   // numTrack. Si numTrack no está dentro del rango de
   // tracks del dispositivo (entre 1 y NumeroDeTracks())
   // devuelve error. Como es una función síncrona la
   // función no finaliza hasta que no acaba la reproducción.
   bool PlayTrack(int numTrack);

   // Función que reproduce sucesivamente los tracks comprendidos
   // entre primerTrack y ultimoTrack. Si alguno de los dos
   // parámetros no está dentro del rango de tracks del CD que
   // se encuentra dentro del dispositivo devuelve error.
   // En caso de que los dos parámetros estén dentro del rango
   // pero primerTrack > ultimoTrack no devuelve error pero no
   // reproduce ningún track.
   bool PlayTracksDesdeA(int primerTrack, int ultimoTrack);

// Definición del tipo de la función que se ha de pasar como parámetro
// en una petición asíncrona. Esta función se ejecutará en atención a
// las interrupción que realice el dispositivo ya sea por finalización de
// la petición, cancelación, error, etc. El parámetro cdNotificacion se
// corresponde al código de notificación que indica el motivo de la
// interrupción.
   typedef void (*CDAUDIOINTPROCEDURE)(int cdNotificacion);

// Constantes para los códigos de notificación que, en una
// petición asíncrona, recibe como parámetro la función
// que se ha pasado como parámetro en dicha petición.

   // Constante que indica que la petición ha finalizado
   // correctamente.
   static const int CDAUDIO_NOTIFY_SUCCESSFUL = 1;

   // Constante que indica que la petición ha sido substituida
   // por una nueva petición. Este valor se recibe cuando se
   // realiza una nueva petición de reproducción sin que haya
   // finalizado la anterior.
   static const int CDAUDIO_NOTIFY_SUPERSEDED = 2;

   // Constante que indica que la petición no se ha podido
   // finalizar correctamente. Este valor se recibe cuando se
   // produce algún error al procesar la petición.
   static const int CDAUDIO_NOTIFY_FAILURE = 3;

   // Constante que indica que la petición ha sido cancelada.
   // Este valor se recibe cuando se para la reproducción
   // mediante cualquiera de las funciones de la librería.
   static const int CDAUDIO_NOTIFY_ABORTED = 4;

// Funciones de peticiones de E/S asíncronas.
// Todas estas funciones devuelven un booleano
// que indica si se ha producido algún error al
// enviar el comando de E/S y no en el procesado
// del mismo ya que son asíncronas. Cuando la petición
// finalice se ejecutará la función intPro que reciben
// estas funciones como parámetro enviándole uno de los
// códigos anteriores que notifica el motivo de la finalización

   // Función que reproduce el CD de Audio desde la
   // posición donde se encuentra situado el cabezal
   // hasta el final del CD. Como es una función asíncrona
   // la función finaliza una vez ha comenzado la reproducción.
   bool Play(CDAUDIOINTPROCEDURE intPro);

   // Función que reproduce el track correspondiente al
   // numTrack. Si numTrack no está dentro del rango de
   // tracks del dispositivo (entre 1 y NumeroDeTracks())
   // devuelve error. Como es una función asíncrona
   // la función finaliza una vez ha comenzado la reproducción.
   bool PlayTrack(int numTrack, CDAUDIOINTPROCEDURE intPro);

   // Función que reproduce sucesivamente los tracks comprendidos
   // entre primerTrack y ultimoTrack. Si alguno de los dos
   // parámetros no está dentro del rango de tracks del CD que
   // se encuentra dentro del dispositivo devuelve error.
   // En caso de que los dos parámetros estén dentro del rango
   // pero primerTrack > ultimoTrack no devuelve error pero no
   // reproduce ningún track. Como es una función asíncrona
   // la función finaliza una vez ha comenzado la reproducción.
   bool PlayTracksDesdeA(int primerTrack, int ultimoTrack,
                         CDAUDIOINTPROCEDURE intPro);

   // Función que reinicia una reproducción después de
   // una pausa.
   bool Resume(CDAUDIOINTPROCEDURE intPro);

// Funciones que permiten consultar los errores,
// en caso de que se produzcan.

   // Función que permite obtener una cadena de caracteres que
   // indica que error se ha producido.
   const char* MensajeError();
#endif