TeleFlow Board API

TeleFlow Board API

From TeleFlow

Jump to: navigation, search

This section defines the TeleFlow Server API function calls and software relationships the used within TeleFlow Server. This document should be helpful for creating applications using TeleFlow Server as the base. Developers of TeleFlow Server software require this document for creating and compiling additional functions into TeleFlow.

This document is to serve as a method for sharing ideas and ensuring all aspects of development and documentation have been accounted for. Additional documents related to the project development may also be included as appendices.

During the design process, all parties involved will need to review the document to ensure accuracy. Please also ensure you do your best to conform to the C++ Programming Practices for TeleFlow.


Contents

Server Code Structure

This section provides a brief description of how the components of the open source environment relate together.

Server Layer


Engine Layer

  • TFEngine.dll
  • xmlutil.dll
  • esctl.dll
  • inet.dll


Generic Board Layer

  • TF Board API (board generic)
  • english.dll
  • french.dll
  • spanish.dll


Specific TeleFlow Board Layer

  • brd_simulator

Note: Other board dlls are available to drive Ai-Logix, Dialogic, NMS Communications etc. Note: Open source competitions will mostly focus in this area.


Hardware Vendor API Layer

  • Vendors API
  • PC Multimedia


API Function Calls

This section describes the list of API function calls.

IV_STATUS Return Values

  • defined in ivr_defs.h
IVR_SUCCESS Function was successful
IVR_HANGUP Caller hung up
IVR_ NOTSUPPORTED Function not supported either by hardware or software
IVR_SHUTDOWN System requested a shutdown and shutdown is permitted
IVR_RELOAD Redundant
IVR_FAIL Function failed due to external conditions such as hardware
IVR_FATAL Function has encountered a critical error and cannot continue
IVR_TIMEOUT Function specific
IVR_BUSY PlaceCall encounters a busy signal
IVR_NO_VOICE AudioVoiceRecognise detects no voice signal
IVR_THRESHOLD AudioVoiceRecognise recognition certainty is below threshold
IVR_GENERIC_TIMEOUT The generic timer was set and not properly handled
IVR_GENERIC_EVENT The generic event was set and not properly handled


Enumerated Board Constants

callMode { newLine, existingLine }

  • defined in brd_generic.h
  • newLine indicates the port is not currently in use
  • existing indicates the port is currently in use

state { good, bad }

  • Redundant

TTSTypes { TTS_FILE_TYPE, TTS_STRING_TYPE }

  • Redundant


Board Variables

bool lineOffHook TRUE if line off hook
int curLine; IVR port that this thread is using (-1 when not in use)
PIVRINFO pInfo; Thread application information
bool bBrdInit; True if board is initialized.
Log* ivLog; Application log
char* TTSDirectory; Text To Speech file directory
int lastLine; Last IVR port on the system
time_t callStart; Time at which a call is placed or answered
time_t callEnd; Time at which the last hang up occurred
BRD_LINE lines[MAX_LINES]; Groundwork for IVR port independent threads? Currently only lines[curLine] contains any useful information
SignalEvent<int>* mySignal; Recvs events from Service/Monitor.
HANDLE hEvent; Signalled on Service/Monitor events.
HANDLE hWaitTimer; Used for handling timeouts.
HANDLE hGenericTimer; Used as a general timer by anyone.
HANDLE* waitObjects; List of wait objects to monitor.
HINSTANCE library; Handle to instance of this .dll for audio resources
unsigned numWaitObjects; No. of objects in 'waitObjects'.
CCriticalSection cs;
const char* speakAudioExtension;


Creator/Destructor

BoardGeneric(PIVRINFO pIVRInfo)

  • relies on pIVRInfo for system event queue mySignal
  • relies on pIVRInfo for board DLL file name
  • loads board DLL
  • derived classes are responsible for board specific initialization

BoardGeneric(void)

  • releases board DLL
  • derived classes are responsible for board specific clean up


Generic Board Functions (Implemented in base class BoardGeneric)

