/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/***************************************************************************
 *            audioin.h
 *
 *  Wed Sep 30 11:36:18 CEST 2009
 *  Copyright 2011 Bent Bisballe Nyeng
 *  deva@aasimon.org
 ****************************************************************************/

/*
 *  This file is part of libaudioin.
 *
 *  libaudioin 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 2 of the License, or
 *  (at your option) any later version.
 *
 *  libaudioin 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 libaudioin; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.
 */
#ifndef __LIBAUDIOIN_AUDIOIN_H__
#define __LIBAUDIOIN_AUDIOIN_H__

#ifdef __cplusplus
extern "C" {
#endif

#define NO_ERROR                     0

#define OUT_OF_MEMORY              101
#define MISSING_HANDLE             102

#define COULD_NOT_OPEN_DEVICE      203
#define COULD_NOT_SET_HW_PARAMS    204
#define COULD_NOT_INIT_PARAMS      205
#define COULD_NOT_SET_ACCESS_MODE  206
#define COULD_NOT_SET_FORMAT       207
#define COULD_NOT_SET_CHANNELS     208
#define COULD_NOT_SET_SAMPLE_RATE  209
#define COULD_NOT_SET_PERIOD_SIZE  210

#define BUFFER_TOO_SMALL           305
#define BUFFER_OVERRUN             306
#define READ_ERROR                 307
#define SHORT_READ                 308

#define MIXER_INIT_FAILED          400

#define MIXER_NOT_INITIALISED      401
#define INVALID_MIXER_LEVEL        402
#define INVALID_CHANNEL_NUMBER     403
#define COULD_NOT_SET_MIXER_LEVEL  404

struct ai_t;

/**
 * Initalise the AudioIn 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 ai_t *ai_init(int *err, const char *device, const char *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 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 ai_read(int *err, struct ai_t *handle, void *pcm, unsigned int maxsize);

/**
 * Adjust channel mixer levels.
 * @param err An int pointer containing error value if function is unsuccessful.
 * @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, ranging from 0.0 to 1.0 where 0.0 is
 * mute and 1.0 is maximum gain.
 * @return Returns -1 on error 0 otherwise.
 */
int ai_set_mixer_level(int *err, struct ai_t *handle, unsigned int channel,
                       float level);

/**
 * 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 ai_get_samplerate(int *err, struct ai_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.
 */
void ai_close(int *err, struct ai_t *handle);

#ifdef __cplusplus
}
#endif

#endif/*__LIBAUDIOIN_AUDIOIN_H__*/