vpbapi.h

Go to the documentation of this file.
00001 /*---------------------------------------------------------------------------*\
00002 
00003     FILE....: VPBAPI.H
00004     TYPE....: C Header File
00005     AUTHOR..: Voicetronix
00006     DATE....: 26/11/97
00007 
00008         Header file for:
00009   
00010         "Voice Processing Board Applications Programmer Interface" functions.
00011 
00012 \*---------------------------------------------------------------------------*/
00013 
00014 /*---------------------------------------------------------------------------*\
00015 
00016         Copyright (C) 1999 Voicetronix Pty Ltd
00017 
00018         This program is free software; you can redistribute it and/or
00019         modify it under the terms of the GNU General Public License
00020         as published by the Free Software Foundation; either version 2
00021         of the License, or (at your option) any later version.
00022 
00023         This program is distributed in the hope that it will be useful,
00024         but WITHOUT ANY WARRANTY; without even the implied warranty of
00025         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00026         GNU General Public License for more details.
00027 
00028 \*---------------------------------------------------------------------------*/
00029 
00030 #ifndef __VPBAPI__
00031 #define __VPBAPI__
00032 
00033 #ifdef WIN32
00034 #define WINAPI  __stdcall
00035 #else
00036 #define WINAPI
00037 #endif
00038 
00039 /*-----------------------------------------------------------------------*\
00040 
00041                                                                 GENERAL
00042 
00043 \*-----------------------------------------------------------------------*/
00044 
00045 // Return codes
00046 
00047 #define VPB_OK                  0               
00048 #define VPB_NO_EVENTS   -1              
00049 #define VPB_TIME_OUT    -2              
00050 
00051 // string length
00052 
00053 #define VPB_MAX_STR             256
00054 
00055 // vpb_sethook() states
00056 
00057 #define VPB_ONHOOK      0
00058 #define VPB_OFFHOOK     1
00059 
00060 /*-------------------------------------------------------------------------*\
00061 
00062                                                         MISC FUNCTIONS
00063 
00064 \*-------------------------------------------------------------------------*/
00065 
00066 int WINAPI vpb_open(unsigned int board, unsigned int channel);
00067 int WINAPI vpb_close(int handle);
00068 void WINAPI vpb_sleep(long time_ms);
00069 int WINAPI vpb_sethook_async(int handle, int hookstate);
00070 int WINAPI vpb_sethook_sync(int handle, int hookstate);
00071 int WINAPI vpb_get_model(char *s);
00072 int WINAPI vpb_reset_play_fifo_alarm(int handle);
00073 int WINAPI vpb_reset_record_fifo_alarm(int handle);
00074 
00075 /*-----------------------------------------------------------------------*\
00076 
00077                                                         EVENT HANDLING  
00078 
00079 \*-----------------------------------------------------------------------*/
00080 
00081 typedef struct {
00082         int     type;           // event type (see below)
00083         int     handle;         // channel that generated event
00084         int     data;           // optional data
00085         unsigned long data1;
00086 } VPB_EVENT;
00087 
00088 // unsolicited events (maskable)
00089 
00090 #define VPB_RING                        0
00091 #define VPB_DIGIT                       1
00092 #define VPB_TONEDETECT          2
00093 #define VPB_TIMEREXP            3
00094 #define VPB_VOXON                       4
00095 #define VPB_VOXOFF                      5
00096 #define VPB_PLAY_UNDERFLOW      6
00097 #define VPB_RECORD_OVERFLOW     7
00098 #define VPB_DTMF                8
00099 
00100 // solicited events (not maskable)
00101 
00102 #define VPB_PLAYEND                     100
00103 #define VPB_RECORDEND           101
00104 #define VPB_DIALEND                     102
00105 #define VPB_TONE_DEBUG_END      103
00106 #define VPB_CALLEND                     104
00107 
00108 // Event mask values
00109 
00110 #define VPB_MRING                               (1<<VPB_RING)
00111 #define VPB_MDIGIT                              (1<<VPB_DIGIT)
00112 #define VPB_MDTMF                               (1<<VPB_DTMF)
00113 #define VPB_MTONEDETECT                 (1<<VPB_TONEDETECT)
00114 #define VPB_MTIMEREXP                   (1<<VPB_TIMEREXP)
00115 #define VPB_MVOXON                              (1<<VPB_VOXON)
00116 #define VPB_MVOXOFF                             (1<<VPB_VOXOFF)
00117 #define VPB_MPLAY_UNDERFLOW             (1<<VPB_PLAY_UNDERFLOW)
00118 #define VPB_MRECORD_OVERFLOW    (1<<VPB_RECORD_OVERFLOW)
00119 
00120 int WINAPI vpb_enable_event(int handle, unsigned short mask);
00121 int WINAPI vpb_disable_event(int handle, unsigned short mask);
00122 int WINAPI vpb_get_event_mask(int handle);
00123 int WINAPI vpb_set_event_mask(int handle, unsigned short mask);
00124 int WINAPI vpb_get_event_async(VPB_EVENT *event);
00125 int WINAPI vpb_get_event_sync(VPB_EVENT *event, unsigned int time_out);
00126 int WINAPI vpb_get_event_ch_async(int handle, VPB_EVENT *e);
00127 int WINAPI vpb_get_event_ch_sync(int handle, VPB_EVENT *e, unsigned int time_out);
00128 int WINAPI vpb_put_event(VPB_EVENT *event);
00129 void WINAPI vpb_translate_event(VPB_EVENT *e, char s[]);
00130 int WINAPI vpb_set_event_callback(int handle, void (WINAPI *event_callback)(VPB_EVENT *e, void *context), void *context);
00131 
00132 /*-----------------------------------------------------------------------*\
00133 
00134                                                         PLAY AND RECORD
00135 
00136 \*-----------------------------------------------------------------------*/
00137 
00138 // return code for vpb_play_buf_sync and vpb_record_buf_sync
00139 
00140 #define VPB_FINISH              1       
00141 
00142 // compression modes
00143 
00144 #define VPB_LINEAR              0       // 128 kbit/s 16 bit linear
00145 #define VPB_ALAW                1       // 64 kbit/s A-law companded
00146 #define VPB_MULAW               2       // 64 kbit/s mu-law companded
00147 #define VPB_OKIADPCM    3       // 32 kbit/s OKI ADPCM
00148 #define VPB_OKIADPCM24  4       // 24 kbit/s OKI ADPCM
00149 
00150 // structures for configuring record and play params
00151 
00152 typedef struct {
00153         char                    *term_digits;   // string of digits to terminate collection
00154 } VPB_PLAY;
00155 
00156 typedef struct {
00157         char                    *term_digits;   // string of digits to terminate collection
00158         unsigned int    time_out;               // record terminates after time_out ms
00159                                                                         // if set to 0 (default) no time out
00160 } VPB_RECORD;
00161 
00162 // play functions
00163 
00164 int WINAPI vpb_play_file_sync(int handle, char file_name[]);
00165 int WINAPI vpb_play_file_async(int handle, char file_name[], int data);
00166 int WINAPI vpb_play_voxfile_sync(int handle, char file_name[],unsigned short mode);
00167 int WINAPI vpb_play_voxfile_async(int handle, char file_name[], unsigned short mode, int data);
00168 
00169 int WINAPI vpb_play_buf_start(int handle, unsigned short mode);
00170 int WINAPI vpb_play_buf_sync(int handle, char *buf, unsigned short length);
00171 int WINAPI vpb_play_buf_finish(int handle);
00172 int WINAPI vpb_play_terminate(int handle);
00173 int WINAPI vpb_play_set(int handle, VPB_PLAY *vpb_play);
00174 int WINAPI vpb_play_set_gain(int handle, float gain);
00175 int WINAPI vpb_play_get_gain(int handle, float *gain);
00176 
00177 // record functions
00178 
00179 int WINAPI vpb_record_file_sync(int handle, char file_name[], unsigned short mode);
00180 int WINAPI vpb_record_file_async(int handle, char file_name[], unsigned short mode);
00181 int WINAPI vpb_record_voxfile_sync(int handle, char file_name[], unsigned short mode);
00182 int WINAPI vpb_record_voxfile_async(int handle, char file_name[], unsigned short mode);
00183 int WINAPI vpb_record_buf_start(int handle, unsigned short mode);
00184 int WINAPI vpb_record_buf_sync(int handle, char *buf, unsigned short length);
00185 int WINAPI vpb_record_buf_finish(int handle);
00186 int WINAPI vpb_record_terminate(int handle);
00187 int WINAPI vpb_record_set(int handle, VPB_RECORD *vpb_record);
00188 int WINAPI vpb_record_set_gain(int handle, float gain);
00189 int WINAPI vpb_record_get_gain(int handle, float *gain);
00190 int WINAPI vpb_record_buf_async(int handle, unsigned short mode,char *mbuf,unsigned long size);
00191 
00192 // record terminating reason outputed during a vpb_record_???_async() in 
00193 // the data member of the VPBevents
00194 
00195 #define VPB_RECORD_DIGIT                        1       // terminated due to Digit String
00196 #define VPB_RECORD_TIMEOUT                      2       // terminated due to record timeout
00197 #define VPB_RECORD_ENDOFDATA            3       // terminate due to end of data in buffer
00198 #define VPB_RECORD_MAXDIGIT                     4       // terminate due to Maximum digits
00199 
00200 /*-----------------------------------------------------------------------*\
00201 
00202                                                         ERROR HANDLING
00203 
00204 \*-----------------------------------------------------------------------*/
00205 
00206 // Run time error manager modes
00207 
00208 #define VPB_DEVELOPMENT 0       // API function error causes program abort
00209 #define VPB_ERROR_CODE  1       // API function error returns error code
00210 #define VPB_EXCEPTION   2       // API function error throw a exception
00211 
00212 // Exception class
00213 
00214 class VpbException {
00215 public:
00216         int             code;                                           // error code
00217         char    s[VPB_MAX_STR];                         // code translated into string
00218         char    api_function[VPB_MAX_STR];      // api func that threw exception
00219         
00220         VpbException(int c, char trans[], char api_function[]);
00221 };
00222 
00223 int WINAPI vpb_seterrormode(int mode);
00224 void WINAPI vpb_throw_exception(int c, char trans[], char api_function[]);
00225 
00226 /*-----------------------------------------------------------------------*\
00227 
00228                                                         DIALLING
00229 
00230 \*-----------------------------------------------------------------------*/
00231 
00232 // blind dialling functions
00233 
00234 int WINAPI vpb_dial_sync(int handle, char *dialstr);
00235 int WINAPI vpb_dial_async(int handle, char *dialstr);
00236 
00237 // Call progress tone ids
00238 
00239 #define VPB_CALL_DISCONNECT     0       
00240 #define VPB_CALL_DIALTONE       1
00241 #define VPB_CALL_RINGBACK       2
00242 #define VPB_CALL_BUSY           3
00243 #define VPB_CALL_GRUNT          4
00244 
00245 typedef struct {
00246         unsigned int    tone_id;        // prog tone detector tone id
00247         unsigned int    call_id;        // call progress tone id
00248         unsigned int    terminate;      // no zero to terminate list
00249 } VPB_TONE_MAP;
00250 
00251 #define VPB_MAX_TONE_MAP        10      // maximum number of entries in tone map
00252 
00253 // structure used to store call progress config information
00254 
00255 typedef struct {
00256         unsigned int    dialtones;                              // number of dialtones (eg internal line, then outside line = 2 dialtones)
00257         unsigned int    dialtone_timeout;               // wait for dial tone timeout in ms
00258         unsigned int    ringback_timeout;               // time to wait for initial ringback in ms
00259         unsigned int    inter_ringback_timeout; // if ringback stops for this time (ms), call is considered connected
00260         unsigned int    answer_timeout;                 // time to wait for answer after ringback detected in ms
00261         VPB_TONE_MAP    tone_map[VPB_MAX_TONE_MAP];     // maps tone_id to call progress tone   
00262 } VPB_CALL;
00263 
00264 // getting and setting call progress configuration
00265 
00266 int WINAPI vpb_get_call(int handle, VPB_CALL *vpb_call);
00267 int WINAPI vpb_set_call(int handle, VPB_CALL *vpb_call);
00268 
00269 // call progress return codes
00270 
00271 #define VPB_CALL_CONNECTED              0               // call connected successfully
00272 #define VPB_CALL_NO_DIAL_TONE   1               // dial tone time out
00273 #define VPB_CALL_NO_RING_BACK   2               // ring back time out
00274 #define VPB_CALL_BUSY                   3               // busy tone 
00275 #define VPB_CALL_NO_ANSWER              4               // no answer time out
00276 #define VPB_CALL_DISCONNECTED   5               // no answer time out
00277 
00278 // dialling with call progress
00279 
00280 int WINAPI vpb_call_sync(int handle, char *dialstr);
00281 int WINAPI vpb_call_async(int handle, char *dialstr);
00282 
00283 /*-----------------------------------------------------------------------*\
00284 
00285                                                 PROGRAMMABLE TONE GENERATOR
00286 
00287 \*-----------------------------------------------------------------------*/
00288 
00289 // Programmable tone generator structure ---------------------------------
00290 
00291 typedef struct {
00292     unsigned short      freq1;  // frequency of first tone
00293     unsigned short      freq2;  // frequency of second tone
00294     unsigned short      freq3;  // frequency of third tone
00295         short                   level1; // first tone level in dB, 0dB maximum
00296         short                   level2; // second tone level in dB, 0dB maximum
00297         short                   level3; // third tone level in dB, 0dB maximum
00298     unsigned long       ton;    // on time ms 
00299         unsigned long   toff;   // off time ms 
00300 } VPB_TONE;
00301 
00302 int WINAPI vpb_settone(char ident, VPB_TONE *vpb_tone);
00303 int WINAPI vpb_gettone(char ident, VPB_TONE *vpb_tone);
00304 int WINAPI vpb_playtone_async(int handle, VPB_TONE *vpb_tone);
00305 int WINAPI vpb_playtone_sync(int handle, VPB_TONE *vpb_tone);
00306 
00307 /*-----------------------------------------------------------------------*\
00308 
00309                                                 PROGRAMMABLE TONE DETECTOR
00310 
00311 \*-----------------------------------------------------------------------*/
00312 
00313 // built in tone dectector IDs
00314 
00315 #define VPB_DIAL                0               // dial tone detected
00316 #define VPB_RINGBACK    1               // ringback detected
00317 #define VPB_BUSY                2               // busy tone detected
00318 #define VPB_GRUNT               3               // grunt detected
00319 
00320 #define VPB_MD  10              // maximum number of tone detectors per device
00321 #define VPB_MS  10              // maximum number of states per cadence state mach
00322 
00323 // State transition table consists of one entry for each state transition.
00324 
00325 #define VPB_TIMER       0
00326 #define VPB_RISING      1
00327 #define VPB_FALLING     2
00328 #define VPB_DELAY       3
00329 
00330 typedef struct {
00331     unsigned short type;                // VPB_TIMER, VPB_RISING, or VPB_FALLING                
00332     unsigned short tfire;               // timer mode only                      
00333     unsigned short tmin;                // minimum tone on/off time (non timer) in ms
00334     unsigned short tmax;                // maximum tone on/off time (non timer) in ms
00335 } VPB_STRAN;
00336 
00337 typedef struct {
00338    unsigned short       nstates;        // number of cadence states                     
00339    unsigned short       tone_id;        // unique ID number for this tone               
00340    unsigned short       ntones;         // number of tones (1 or 2)                     
00341    unsigned short       freq1;          // freq of first tone (Hz)                      
00342    unsigned short       bandwidth1;     // bandwidth of first tone (Hz) 
00343    unsigned short       freq2;          // freq of first tone (Hz)                      
00344    unsigned short       bandwidth2;     // bandwidth of second tone (Hz)        
00345    short                        minlevel1;  // min amp of 1st tone ref 0dBm0            
00346    short                        minlevel2;      // min amp of 2nd tone ref 0dbm0                
00347    short                        twist;          // allowable difference in tone powers  
00348                                                                 // If (E1/E2 < twist) AND (E2/E1 < twist) tone OK               
00349    short                        snr;            // min signal to noise ratio to accept tone                     
00350    unsigned short       glitch;         // short transitions of glitch ms ignored
00351 
00352    VPB_STRAN stran[VPB_MS];             // cadence state transition table
00353 } VPB_DETECT;
00354 
00355 int WINAPI vpb_settonedet(int handle, VPB_DETECT *d);
00356 int WINAPI vpb_gettonedet(int handle, int id, VPB_DETECT *d);
00357 int WINAPI vpb_debug_tonedet(int handle, int id, char file_name[], int sec);
00358 int WINAPI vpb_tonedet_make_default(VPB_DETECT *d);
00359 
00360 /*-------------------------------------------------------------------------*\
00361 
00362                                                         TIMER
00363 
00364 \*-------------------------------------------------------------------------*/
00365 
00366 int WINAPI vpb_timer_open(void **timer, int handle, int id, unsigned long period);
00367 int WINAPI vpb_timer_close(void *timer);
00368 int WINAPI vpb_timer_start(void *timer);
00369 int WINAPI vpb_timer_stop(void *timer);
00370 int WINAPI vpb_timer_restart(void *timer);
00371 int WINAPI vpb_timer_get_unique_timer_id();
00372 int WINAPI vpb_timer_change_period(void *timer, unsigned long newperiod);
00373 
00374 /*-------------------------------------------------------------------------*\
00375 
00376                                                         VOX
00377 
00378 \*-------------------------------------------------------------------------*/
00379 
00380 typedef struct {
00381    float                        onlevel;        // switch on level in dB (0 dB maximum)
00382    float                        offlevel;       // switch off level in dB (0 dB maximum)
00383    unsigned short       runon;          // run on time in ms
00384 } VPB_VOX;
00385 
00386 int WINAPI vpb_setvox(int handle, VPB_VOX *vox);
00387 int WINAPI vpb_getvox(int handle, VPB_VOX *vox);
00388 
00389 /*-------------------------------------------------------------------------*\
00390 
00391                                                         AGC
00392 
00393 \*-------------------------------------------------------------------------*/
00394 
00395 typedef struct {
00396     float setpoint;             // desired signal level                 
00397     float attack;               // agc filter attack            
00398     float decay;                // agc filter decay                     
00399 } VPB_AGC;
00400 
00401 int WINAPI vpb_setagc(int handle, VPB_AGC *agc);
00402 int WINAPI vpb_getagc(int handle, VPB_AGC *agc);
00403 
00404 /*-------------------------------------------------------------------------*\
00405 
00406                                                         ADPCM FUNCTIONS
00407 
00408 \*-------------------------------------------------------------------------*/
00409 
00410 int WINAPI vpb_adpcm_open(void **adpcm);
00411 void WINAPI vpb_adpcm_close(void *adpcm);
00412 int WINAPI vpb_adpcm_decode(void *adpcm,
00413                                                         short linearbuf[],  unsigned short *nlinear,
00414                                                         char adpcmbuf[] ,  unsigned short nadpcmbytes);
00415 
00416 /*-------------------------------------------------------------------------*\
00417 
00418                                                         WAVE FUNCTIONS
00419 
00420 \*-------------------------------------------------------------------------*/
00421 
00422 int WINAPI vpb_wave_open_write(void **ppv, char filename[], int mode);
00423 int WINAPI vpb_wave_write(void *wv, char buf[], long n);
00424 void WINAPI vpb_wave_close_write(void *wv);
00425 
00426 int WINAPI vpb_wave_open_read(void **ppv, char filename[]);
00427 int WINAPI vpb_wave_read(void *wv, char buf[], long n);
00428 void WINAPI vpb_wave_close_read(void *wv);
00429 
00430 void WINAPI vpb_wave_set_sample_rate(void *wv, unsigned short rate);
00431 int WINAPI vpb_wave_seek(void *wv, long offset);
00432 int WINAPI vpb_wave_get_mode(void *wv, unsigned short *mode);
00433 
00434 /*-------------------------------------------------------------------------*\
00435 
00436                                                         RING FUNCTIONS
00437 
00438 \*-------------------------------------------------------------------------*/
00439 
00440 int WINAPI vpb_set_ring(int handle, unsigned int rings_to_fire, unsigned int time_out);
00441 int WINAPI vpb_get_ring(int handle, unsigned int *rings_to_fire, unsigned int *time_out);
00442 
00443 /*-------------------------------------------------------------------------*\
00444 
00445                                                 GET DIGIT FUNCTIONS
00446 
00447 \*-------------------------------------------------------------------------*/
00448 
00449 typedef struct {
00450         char                    *term_digits;                   // string of digits to terminate collection
00451         unsigned short  max_digits;                             // terminate after this many digits collected
00452         unsigned long   digit_time_out;                 // max total time for digit collection (ms)
00453         unsigned long   inter_digit_time_out;   // max time between digits (ms)
00454 } VPB_DIGITS;
00455 
00456 // terminate conditines passed in data field of VPB_EVENT when
00457 // VPB_DIGIT event posted
00458 
00459 #define VPB_DIGIT_TERM                                  0
00460 #define VPB_DIGIT_MAX                                   1
00461 #define VPB_DIGIT_TIME_OUT                              2
00462 #define VPB_DIGIT_INTER_DIGIT_TIME_OUT  3
00463 #define VPB_DIGIT_BUFFER_FULL                   4
00464 
00465 int WINAPI vpb_flush_digits(int handle);
00466 int WINAPI vpb_get_digits_async(int handle, VPB_DIGITS *digits, char *digbuf);
00467 int WINAPI vpb_get_digits_sync(int handle, VPB_DIGITS *digits, char *digbuf);
00468 int WINAPI get_digits_async(int handle, VPB_DIGITS *newdig, char *buf, unsigned short size);
00469 int WINAPI get_digits_record_async(int handle, VPB_DIGITS *newdig, char *buf);
00470 
00471 /*-------------------------------------------------------------------------*\
00472 
00473                                                         PIP FUNCTIONS
00474 
00475 \*-------------------------------------------------------------------------*/
00476 
00477 typedef struct {
00478         unsigned int    width;  // width of pip pulse in ms
00479         unsigned int    period; // period between pip pulse in ms
00480 } VPB_PIP;
00481 
00482 int WINAPI vpb_set_pip(VPB_PIP *vpb_pip);
00483 int WINAPI vpb_get_pip(VPB_PIP *vpb_pip);
00484 
00485 int WINAPI vpb_pip_on(int handle);
00486 int WINAPI vpb_pip_off(int handle);
00487 
00488 #endif  // #ifndef __VPBAPI__   

Generated on Mon Sep 25 16:20:12 2006 for OPAL by  doxygen 1.4.7