IV_STATUS AudioCopy(char* srcFile, char* dstFile)

  • To be moved to TFEngine


IV_STATUS AudioDelete(char* filename)

  • To be moved to TFEngine


IV_STATUS AudioPlay(const char* filename, bool interruptable, SOUND_FORMAT format, int volLevel, bool fancy)

  • calls derived class AudioStartPlay() with the same parameters and then calls derived class AudioWaitForPlayStop()
  • Message Review Mode (fancy true) is not supported at this level but can be overided at the derived class for implementation (such as for NMS)
  • boards that do not support asynchronous playback can overide this function
  • additional message playback control is available if fancy is true: 
1: rewind 2 seconds
2: pause/resume playback
3: fast forward 2 seconds
4: decrease speed
5: set speed to default
6: increase speed
7: decrease volume
8: set volume to default
9: increase volume
0, *, #:end playback


IV_STATUS AudioRecord(const char* filename, bool interruptable, SOUND_FORMAT format, int volLevel, int maxRecTime, int maxSilence, bool disableBeep)

  • calls derived class AudioStartRecord() with the same parameters and then calls derived class AudioWaitForRecordStop()
  • boards that do not support asynchronous recording can overide this function


IV_STATUS AudioSpeak(char* string, bool interruptable, char* langDir, int volLevel, int spkFormat)

  • speaks string of text using a combination of up to 49 different speech files according to spkFormat:
SPKFMT_DIGITS Currently unused
SPKFMT_NUMBER Currently unused
SPKFMT_DATE Month Day Year (str must be in MM/DD, MM/DD/YY, or MM/DD/YYYY format)
SPKFMT_12HOUR 12 hour clock format, other spkFormat will default to 24 hour clock format (str must be in HH:MM or HH:MM:YY format)
SPKFMT_24HOUR Currently unused
SPKFMT_MONEY Currently unused
SPKFMT_ALPHA Currently unused
SPKFMT_MONTHYEAR Month Year (str must be in MM/DD, MM/DD/YY, or MM/DD/YYYY format)
SPKFMT_MONTHDAY Month Day (str must be in MM/DD, MM/DD/YY, or MM/DD/YYYY format)
  • type of spkFormat needs to be changed from int to SPEAK_FORMAT_TYPE
  • uses audio files in the langDir directory
  • plays audio files at volume level volLevel, currently -3 to 3, by calling board specific AudioPlay()
  • volume level range will be changed to 1 to 10
  • speech can be interrupted if interruptable is true


void ClearGenericEvent(void)

  • clears hGenericEvent


time_t GetCallEndTime(void) const

  • returns the value of callEnd


time_t GetCallStartTime(void) const

  • returns the value of callStart


IV_STATUS GetDigit(char* ivNextTT, int newTime)

  • waits up to newTime for a touch tone and puts the touch tone in ivNextTT
  • calls derived class GetDigits() for 1 digit
  • returns IVR_TIMEOUT if newTime seconds have elapsed with no touch tones received


bool GetLineOnHook(void) const

  • returns true if port is on hook, returns false otherwise


IV_STATUS ProcessSystemEvent(void)

  • gets system event from the event queue mySignal, processes as appropriate and returns either IVR_SUCCESS or IVR_SHUTDOWN


void SetGenericEvent(HANDLE event)

  • sets hGenericEvent to event


IV_STATUS WaitForEvent(BoardEvent* boardEvent, long timeout = FOREVER)

  • waits up to timeout ms for an event from mySignal, hWaitTimer, hGenericTimer, hGenericEvent or a board event
  • copies board event to boardEvent if board event occurs
  • returns IVR_TIMEOUT if timeout ms elapses
  • returns IVR_GENERIC_TIMEOUT if hGenericTimer is signalled
  • returns IVR_GENERIC_EVENT if hGenericTimer is signalled


