speex_callbacks.h

00001 /* Copyright (C) 2002 Jean-Marc Valin*/
00002 /**
00003   @file speex_callbacks.h
00004   @brief Describes callback handling and in-band signalling
00005 */
00006 /*
00007    Redistribution and use in source and binary forms, with or without
00008    modification, are permitted provided that the following conditions
00009    are met:
00010    
00011    - Redistributions of source code must retain the above copyright
00012    notice, this list of conditions and the following disclaimer.
00013    
00014    - Redistributions in binary form must reproduce the above copyright
00015    notice, this list of conditions and the following disclaimer in the
00016    documentation and/or other materials provided with the distribution.
00017    
00018    - Neither the name of the Xiph.org Foundation nor the names of its
00019    contributors may be used to endorse or promote products derived from
00020    this software without specific prior written permission.
00021    
00022    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00023    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00024    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00025    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
00026    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00027    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00028    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00029    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00030    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00031    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00032    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00033 
00034 */
00035 
00036 #ifndef SPEEX_CALLBACKS_H
00037 #define SPEEX_CALLBACKS_H
00038 /** @defgroup SpeexCallbacks Various definitions for Speex callbacks supported by the decoder.
00039  *  @{
00040  */
00041 
00042 #include "speex.h"
00043 
00044 #ifdef __cplusplus
00045 extern "C" {
00046 #endif
00047 
00048 /** Total number of callbacks */
00049 #define SPEEX_MAX_CALLBACKS 16
00050 
00051 /* Describes all the in-band requests */
00052 
00053 /*These are 1-bit requests*/
00054 /** Request for perceptual enhancement (1 for on, 0 for off) */
00055 #define SPEEX_INBAND_ENH_REQUEST         0
00056 /** Reserved */
00057 #define SPEEX_INBAND_RESERVED1           1
00058 
00059 /*These are 4-bit requests*/
00060 /** Request for a mode change */
00061 #define SPEEX_INBAND_MODE_REQUEST        2
00062 /** Request for a low mode change */
00063 #define SPEEX_INBAND_LOW_MODE_REQUEST    3
00064 /** Request for a high mode change */
00065 #define SPEEX_INBAND_HIGH_MODE_REQUEST   4
00066 /** Request for VBR (1 on, 0 off) */
00067 #define SPEEX_INBAND_VBR_QUALITY_REQUEST 5
00068 /** Request to be sent acknowledge */
00069 #define SPEEX_INBAND_ACKNOWLEDGE_REQUEST 6
00070 /** Request for VBR (1 for on, 0 for off) */
00071 #define SPEEX_INBAND_VBR_REQUEST         7
00072 
00073 /*These are 8-bit requests*/
00074 /** Send a character in-band */
00075 #define SPEEX_INBAND_CHAR                8
00076 /** Intensity stereo information */
00077 #define SPEEX_INBAND_STEREO              9
00078 
00079 /*These are 16-bit requests*/
00080 /** Transmit max bit-rate allowed */
00081 #define SPEEX_INBAND_MAX_BITRATE         10
00082 
00083 /*These are 32-bit requests*/
00084 /** Acknowledge packet reception */
00085 #define SPEEX_INBAND_ACKNOWLEDGE         12
00086 
00087 /** Callback function type */
00088 typedef int (*speex_callback_func)(SpeexBits *bits, void *state, void *data);
00089 
00090 /** Callback information */
00091 typedef struct SpeexCallback {
00092    int callback_id;             /**< ID associated to the callback */
00093    speex_callback_func func;    /**< Callback handler function */
00094    void *data;                  /**< Data that will be sent to the handler */
00095    void *reserved1;             /**< Reserved for future use */
00096    int   reserved2;             /**< Reserved for future use */
00097 } SpeexCallback;
00098 
00099 /** Handle in-band request */
00100 int speex_inband_handler(SpeexBits *bits, SpeexCallback *callback_list, void *state);
00101 
00102 /** Standard handler for mode request (change mode, no questions asked) */
00103 int speex_std_mode_request_handler(SpeexBits *bits, void *state, void *data);
00104 
00105 /** Standard handler for high mode request (change high mode, no questions asked) */
00106 int speex_std_high_mode_request_handler(SpeexBits *bits, void *state, void *data);
00107 
00108 /** Standard handler for in-band characters (write to stderr) */
00109 int speex_std_char_handler(SpeexBits *bits, void *state, void *data);
00110 
00111 /** Default handler for user-defined requests: in this case, just ignore */
00112 int speex_default_user_handler(SpeexBits *bits, void *state, void *data);
00113 
00114 
00115 
00116 /** Standard handler for low mode request (change low mode, no questions asked) */
00117 int speex_std_low_mode_request_handler(SpeexBits *bits, void *state, void *data);
00118 
00119 /** Standard handler for VBR request (Set VBR, no questions asked) */
00120 int speex_std_vbr_request_handler(SpeexBits *bits, void *state, void *data);
00121 
00122 /** Standard handler for enhancer request (Turn ehnancer on/off, no questions asked) */
00123 int speex_std_enh_request_handler(SpeexBits *bits, void *state, void *data);
00124 
00125 /** Standard handler for VBR quality request (Set VBR quality, no questions asked) */
00126 int speex_std_vbr_quality_request_handler(SpeexBits *bits, void *state, void *data);
00127 
00128 
00129 #ifdef __cplusplus
00130 }
00131 #endif
00132 
00133 /** @} */
00134 #endif