/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set et sw=2 ts=2: */
/***************************************************************************
 *            audioio.h
 *
 *  Thu Sep 25 15:55:14 CEST 2014
 *  Copyright 2014 Bent Bisballe Nyeng
 *  deva@aasimon.org
 ****************************************************************************/

/*
 *  This file is part of LibAudioIO.
 *
 *  LibAudioIO is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *  
 *  LibAudioIO 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
 *  Lesser General Public License for more details.
 *  
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with LibAudioIO; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */
#ifndef __LIBAUDIOIO_AUDIOIO_H__
#define __LIBAUDIOIO_AUDIOIO_H__

#ifdef __cplusplus
extern "C" {
#endif

#define NO_ERROR                     0

#define OUT_OF_MEMORY              -101
#define MISSING_HANDLE             -102
#define MISSING_MIXER_HANDLE       -102
#define MISSING_PCM_HANDLE         -104
#define MIXER_INIT_FAILED          -105
#define NO_SUCH_CHANNEL            -106
#define SAMPLE_READ_ERROR          -107
#define SAMPLE_WRITE_ERROR         -108
#define MIXER_ERROR                -109
#define COULD_NOT_OPEN_DEVICE      -110
#define INVALID_MIXER_LEVEL        -111
#define NO_SUCH_ENUM               -112

struct aio_t;

/**
 * Initalise the AudioIO library and connect to a soundcard and a mixer.
 * @param err An int pointer containing error value if function is unsuccessful.
 * @param device A string containing the device name to connect to. A list 
 * possible devices can be seen with the 'aplay -L' command. The device
 * "default" are usually the one needed.
 * @param mixer A string containing the mixer interface to connect to. A list
 * of possible interfaces can be seen with the 'amixer scontrols' command.
 * Usually the interface "Capture" is the one needed.
 * @param samplerate An unsigned integer containing the desired samplerate in
 * Hertz.
 * @param channels An unsigned integer containing the desired number of
 * channels. The channel samples will be interleaved in the data stream whe
 * ai_read is called.
 * @return A pointer to the newly created handle or NULL on failure.
 */
struct aio_t *aio_init(int *err,
                       const char *playback_device,
                       const char *playback_mixer,
                       const char *capture_device,
                       const char *capture_mixer,
                       unsigned int samplerate,
                       unsigned int channels);

/**
 * Read samples from the soundcard.
 * @param err An int pointer containing error value if function is unsuccessful.
 * @param handle A pointer to the handle to be used.
 * @param pcm Buffer cotaining which will be filled with samples.
 * @param maxsize The maximum number of bytes (not samples) to read.
 * @return Returns the number of bytes (not samples) read or -1 on error.
 * NOTE: to get the number of samples read, devide the return value with the
 * sample width (2 bytes / 16 bits) and the number of interleaved channels
 * (usually 1 or 2).
 */
int aio_read(struct aio_t *handle, char *pcm, unsigned int maxsize);

/**
 * Write samples to the soundcard.
 * @param err An int pointer containing error value if function is unsuccessful.
 * @param handle A pointer to the handle to be used.
 * @param size The maximum number of bytes (not samples) to be written.
 * @return Returns the number of bytes (not samples) written or -1 on error.
 * NOTE: to get the number of samples read, devide the return value with the
 * sample width (2 bytes / 16 bits) and the number of interleaved channels
 * (usually 1 or 2).
 */
int aio_write(struct aio_t *handle, const char *pcm, unsigned int size);

/**
 * Adjust playback channel mixer levels.
 * @param handle A pointer to the handle to be used.
 * @param channel The channel number to set mixer level of. 0 or 1 should be
 * used for the two channels of a stereo interface.
 * @param level The mixer level to set in dB
 * @return Returns error code.
 */
int aio_set_playback_mixer_level(struct aio_t *handle, unsigned int channel,
                                 float level);

/**
 * Get playback channel mixer levels.
 * @param handle A pointer to the handle to be used.
 * @param channel The channel number to get mixer level of. 0 or 1 should be
 * used for the two channels of a stereo interface.
 * @param level A pointer to a float which after a successful call will contain
 * the channel amplification level in dB.
 * @return Returns error code.
 */
int aio_get_playback_mixer_level(struct aio_t *handle, unsigned int channel,
                                 float *level);

/**
 * Get playback channel amplification range in dB.
 * @param handle A pointer to the handle to be used.
 * @param min A pointer to a float in which the min value will be returned.
 * @param max A pointer to a float in which the max value will be returned.
 * @return Returns error code.
 */
int aio_get_playback_mixer_level_range(struct aio_t *handle,
                                       float *min, float *max);

/**
 * Adjust capture channel mixer levels.
 * @param handle A pointer to the handle to be used.
 * @param channel The channel number to set mixer level of. 0 or 1 should be
 * used for the two channels of a stereo interface.
 * @param level The mixer level to set in dB
 * @return Returns error code.
 */
int aio_set_capture_mixer_level(struct aio_t *handle, unsigned int channel,
                                float level);

/**
 * Get channel mixer levels.
 * @param handle A pointer to the handle to be used.
 * @param channel The channel number to get mixer level of. 0 or 1 should be
 * used for the two channels of a stereo interface.
 * @param level A pointer to a float which after a successful call will contain
 * the channel amplification level in dB.
 * @return Returns error code.
 */
int aio_get_capture_mixer_level(struct aio_t *handle, unsigned int channel,
                                float *level);

/**
 * Get capture channel amplification range in dB.
 * @param handle A pointer to the handle to be used.
 * @param min A pointer to a float in which the min value will be returned.
 * @param max A pointer to a float in which the max value will be returned.
 * @return Returns error code.
 */
int aio_get_capture_mixer_level_range(struct aio_t *handle,
                                      float *min, float *max);

/**
 * Get value of enum switch on a specific channel.
 * @param handle A pointer to the handle to be used.
 * @param name The name of the enum swicth.
 * @param value The buffer in which the switch enum value will be written.
 * @param maxsize The size fo the value buffer.
 * @return Returns error code.
 */
int aio_get_enum_value(struct aio_t *handle, const char *name,
                       char *value, unsigned int maxsize);

/**
 * Set value of enum switch on a specific channel.
 * @param handle A pointer to the handle to be used.
 * @param name The name of the enum swicth.
 * @param value The buffer containing the string value of the enum switch.
 * @return Returns error code.
 */
int aio_set_enum_value(struct aio_t *handle,
                       const char *name, const char *value);

/**
 * Set mute state of a named channel.
 */
int aio_set_mute(struct aio_t *handle, const char *name, int muted);

/**
 * Get mute state of a named channel.
 */
int aio_get_mute(struct aio_t *handle, const char *name, int *muted);

/**
 * Get actual samplerate.
 * The samplerate set in ai_init may or may not match a possible samplerate for
 * the audio hardware and therefore the ALSA library might decide to use another
 * samplerate than the one specified.
 * This function can be called to obtain the actual samplerate that the hardware
 * has been configured to use.
 * @param err An int pointer containing error value if function is unsuccessful.
 * @param handle A pointer to the handle to be used.
 * @return The samplerate as an integer or -1 on error.
 */
int aio_get_samplerate(struct aio_t *handle);

/**
 * Get the buffer size used by the underlying hardware/software.
 * @param handle A pointer to the handle to be used.
 * @return The buffer size in bytes.
 */
int aio_get_buffer_size(struct aio_t *handle);

/**
 * Close and free the handle.
 * @param err An int pointer containing error value if function is unsuccessful.
 * @param handle A pointer to the handle to be closed.
 */
int aio_close(struct aio_t *handle);

#ifdef __cplusplus
}
#endif

#endif/*__LIBAUDIOIO_AUDIOIO_H__*/