IV_STATUS WaitForSpecificEvent(BoardEvent* desiredEvent, BoardEvent* boardEvent, long timeout = FOREVER)

  • waits up to timeout ms for an event from mySignal, hWaitTimer, hGenericTimer, hGenericEvent or a until the desired board event occurs
  • copies board event to boardEvent if desired board event occurs

IV_STATUS WaitWhilePaused(void)

  • pause until signalled to proceed
  • only TFSimulator overides this function currently, others simply return IVR_SUCCESS
  • intended for future use


Board Specific Functions (implemented in derived class)

IV_STATUS AudioBeep(void)

  • plays 100 ms 1 kHz tone if there is no touch tone in the board's queue


IV_STATUS AudioPlayEvalMessage(void)

  • plays evaluation message audio


IV_STATUS AudioStartPlay(const char* filename, bool interruptable, SOUND_FORMAT format, int volLevel)

  • starts asynchronous playing of file filename in audio format format at volume volLevel (-3 to 3)
  • volume level range will be changed to 1 to 10
  • current valid SOUND_FORMATS are:
TF_BY_EXTENSION uses file name extension to determine format
TF_VOX Dialogic only: OKI ADPCM 8kHz 4bps
TF_WAV_8KHZ_16BIT NMS, Ai-Logix and TFSimulator only
TF_VCE_24 NMS only
  • playback stops when a touch tone is pressed and interruptable is true and fancy is false, the call is disconnected, or the end of the file is reached


IV_STATUS AudioStartRecord(const char* filename, bool interruptable, SOUND_FORMAT format, int volLevel, int maxRecTime, int maxSilence, bool disableBeep)

  • starts asynchronous recording up to maxRecTime ms of audio to file filename in audio format format at volume volLevel (-3 to 3)
  • volume level range will be changed to 1 to 10
  • doesn't play beep that precedes recording if disableBeep is true
  • current valid SOUND_FORMATS are:
TF_BY_EXTENSION uses file name extension to determine format
TF_VOX Dialogic only: OKI ADPCM 8kHz 4bps
TF_WAV_8KHZ_16BIT NMS, Ai-Logix and TFSimulator only
TF_VCE_24 NMS only
  • records stops when a touch tone is pressed and interruptable is true, the call is disconnected, maxSilence ms of silence elapses, or maxRecTime ms have elapsed


IV_STATUS AudioStopPlay(void)

  • stops play started with AudioStartPlay()


IV_STATUS AudioStopRecord(void)

  • stops record started with AudioStartRecord()


IV_STATUS AudioRecognise(const char* grammar, int timeout, int silenceTimeout)

  • sends up to timeout ms of audio to Nuance Voice Recognition engine using grammar grammar
  • ends audio after silenceTimeout ms of silence


IV_STATUS BlockCalls(void)

  • blocks port so that calls cannot be placed or received


IV_STATUS CallTrigger(const char* triggerList, const char*& trigger, int& triggerInfo, long timeout)

  • waits up to timeout ms for a board level event that is in triggerList, copies a pointer to the event name string to trigger and copies secondary information to triggerInfo
  • returns IVR_TIMEOUT if timeout ms elapse


IV_STATUS FaxQueueAdd(char* fullFile)

  • Adds fullFile to faxFileQ list (creates list if faxFileQ is NULL)
  • currently implemented for NMS only


IV_STATUS FaxQueueClr(void)

  • Clears items in faxFileQ, sets faxFileQ to NULL
  • currently implemented for NMS only


IV_STATUS FaxReceive(char* file, char* SID)

  • Copies the subscriber ID string to SID if SID is not NULL
  • Stores the incoming fax in file


IV_STATUS FaxSend(char* phoneNo, char* ringStr, char* sendSID)

  • calls PlaceCall() phoneNo, waits up to ringStr rings and sends queued faxes upon a succesful fax connection, sending sendSID as the subscriber ID
  • returns the value of PlacCall() if PlaceCall() is unsuccessful


IV_STATUS FlashHook(long flashTime)

  • flashes the port with a duration of flashTime ms


void FlushDigits(void)

  • removes any pending touch tones from the board’s touch tone queue


