vpbapi.h

multi-line Adjunct Communication Server

/*---------------------------------------------------------------------------*\

    FILE....: VPBAPI.H
    TYPE....: C Header File
    AUTHOR..: Voicetronix
    DATE....: 26/11/97

	Header file for:
  
	"Voice Processing Board Applications Programmer Interface" functions.

\*---------------------------------------------------------------------------*/

/*---------------------------------------------------------------------------*\

	Copyright (C) 1999-2000 Voicetronix Pty Ltd

	This program 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.

	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 General Public License for more details.

\*---------------------------------------------------------------------------*/

#ifndef __VPBAPI__
#define __VPBAPI__

#ifdef WIN32
#define	WINAPI	__stdcall
#else
#define	WINAPI
#endif

/*-----------------------------------------------------------------------*\

								GENERAL

\*-----------------------------------------------------------------------*/

// Return codes

#define	VPB_OK			0		
#define	VPB_NO_EVENTS	-1		
#define	VPB_TIME_OUT	-2		

// string length

#define	VPB_MAX_STR		256

// vpb_sethook() states

#define	VPB_ONHOOK	0
#define	VPB_OFFHOOK	1

/*-------------------------------------------------------------------------*\

							MISC FUNCTIONS

\*-------------------------------------------------------------------------*/

int WINAPI vpb_open(unsigned int board, unsigned int channel);
int WINAPI vpb_close(int handle);
void WINAPI vpb_sleep(long time_ms);
int WINAPI vpb_sethook_async(int handle, int hookstate);
int WINAPI vpb_sethook_sync(int handle, int hookstate);
int WINAPI vpb_get_model(char *s);
int WINAPI vpb_reset_play_fifo_alarm(int handle);
int WINAPI vpb_reset_record_fifo_alarm(int handle);

/*-----------------------------------------------------------------------*\

							EVENT HANDLING	

\*-----------------------------------------------------------------------*/

typedef struct {
	int	type;		// event type (see below)
	int	handle;		// channel that generated event
	int	data;		// optional data
	unsigned long data1;
} VPB_EVENT;

// unsolicited events (maskable)

#define VPB_RING			0
#define VPB_DIGIT			1
#define	VPB_TONEDETECT		2
#define	VPB_TIMEREXP		3
#define	VPB_VOXON			4
#define	VPB_VOXOFF			5
#define	VPB_PLAY_UNDERFLOW	6
#define	VPB_RECORD_OVERFLOW	7
#define VPB_DTMF		8

// solicited events (not maskable)

#define	VPB_PLAYEND			100
#define	VPB_RECORDEND		101
#define	VPB_DIALEND			102
#define	VPB_TONE_DEBUG_END	103
#define	VPB_CALLEND			104

// Event mask values

#define VPB_MRING				(1<<VPB_RING)
#define VPB_MDIGIT				(1<<VPB_DIGIT)
#define VPB_MDTMF				(1<<VPB_DTMF)
#define	VPB_MTONEDETECT			(1<<VPB_TONEDETECT)
#define VPB_MTIMEREXP			(1<<VPB_TIMEREXP)
#define VPB_MVOXON				(1<<VPB_VOXON)
#define VPB_MVOXOFF				(1<<VPB_VOXOFF)
#define	VPB_MPLAY_UNDERFLOW		(1<<VPB_PLAY_UNDERFLOW)
#define	VPB_MRECORD_OVERFLOW	(1<<VPB_RECORD_OVERFLOW)

int WINAPI vpb_enable_event(int handle, unsigned short mask);
int WINAPI vpb_disable_event(int handle, unsigned short mask);
int WINAPI vpb_get_event_mask(int handle);
int WINAPI vpb_set_event_mask(int handle, unsigned short mask);
int WINAPI vpb_get_event_async(VPB_EVENT *event);
int WINAPI vpb_get_event_sync(VPB_EVENT *event, unsigned int time_out);
int WINAPI vpb_get_event_ch_async(int handle, VPB_EVENT *e);
int WINAPI vpb_get_event_ch_sync(int handle, VPB_EVENT *e, unsigned int time_out);
int WINAPI vpb_put_event(VPB_EVENT *event);
void WINAPI vpb_translate_event(VPB_EVENT *e, char s[]);
int WINAPI vpb_set_event_callback(int handle, void (WINAPI *event_callback)(VPB_EVENT *e, void *context), void *context);

/*-----------------------------------------------------------------------*\

							PLAY AND RECORD

\*-----------------------------------------------------------------------*/

