v32bis.h

Go to the documentation of this file.

/*
 * SpanDSP - a series of DSP components for telephony
 *
 * v32bis.h - ITU V.32bis modem
 *
 * Written by Steve Underwood <steveu@coppice.org>
 *
 * Copyright (C) 2008 Steve Underwood
 *
 * All rights reserved.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License version 2.1,
 * as published by the Free Software Foundation.
 *
 * 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 Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this program; if not, write to the Free Software
 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 * $Id: v32bis.h,v 1.1 2008/05/02 14:26:39 steveu Exp $
 */

/*! \file */

/*! \page v32bis_page The V.32bis modem
\section v32bis_page_sec_1 What does it do?

\section v32bis__page_sec_2 How does it work?
*/

#if !defined(_V32BIS_H_)
#define _V32BIS_H_

/*!
    V.32bis modem descriptor. This defines the working state for a single instance
    of a V.32bis modem.
*/
typedef struct
{
    /*! \brief The bit rate of the modem. Valid values are 1200 and 2400. */
    int bit_rate;
    /*! \brief TRUE is this is the calling side modem. */
    int caller;

    v17_rx_state_t rx;
    v17_tx_state_t tx;

    /*! \brief Error and flow logging control */
    logging_state_t logging;
} v32bis_state_t;

extern const complexf_t v32bis_constellation[16];

#if defined(__cplusplus)
extern "C"
{
#endif

/*! Reinitialise an existing V.32bis modem receive context.
    \brief Reinitialise an existing V.32bis modem receive context.
    \param s The modem context.
    \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
    \return 0 for OK, -1 for bad parameter */
int v32bis_rx_restart(v32bis_state_t *s, int bit_rate);

/*! Process a block of received V.32bis modem audio samples.
    \brief Process a block of received V.32bis modem audio samples.
    \param s The modem context.
    \param amp The audio sample buffer.
    \param len The number of samples in the buffer.
    \return The number of samples unprocessed. */
int v32bis_rx(v32bis_state_t *s, const int16_t amp[], int len);

/*! Get a snapshot of the current equalizer coefficients.
    \brief Get a snapshot of the current equalizer coefficients.
    \param coeffs The vector of complex coefficients.
    \return The number of coefficients in the vector. */
int v32bis_equalizer_state(v32bis_state_t *s, complexf_t **coeffs);

/*! Get the current received carrier frequency.
    \param s The modem context.
    \return The frequency, in Hertz. */
float v32bis_rx_carrier_frequency(v32bis_state_t *s);

/*! Get the current symbol timing correction since startup.
    \param s The modem context.
    \return The correction. */
float v32bis_symbol_timing_correction(v32bis_state_t *s);

/*! Get a current received signal power.
    \param s The modem context.
    \return The signal power, in dBm0. */
float v32bis_rx_signal_power(v32bis_state_t *s);

/*! Set the power level at which the carrier detection will cut in
    \param s The modem context.
    \param cutoff The signal cutoff power, in dBm0. */
void v32bis_rx_signal_cutoff(v32bis_state_t *s, float cutoff);

/*! Set a handler routine to process QAM status reports
    \param s The modem context.
    \param handler The handler routine.
    \param user_data An opaque pointer passed to the handler routine. */
void v32bis_set_qam_report_handler(v32bis_state_t *s, qam_report_handler_t *handler, void *user_data);

/*! Generate a block of V.32bis modem audio samples.
    \brief Generate a block of V.32bis modem audio samples.
    \param s The modem context.
    \param amp The audio sample buffer.
    \param len The number of samples to be generated.
    \return The number of samples actually generated. */
int v32bis_tx(v32bis_state_t *s, int16_t amp[], int len);

/*! Adjust a V.32bis modem transmit context's power output.
    \brief Adjust a V.32bis modem transmit context's output power.
    \param s The modem context.
    \param power The power level, in dBm0 */
void v32bis_tx_power(v32bis_state_t *s, float power);

/*! Reinitialise an existing V.32bis modem context, so it may be reused.
    \brief Reinitialise an existing V.32bis modem context.
    \param s The modem context.
    \param bit_rate The bit rate of the modem. Valid values are 4800, 7200, 9600, 12000 and 14400.
    \return 0 for OK, -1 for bad parameter */
int v32bis_restart(v32bis_state_t *s, int bit_rate);

/*! Initialise a V.32bis modem context. This must be called before the first
    use of the context, to initialise its contents.
    \brief Initialise a V.32bis modem context.
    \param s The modem context.
    \param bit_rate The bit rate of the modem. Valid values are 4800, 7200, 9600, 12000 and 14400.
    \param caller TRUE if this is the calling modem.
    \param get_bit The callback routine used to get the data to be transmitted.
    \param put_bit The callback routine used to get the data to be transmitted.
    \param user_data An opaque pointer, passed in calls to the get and put routines.
    \return A pointer to the modem context, or NULL if there was a problem. */
v32bis_state_t *v32bis_init(v32bis_state_t *s,
                            int bit_rate,
                            int caller,
                            get_bit_func_t get_bit,
                            put_bit_func_t put_bit,
                            void *user_data);

/*! Free a V.32bis modem receive context.
    \brief Free a V.32bis modem receive context.
    \param s The modem context.
    \return 0 for OK */
int v32bis_free(v32bis_state_t *s);

/*! Change the get_bit function associated with a V.32bis modem context.
    \brief Change the get_bit function associated with a V.32bis modem context.
    \param s The modem context.
    \param get_bit The callback routine used to get the data to be transmitted.
    \param user_data An opaque pointer. */
void v32bis_set_get_bit(v32bis_state_t *s, get_bit_func_t get_bit, void *user_data);

/*! Change the get_bit function associated with a V.32bis modem context.
    \brief Change the put_bit function associated with a V.32bis modem context.
    \param s The modem context.
    \param put_bit The callback routine used to process the data received.
    \param user_data An opaque pointer. */
void v32bis_set_put_bit(v32bis_state_t *s, put_bit_func_t put_bit, void *user_data);

#if defined(__cplusplus)
}
#endif

#endif
/*- End of file ------------------------------------------------------------*/