IV_STATUS GenerateDigits(char* ttStr)

  • generates touch tones for character in ttStr (0...9, A...D, *, # and ,’ or . for pauses)


IV_STATUS GetDigits(unsigned count, char* digits, int newTime, char* ttOkay, char* ttDone)

  • puts touch tones that match those in ttOkay, in the order received, in digits until count touch tones are received, a touch tone from ttDone is received, or newTime seconds expire between touch tones (including before first touch tone)
  • returns IVR_TIMEOUT if newTime seconds have elapsed without a touch tone

IV_STATUS Hangup(bool returnHangup = false, char* pszCause = NULL)

  • sets port on hook
  • pszCause is unused and will be removed
  • returns IVR_SUCCESS if returnHangup is false
  • returns IVR_HANGUP if returnHangup is true


IV_STATUS LoadWebDocument(const char* request, int timeout, const char* filename, SOUND_FORMAT format, int volLevel, char*& result)

  • plays file filename of audio format format at volume volLevel while loading the document specified by request into a string created for result
  • waits for up to timeout ms after file playback finishes for document
  • returns IVR_FAIL if the http request comes back with an error or if the O/S returns a socket error and creates a string with the error code for result
  • returns IVR_TIMEOUT if the host does not respond after 3 attempts that wait 500ms each or if timeout ms elapse after playback of the file filename finishes and creates a string with as much text as has already been received for result
  • returns IVR_NOTSUPPORTED if an unsupported protocol such as https is used


IV_STATUS Pickup(void)

  • sets port off hook
  • returns IVR_HANGUP if line does not connect


IV_STATUS PlaceCall(char* digits, char* callerID, int numrings, callMode mode)

  • sets board off hook if mode is newLine or flash hooks if mode is existingLine
  • passes callerID with the dial string if the protocol is “isd0” (NMS only)
  • dials digits and waits at most 30 seconds for a connection within numrings rings
  • NMS sets @SYS_CALL_STATUS to one of the following values: 
"CED"
"DIALTONE_DETECTED"
"PROCEEDING"
"RING_QUIT"
"SIGNAL"
"SIT_DETECTED"
"TIMEOUT"
"VOICE_BEGIN"
"VOICE_END"
"VOICE_EXTENDED"
"VOICE_LONG"
"VOICE_MEDIUM"
"UNKNOWN"
  • returns IVR_HANGUP if there is an incoming call on the port; returns IVR_TIMEOUT if the call did not connect within numrings rings or 30 seconds; returns IVR_BUSY if a busy signal is detected


IV_STATUS ProcessBoardEvent(BoardEvent* boardEvent, bool& bFound)

  • called by BoardGeneric::WaitForEvent() to do special processing of board events
  • bFound is set to false if the event should not end BoardGeneric::WaitForEvent()


IV_STATUS QueryDigit(char& digit)

  • copies the first touch tone in the board queue to digit or '\0' if there is none


IV_STATUS SetParameter(char* pszParm, DWORD dwParmValue)

  • set hardware parameter pszParm on board to dwParmValue


IV_STATUS Switch(int newPort)

  • connects port with port newPort


IV_STATUS UnblockCalls(void)

  • unblocks previously blocked port so that calls can be placed or received


IV_STATUS UnSwitch(void)

  • unswitches a previously switched port


IV_STATUS WaitForCall(long timeout, int numrings, bool pickup, char* calledDigits, char* callingDigits, char* handsetDisplay)

  • waits up to timeout seconds (or FOREVER) and numrings rings for a call to come in
  • picks up call if pickup is true
  • copies the DNIS to calledDigits if calledDigits is not NULL
  • copies the ANI to callingDigits if callingDigits is not NULL
  • copies the handset display to handsetDisplay if handsetDisplay is not NULL
  • returns IVR_TIMEOUT if a call does not come in before timeout seconds elapse
Retrieved from "http://teleflow.org/wiki/index.php5?title=TeleFlow_Board_API"