// return code for vpb_play_buf_sync and vpb_record_buf_sync

#define	VPB_FINISH		1	

// compression modes

#define	VPB_LINEAR		0	// 128 kbit/s 16 bit linear
#define	VPB_ALAW		1	// 64 kbit/s A-law companded
#define	VPB_MULAW		2	// 64 kbit/s mu-law companded
#define	VPB_OKIADPCM	3	// 32 kbit/s OKI ADPCM
#define	VPB_OKIADPCM24	4	// 24 kbit/s OKI ADPCM

// structures for configuring record and play params

typedef struct {
	char			*term_digits;	// string of digits to terminate collection
} VPB_PLAY;

typedef struct {
	char			*term_digits;	// string of digits to terminate collection
	unsigned int	time_out;		// record terminates after time_out ms
									// if set to 0 (default) no time out
} VPB_RECORD;

// play functions

int WINAPI vpb_play_file_sync(int handle, char file_name[]);
int WINAPI vpb_play_file_async(int handle, char file_name[], int data);
int WINAPI vpb_play_voxfile_sync(int handle, char file_name[],unsigned short mode);
int WINAPI vpb_play_voxfile_async(int handle, char file_name[], unsigned short mode, int data);

int WINAPI vpb_play_buf_start(int handle, unsigned short mode);
int WINAPI vpb_play_buf_sync(int handle, char *buf, unsigned short length);
int WINAPI vpb_play_buf_finish(int handle);
int WINAPI vpb_play_terminate(int handle);
int WINAPI vpb_play_set(int handle, VPB_PLAY *vpb_play);
int WINAPI vpb_play_set_gain(int handle, float gain);
int WINAPI vpb_play_get_gain(int handle, float *gain);

// record functions

int WINAPI vpb_record_file_sync(int handle, char file_name[], unsigned short mode);
int WINAPI vpb_record_file_async(int handle, char file_name[], unsigned short mode);
int WINAPI vpb_record_voxfile_sync(int handle, char file_name[], unsigned short mode);
int WINAPI vpb_record_voxfile_async(int handle, char file_name[], unsigned short mode);
int WINAPI vpb_record_buf_start(int handle, unsigned short mode);
int WINAPI vpb_record_buf_sync(int handle, char *buf, unsigned short length);
int WINAPI vpb_record_buf_finish(int handle);
int WINAPI vpb_record_terminate(int handle);
int WINAPI vpb_record_set(int handle, VPB_RECORD *vpb_record);
int WINAPI vpb_record_set_gain(int handle, float gain);
int WINAPI vpb_record_get_gain(int handle, float *gain);
int WINAPI vpb_record_buf_async(int handle, unsigned short mode,char *mbuf,unsigned long size);

// record terminating reason outputed during a vpb_record_???_async() in 
// the data member of the VPBevents

#define VPB_RECORD_DIGIT			1	// terminated due to Digit String
#define VPB_RECORD_TIMEOUT			2	// terminated due to record timeout
#define VPB_RECORD_ENDOFDATA		3	// terminate due to end of data in buffer
#define VPB_RECORD_MAXDIGIT			4	// terminate due to Maximum digits

/*-----------------------------------------------------------------------*\

							ERROR HANDLING

\*-----------------------------------------------------------------------*/

// Run time error manager modes

#define	VPB_DEVELOPMENT	0	// API function error causes program abort
#define	VPB_ERROR_CODE	1	// API function error returns error code
#define	VPB_EXCEPTION	2	// API function error throw a exception

// Exception class

class VpbException {
public:
	int		code;						// error code
	char	s[VPB_MAX_STR];				// code translated into string
	char	api_function[VPB_MAX_STR];	// api func that threw exception
	
	VpbException(int c, char trans[], char api_function[]);
};

int WINAPI vpb_seterrormode(int mode);
void WINAPI vpb_throw_exception(int c, char trans[], char api_function[]);

/*-----------------------------------------------------------------------*\

							DIALLING

\*-----------------------------------------------------------------------*/

// blind dialling functions

int WINAPI vpb_dial_sync(int handle, char *dialstr);
int WINAPI vpb_dial_async(int handle, char *dialstr);

// Call progress tone ids

#define	VPB_CALL_DISCONNECT	0	
#define	VPB_CALL_DIALTONE	1
#define	VPB_CALL_RINGBACK	2
#define	VPB_CALL_BUSY		3
#define	VPB_CALL_GRUNT		4

typedef struct {