Home

ADI Service Developer`s Reference Manual

1. 241 Event data sStr ct re cec ies a i aad vanes eect re EDAX WE ex REY RUNE 241 DONE events e xe eed awa eee e a E 242 Alphabetical event summary nne hne 243 Numerical event enne 245 Events ordered by category 247 Administrative 1 ene sea aea 247 Play and record 1 6 66 248 deans ERE E ENTE Fa eU 248 MIF CV GIES 248 dia eta ib re ERE TIR E es ake ed 249 Tone detector events du Dui em Eae dee De e aca vex Red do 250 Call control primitives nennen emnes 250 Miscellaneous anna sena sena seen nnn 251 Chapter 9 253 Overview of the ADI service 0 6 6 253 ADI CALEPROG
2. deta 66 Starting energy detection cede RR RE 66 Stopping energy detection 1 1 4 666 66 HERES EEE EES 67 Detectirig VOICE actlVIiEy Rr Rr nn ce EE e Ere ate 67 Configuring boards for voice 052222 68 Using voice activity detection 0 68 Sending and receiving FSK data eee eee emnes eene 69 Sending PSK data 69 Terminating FSK data transmission 0 70 Receiving FSK data iere td es AN AAEN A px ra ee 70 Terminating FSK data 70 Performing low level call 1 2 2 2 4 4 112 6 71 Using on board MEFS acrin tat een te riage levine tee Tea aer EY 72 Starting th timere e cats Deme IE RR Re ER Roc RD 72 Stopping the TIMER hs TRI PIE i vias IE RII 72 Chapter 4 Function summary 73 Telephony protocol ennemis 73 Record and play 6 nnam nnn nnn 73 Initiating record and play operation
3. e PacketMedia HMP process Prototype DWORD adiGetRecordStatus ctahd ADI RECORD STATUS info unsigned size Return values Return value SUCCESS CTAERR_BAD_ARGUMENT CTAERR_BAD_SIZE CTAERR_INVALID_CTAHD CTAERR_INVALID_STATE CTAERR_SVR_COMM NMS Communications Description info is NULL size is smaller than the size of DWORD Context handle is invalid Function not valid in the current port state Server communication error Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext info Pointer to the ADI RECORD STATUS structure as shown typedef struct Parms related to RECORD functions DWORD size Returned size GetRecordStatus DWORD reason Reason last record ended Sy DWORD buffercount Counter of buffers submitted ay DWORD frame Number of frames submitted ay DWORD totalbytes Total bytes submitted void buffer Last buffer pointer SUBMITTED gt DWORD bytecount Number of bytes into this buffer DWORD bytesrecorded Total bytes actually recorded 7 DWORD timestarted Actual time started ms units a DWORD underrun Counts underrun events a ADI_RECORD_STATUS Refer to the Details section for field descriptions Amount of memory available at info to receive the ADI RECORD STATUS 117 Function reference ADI Service Developer s Reference Manual
4. joule Slovene NS 4 p 110 NMS Communications ADI Service Developer s Reference Manual Function reference adiGetEEPromData Reads the on board OEM data for a given board Supported board types AG e CG e PacketMedia process Prototype DWORD adiGetEEPromData ctahd unsigned board unsigned size ADI_EEPROM_DATA eepromdata Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext board Board number as specified in the board keyword file size Size of the caller s structure the returned size is enclosed in the eepromdata structure eepromdata Pointer to the returned structure as shown typedef struct DWORD size Sire dnis 2 WORD data 32 EEprom data 8 ADI EEPROM DATA Return values Return value Description SUCCESS CTAERR BAD ARGUMENT NULL pointer was passed for eepromdata CTAERR BAD SIZE size is smaller than the size of DWORD CTAERR INVALID BOARD Invalid board was specified CTAERR INVALID CTAHD Context handle is invalid CTAERR SVR COMM Server communication error Details Use adiGetEEPromData to return OEM information stored on a PROM on the specified board The ctahd argument is used to access the context on which the ADI service was opened The ADI service can be opened in driver only mode if desired In this case no actual board resources are reserved Set the board f
5. 111 on board timers 77 adiStartTimer 192 adiStopTimer 220 starting 72 stopping 72 out of band signaling 71 adiQuerySignalState 139 276 ADI Service Developer s Reference Manual parameters 253 ADI_CALLPROG_PARMS 254 ADI_COLLECT_PARMS 256 ADI_DIAL_PARMS 257 ADI_DTMF_PARMS 259 ADI_DTMFDETECT_PARMS 260 ADI_ECHOCANCEL_STATUS_INFO 125 ADI_ENERGY_PARMS 260 ADI_FSKRECEIVE_PARMS 261 ADI_FSKSEND_PARMS 261 ADI_PLAY_PARMS 261 ADI_RECORD_PARMS 262 ADI_START_PARMS 264 ADI_TONE_PARMS 267 ADI_TONEDETECT_PARMS 268 playing voice data 25 adiGetEncodingInfo 113 adiGetPlayStatus 115 adiModifyPlayGain 128 adiModifyPlaySpeed 130 adiPlayAsync 132 adiPlayFromMemory 136 adiSetNativeInfo 150 adiStartPlaying 170 adiStopPlaying 212 adiSubmitPlayBuffer 226 functions summary of 73 playrec demonstration program 234 recording voice data 20 adiGetEncodingInfo 113 adiGetRecordStatus 117 adiRecordAsync 141 adiRecordToMemory 145 adiSetNativeInfo 150 adiStartRecording 182 NMS Communications ADI Service Developer s Reference Manual adiStopRecording 216 adiSubmitRecordBuffer 228 functions summary of 73 retrieving configuration information 78 adiGetBoardInfo 97 adiGetBoardSlots 100 adiGetBoardSlots32 103 adiGetContextInfo 106 adiGetEEPromData 111 S setting time 149 simultaneous play and record 30 single memory transaction 18 speed 29 system restrictions 30 NMS Communications Index T TCP 73 adiSt
6. 174 adistartP lse 177 RARE er es 179 daa Seek Wa e x inertes ER ER a INR TERRE a 182 adiStartSendingESK i erre e e etia ell ores e D maa eu d eam t aac et ta a eae dane a 186 adiStartSignalDetector exem e REN ERES ERE REX RI 189 adiStartTimmer o sees sere er dextera cave rea e ex e eR Et cerra eA 192 adiStartToneDetector eerie mer e x tas ations EI OR TARTE 194 adiStartTones oA AERA utc ent vot 198 adiStopCallProgress roe ex xs NY ERES xe E a prt enis 201 adiStopGolle ction ee ie reet x enm er ee Ca og x e eR EA RR cakes 203 adiStopDial RUNI RET EE exa er RAT nU ea 204 adiStopDTMFDetector sena ae nnn nnn 206 adiStopEnergyDetector aan 208 adiStopMED et ectoF 2 Eis et e rael Rex a Pee nue EA DEAN v eda a Da pega 210 adiStopPlayilg x sive deny DAA Ret a E P xeu E ee rA a Rr aaa ee ena 212 adiStopProtocol iie e xe Cea E e EE AERA man CREE 213 adiStopRecelvingES K ee nori pite a a AREA AMO E FR re ee el a roles ts 215 216 adiStopSendingESK ipe 217 adiStopSignalD6tector etes dort Fea kk n Fe e n
7. ret adiStartProtocol ctahd nocc NULL NULL ret WaitForSpecificEvent ADIEVN STARTPROTOCOL DONE amp event create mspp RTP endpoint ret mspCreateEndpoint ctahd amp mspAddr amp mspParm amp ephd ret WaitForSpecificEvent MSPEVN CREATE ENDPOINT DONE amp event get cg6xxx board handle ret mspGetFilterHandle msphd MSP FILTER RTPFDX EPH rtp play filter handle ret adiSetNativeInfo ctahd NULL no ingress handle as this is a play only rtp play filter handle amp natpr ctl RIP endpoint filter ID Specified as a destination for audio ret adiPlayFromMemory ctahd ADI ENCODE EDTX AMRNB audio play MemoryBuffer RecordedBytes NULL ret adiStopPlaying ctahd Native record without inband silence and DTMF detection To implement native record functionality without inband silence detection or DTMF detection the application performs the following tasks e Creates a Natural Access event queue and context e Opens the ADI and MSPP services on the context and starts the nocc protocol on the context e Creates an MSPP RTP endpoint and an MSPP record channel on the context e Connects the RTP endpoint with the record channel to create a record connection e Retrieves the filter ID of the jitter filter within the record channel e Supplies the ADI service with information about the RTP audio streams and specifies the desired behavior for native record
8. rvoice fxx rvoice vad fxx qtsignal f54 for CG 6000 C boards 8tsignal f54 for CG 6100C and CG 6500C boards not required for CG 6565 C and CG 6060 C boards ADI Service Developer s Reference Manual Description Contains the echo cancellation functions available in echo v3 x54 as well as comfort noise generation and tone disabling features CG boards only Contains ITU G 723 1 play and record functions for both 5 3 kbit s and 6 3 kbit s rates The codec data is output as raw bytes of the encoded 30 ms frames Contains ITU G 726 ADPCM play and record functions G 726 is a standard for 32 kbit s speech coding Note These functions require more DSP processing time than the functions in voice xxx You cannot run as many actively playing or recording contexts as you can with other speech encodings CG boards only Contains ITU G 729A play and record functions The 8 kbit s codec data is output as raw bytes of the encoded 10 ms frames Contains play and record functions for MS GSM speech encoding at 13 kbit s Similar in operation to gsm_ms m54 except that maximum output of the play function is limited Contains play and record functions for IMA ADPCM speech encoding at 24 kbit s or 32 kbit s Contains the multi frequency receiver function Required for any trunk protocol that uses MF signaling and also by adiStartMFDetector Contains play and record functions for OKI ADPCM speech encoding at 24 kbit
9. XR 218 adiStopTimer odere ee ixi rer eee perd rase DOR eri RII pr E NES 220 adiStopToneDetector von cr E ert e t iet d d Pre xd a e Y RO RE e ee 222 ACISTOPTONES p 224 adiSubmitPlayBU ffer cn eve e drea wove bv via ree Yu rei p Rs 226 adisubmitRecordBuffer 211 snas ase aae nn 228 Chapter 6 Demonstration 231 Summary of the demonstration 231 ctademo c and 11 1 66 6 nnns 231 Host port to port connection 2 232 Play and record 1 66 nna sna sena sena seen 234 Multi threaded application 5 1 6 236 NMS Communications 5 Table of Contents ADI Service Developer s Reference Manual Chapter ZiErrOrs ssisesisccccacccaccccticcccdcacsecsdasecaccsenadeasseiccaceceusdeasnstecccscesacccusene 237 Alphabetical error EE EEE EEE nnn nnn 237 Numerical error nana senses ases nn assa sena sea ae nnn 239 Chapter 8 Events
10. NMS Communications 261 Parameters ADI_RECORD_PARMS ADI Service Developer s Reference Manual Dependent functions adiStartRecording adiRecordToMemory adiRecordAsync Field name Type AGCattacktime DWORD AGCdecaytime DWORD AGCenable DWORD AGCsilenceampl INT32 AGCtargetampl INT32 beepampl INT32 beepfreq DWORD beeptime DWORD DTMFabort DWORD gain INT32 262 Default Units 14 ms 304 ms 0 integer 49 dBm 19 dBm 20 dBm 1000 Hz 200 ms OxFFFF mask 0 dB Description Automatic gain control AGC attack time constant This value affects how quickly the gain is reduced for loud signals Valid AG board CG board and PacketMedia HMP range is 1 through 30000 Not used for QX boards AGC decay time constant This value affects how quickly the gain is increased for soft signals Valid AG board CG board and PacketMedia HMP range is 1 through 30000 Not used for QX boards Flag to enable AGC Set to 1 to enable AGC and 0 to disable it Note AGC must be disabled if you are using voice activity detection Noise threshold for AGC Gain adjustment is suspended for signals below this level Valid AG board CG board and PacketMedia HMP range is 72 through 0 Not used for QX boards Target amplitude for AGC Valid AG board CG board and PacketMedia HMP range is 72 through 0 Valid board range is 42 through Amplitude of the record beep tone Valid AG board CG board an
11. Return values Return value Description SUCCESS pattern Bit mask to assert Specified context s protocol does not allow an out of band signaling pattern CTAERR_FUNCTION_NOT_AVAIL CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function is not valid in the current port state CTAERR_OUTPUT_ACTIVE Specified port is actively dialing CTAERR_SVR_COMM Server communication error Details adiAssertSignal asserts the specified out of band signaling pattern which is either the physical out of band signal bits of digital lines or relates to the control of analog interface boards In both cases four signaling bits are addressed A B C and D often written as ABCD and defined by a bit mask 0x8 0x4 0 2 and 0 1 respectively The following constants are in adidef h and can be combined with the OR operator to assert any group of bits ADI_A_BIT ADI_B_BIT ADI_C_BIT and ADI_D_BIT This function cannot be used unless the current protocol specifically allows it CTAERR_FUNCTION_NOT_AVAIL is returned if the application invokes adiAssertSignal when disallowed by the protocol When using adiAssertSignal and adiStartPulse on AG 4000 AG 4000C AG 4040 AG 4040C or CG boards configured for D4 framing ensure that the C bit and the D bit are set the same as the A bit and the B bit Otherwise the received A bit and B bit at the remote end remains in an indeterminate state For ex
12. ServDesc 0 name svcname ADI ServDesc 0 name svcmgrname ADIMGR ServDesc 0 mvipaddr mode ADI VOICE DUPLEX ServDesc 0 mvipaddr stream 0 ServDesc 0 mvipaddr timeslot fusion timeslot ServDesc 1 name svcname MSP ServDesc 1 name svcmgrname MSPMGR ret ctaOpenServices iphd ServDesc ServiceCount ret WaitForSpecificEvent CTAEVN OPEN SERVICES DONE amp Event printf Failed to receive CTAEVN OPEN SERVICES DONE event return FAILURE Channel Initialization MS PHD ds0 ephd MSPHD rtp ephd Create and init RTP endpoint MSP ENDPOINT ADDR rtpaddr 0 MSP ENDPOINT PARAMETER rtp params TONS rtpaddr size sizeof MSP ENDPOINT ADDR rtpaddr eEpType MSP ENDPOINT RTPFDX rtpagddr nBoard Board NMS Communications 41 Developing applications ADI Service Developer s Reference Manual mspCreateEndpoint ipHd amp rtpaddr amp rtp params amp rtp ephd CU WaitForSpecificEvent MSPEVN CREATE ENDPOINT DONE amp Event 5000 printf Failed waiting for MSPEVN CREATE ENDPOINT DONE RTPI return FAILURE create mspp DSO endpoint MSP_ENDPOINT_ADDR ds0addr 0 ds0addr eEpType MSP ENDPOINT DS0 dsQaddr nBoard Board ds0addr size sizeof MSP ENDPOINT 50 ds0addr EP DS0 nTimeslot fusion timeslot MSP ENDPOINT PARAMETER dsOparms 0 dsOparms size sizeof DS0 ENDPOINT PARMS dsOparms eParmType MSP ENDPOINT 50 dsO
13. not used DWORD userid not used INT32 agliberr last error code after calling AGLIB DWORD channel AG Channel 5f DWORD board AG Board number eu DWORD stream MVIP stream of this port 5 DWORD timeslot MVIP slot of this port DWORD mode MVIP mode of operation of this port af DWORD maxbufsize maximum board buffer size 7 char 12 Current Protocol DWORD state port state 4 DWORD stream95 MVIP 95 base stream number ADI CONTEXT INFO Refer to the Details section for a description of these fields size Amount of memory available at info which must be large enough to receive the ADI CONTEXT INFO size return value Return values Return value Description SUCCESS CTAERR BAD ARGUMENT info is NULL CTAERR BAD SIZE size is smaller than the size of DWORD CTAERR INVALID CTAHD Context handle is invalid CTAERR SVR COMM Server communication error 106 NMS Communications ADI Service Developer s Reference Manual Function reference Details Use adiGetContextInfo to return information about the current state of a specified context Up to size bytes of the ADI_CONTEXT_INFO structure are copied to the address at info If size is greater than or equal to sizeof ADI_CONTEXT_INFO the complete structure is copied The number of bytes actually copied is returned in the ADI_CONTEXT_INFO size field Note If you are using the Natural Call Control
14. 4100 8100 8000 8000 8000 8000 16000 3000 4000 11000 22000 667 800 667 15 Developing applications ADI Service Developer s Reference Manual Encoding format Description Sample Sample Frame Frame Data rate size rate size time bytes sec bits Hz bytes ms ADI_ENCODE_EDTX_G723_6 ITU G 723 1 N A 8000 26 30 800 6 3 kbit s with EDTX headers ADI_ENCODE_EDTX_G723 ITU G 723 1 N A 8000 26 30 800 with EDTX headers ADI_ENCODE_G726 ITU G 726 4 8000 40 10 4000 ADPCM 32 kbit s ADI_ENCODE_EDTX_G726 ITU G 726 4 8000 42 10 4000 ADPCM 32 kbit s with EDTX headers ADI_ENCODE_G726_16 ITU G 726 2 8000 Variable Variable 2000 ADPCM 16 kbit s ADI_ENCODE_G726_24 ITU G 726 3 8000 Variable Variable 3000 ADPCM 24 kbit s ADI_ENCODE_G726_32 ITU G 726 4 8000 Variable Variable 4000 ADPCM 32 kbit s ADI_ENCODE_G726_40 ITU G 726 5 8000 Variable Variable 5000 ADPCM 40 kbit s ADI_ENCODE_G729A ITU G 729A N A 8000 10 10 1000 8 kbit s ADI_ENCODE_EDTX_G729A ITU G 729A N A 8000 12 10 1000 8 kbit s with EDTX headers ADI_ENCODE_IMA_24 IMA ADPCM 4 6000 36 10 3600 24 kbit s ADI_ENCODE_IMA_32 IMA ADPCM 4 8000 46 10 4600 32 kbit s ADI_ENCODE_VOX_32 ADPCM 4 8000 40 10 4000 32 kbit s ADI_ENCODE_GSM MS GSM N A 8000 130 80 1625 13 kbit s Note The Voice Message service has equivalent encoding formats with names that begin with VCE_ 16 NMS Communications ADI Se
15. RD size DTMFabort gain novoicetime silencetime INT32 silenceampl WOR D silencedeglitch DWORD beepfreq INT32 beepampl DWORD beeptime WORD AGCenable INT32 AGCtargetampl INT32 AGCsilenceampl DWORD AGCattacktime DWORD AGCdecaytime ADI RECORD PARMS Note Fields in bold are not applicable to the native play and record feature Refer ADI RECORD PARMS on page 262 for field descriptions and valid values NMS Communications Size of this structure Abort on DTM Recording gain in dB After voice has been detected Qualif level for silence Deglitch while qualifying silence ms Beep for record SLC parms used if silence det Length of initial silence to stop Recording ms use 0 to deactivate nitial silence detection Length of silence to stop recording ms Use 0 to deactivate dBm Beep frequency Hz Beep amplitude dBm Beep time ms 0 beep AGC parms Enable AGC use 1 to activate Target AGC level dBm Silence level dBm Attack time ms Decay time ms Ad B mie a 7 pu bid 5 eu e e e iff e 145 Function reference ADI Service Developer s Reference Manual Return values Return value Description SUCCESS ADIERR_INVALID_CALL_STATE Function not valid in the current call state CTAERR_BAD_ARGUMENT Inval
16. Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Play operation is not currently active CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state 4 CTAERR_SVR_COMM Server communication error Details Use adiModifyPlayGain to alter the gain applied to voice data as it is being transmitted The gain remains set only for the current play operation instance Values specified out of range are limited by the range See also adiModifyPlaySpeed adiPlayAsync adiPlayFromMemory adiStartPlaying adiStopPlaying 128 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 129 Function reference ADI Service Developer s Reference Manual adiModifyPlaySpeed Sets the playback speed for the duration of the active play operation Supported board types e AG e CG Prototype DWORD adiModifyPlaySpeed CTAHD ctahd int speed Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Percentage of change to apply to the original recording where 100 percent is no change Valid range of change depends on the capabilities of the hardware and DSP files installed speed T Return values Return value Description SUCCESS CTAERR FUNCTION NOT ACTIVE Play is not currently active CTAERR INVALID CTAHD Context handle is invalid CTAERR INVALID STATE Function no
17. Use the voice activity detector with any ASR application that is recording with one of the following encoding formats e ADI_ENCODE_MULAW e ADI_ENCODE_ALAW e ADI_ENCODE_PCM8M16 Voice activity detection does not interfere with other existing capabilities such as DTMF detection and echo cancellation NMS Communications 67 Developing applications ADI Service Developer s Reference Manual Configuring boards for voice detection To configure the system for voice activity detection edit the board keyword file as follows For these boards Add this DSP file To this keyword rvoice_vad m54 DSP C5x x Files y rvoice vad f54 DSP C5x x Files For example pie Corll Files hut rvoice_vad To configure the PacketMedia HMP process for voice activity detection set the value of the EnableVAD keyword to Yes For example EnableVAD Yes Configure dynamic buffer allocation on the board to prevent host underruns You can also configure CG boards for voice activity detection by defining a DSP resource pool and specifying rvoice_vad as the resource definition Resource 0 Definitions dtmf det_all amp rvoice_vad rec_alaw amp rvoice_vad rec play_alaw Note QX boards do not support voice activity detection Using voice activity detection Voice activity detection and voice activity detection messaging are disabled by default To enable voice activity detection call adiCommandRecord on an actively running
18. bufsize Size of buffer to send parms Pointer to FSK send parameters as follows NULL designates default values Return values Return value SUCCESS CTAERR_BAD_ARGUMENT CTAERR_FUNCTION_ACTIVE CTAERR_INVALID_CTAHD CTAERR_INVALID_STATE CTAERR_SVR_COMM 186 typedef struct DWORD size Size of this structure ay DWORD noseizureflag No channel seizure when set P INT32 level Transmit output scaling dBm DWORD seizetime Length of channel seizure in ms ml DWORD marktime Length of the initial mark signal in ms DWORD baudrate Baud rate only 1200 supported S ADI_FSKSEND_PARMS Refer to ADI_FSKSEND_PARMS on page 261 for field descriptions Description Function argument had an invalid value or a required pointer argument was NULL Function already active Context handle is invalid Function not valid in the current port state Server communication error NMS Communications ADI Service Developer s Reference Manual Function reference Events Event Description ADIEVN_FSK_SEND_DONE Generated by the ADI service when the send function terminates The event value field contains one of the following termination conditions CTAERR_xxx or ADIERR_xxx Function failed CTA_REASON_FINISHED Buffer submitted was sent in its entirety CTA_REASON_RELEASED Call terminated CTA_REASON_STOPPED Stopped by application request Details The following DS
19. ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values a Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_SEQUENCE Attempt made to stop a function that is already being stopped CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Description ADIEVN_TONES_DONE When the tone generation function is stopped the ADI service generates a DONE event with the value reason CTA_REASON_STOPPED Details Use adiStopTones to terminate tone generation started by either adiStartTones or adiStartDTMF You can restart tone generation and any other functions requiring voice output when you receive the DONE event For more information refer to Generating tones on page 52 224 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 225 Function reference adiSubmitPlayBuffer ADI Service Developer s Reference Manual Submits a buffer of data for a play operation initiated by adiPlayAsync Supported board types CG e PacketMedia process Prototype DWORD adiSubmitPlayBuffer CTAHD ctahd void buffer unsigned size unsigned flags m Return values m _ _ Return value SUCCESS
20. printf Board Number d n info board printf Stream Slot Mode d d info stream info timeslot switch info mode case ADI FULL DUPLEX puts ADI FULL DUPLEX break Case ADI VOICE DUPLEX S RUES ADI VOICE DUPLEX break ADI_SIGNAL_DUPLEX 8 puts ADI SIGNAL DUPLEX break default if info mode amp ADI VOICE INPUT printf VOICE INPUT if info mode amp ADI VOICE OUTPUT printf VOICE OUTPUT if info mode amp ADI SIGNAL INPUT printf SIGNAL INPUT if info mode amp ADI SIGNAL OUTPUT printf SIGNAL OUTPUT WM 29 break is return SUCCESS 108 NMS Communications ADI Service Developer s Reference Manual Function reference adiGetDigit Retrieves a digit from the front of the ADI service internal digit queue Supported board types e PacketMedia process Prototype DWORD adiGetDigit CTAHD ctahd char digit Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext digit Pointer to a character to store the digit copied from the digit queue Valid digit values are the ASCII characters 0 through 9 number sign and asterisk as well as A B C and If the digit queue is empty digit receives a value of zero Return values Return value Description SUCCESS CTAERR_BAD_ARGUMENT digit is a NULL point
21. 1 6 October 2005 DEH LBG Natural Access 2005 1 SP 1 1 7 July 2006 SRG Natural Access 2005 1 SP 2 1 8 February 2009 DEH Natural Access R8 1 Last modified January 22 2009 Refer to www nmscommunications com for product updates and for information about support policies warranty information and service offerings 2 NMS Communications Table Of Contents Chapter 1 Introduction 7 Chapter 2 Overview of the ADI 9 ADI service definition sioe cle a eee 9 Using ADI with the Natural Call Control service 9 ADI terminology EC QU XEM Eque 9 Setting up the Natural Access 2 0 2 10 Initializing Natural 8 10 Creating event queues and 0 10 OPENING SERVICES 2 serch EUM 11 Linking with the ADI 0 81 12 Chapter 3 Developing applications e eee eee eere nnne nnn nnn nnn 13 Recording and 4 0 6 66 enne rese 13 Voice encoding formats RAN RR n NR KNEE 13 Data transfer method
22. 268 NMS Communications 1 0 DSP files DSP file summary This topic lists the DSP files needed for particular ADI service functions Specify the files to be loaded in the board keyword file Use NMS OAM to load DSP files onto boards For more information refer to the board installation and developer s manual DSP files ending in dsp have mu law and A law versions The names shown here are for the mu law version A law files have appended to the file name For example the A law version of voice dsp is voice_a dsp Some DSP files have versions with _j appended to the file name For example the V 23 version of adsir dsp is adsir_j dsp Note DSP files for CG 6000 C CG 6100C and CG 6500C boards use an f54 file extension CG 6565 C and CG 6060 C boards use an f41 file extension AG boards CG boards Description adsir _j m54 adsir _j xx Contains the caller ID function that decodes the modem burst occurring between the first and second rings on a loop start line This file also contains the FSK data receiver Use adsir xxx if one of the loop start protocols is used and the parameter adilps cidsupport is set to 1 Use this file for adiStartReceivingFSK CJ is the V 23 variant adsix j m54 adsix j fxx Contains the FSK data transmitter Use this file for adiStartSendingFSK CJ is the V 23 variant callp m54 callp fxx Contains voice and tone detectors used for call progress detection and for general tone dete
23. 79 adiAssertSigihal RM Ra E dE ea aai 80 adiC llectDigitS 82 1 1 1 1 85 ACIGCOMMANARECOM INE PR Hed aa ia 91 adiFl shDigitQUueue insita ete ua qa RR RYMER 95 adiGetBoardInfOo cipit RR ER EE RUNE REX E CORTO A eA TET E 97 adiGetBoardSlots Rid c di edel PEE bius 100 adiGetBoardSl0ts32 Rea RR RR A MERE 103 adiGetcontextInfOo iio eta e ha TRUM CEU X e ERROR RA I M EK EIE 106 adiGetDigi E 109 AGIGETEEPFOMD Ata ts cies cessed ew ang PER E ERA 111 adiGetEncodingInfo 113 adiGetPlayStatus 2 2 maaa deett de exo cedo ese tes 115 RARE ERR AE ERE NR RAE ERE 117 adiGetTimeStambp i E ERI rare Tae eee 119 4 NMS Communications ADI Service Developer s Reference Manual Table of Contents e e e t AR AS e RR era 121 ee nennen nennen nna nna nna 123 adiModifyPlayGain cisi eter rv x a
24. ADI Service Developer s Reference Manual 9000 62162 18 COMMUNICATIONS 100 Crossing Boulevard Framingham MA 01702 5406 USA www nmscommunications com ADI Service Developer s Reference Manual No part of this document may be reproduced or transmitted in any form or by any means without prior written consent of NMS Communications Corporation 2009 NMS Communications Corporation All Rights Reserved Alliance Generation is a registered trademark of NMS Communications Corporation or its subsidiaries NMS Communications Natural MicroSystems AG CG CX QX Convergence Generation Natural Access Natural Access MX CT Access Natural Call Control Natural Media NaturalFax NaturalRecognition NaturalText Fusion Open Telecommunications Natural Platforms NMS HearSay AccessGate MyCaller and HMIC are trademarks or service marks of NMS Communications Corporation or its subsidiaries Multi Vendor Integration Protocol MVIP is a registered trademark of GO MVIP Inc UNIX is a registered trademark in the United States and other countries licensed exclusively through X Open Company Ltd Windows NT MS DOS MS Word Windows 2000 and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and or other countries Clarent and Clarent ThroughPacket are trademarks of Clarent Corporation Sun Sun Microsystems Solaris Netra and the Sun logo are trademarks or registered trademarks of Sun Microsy
25. ADIERR_TOO_MANY_BUFFERS CTAERR_BAD_ARGUMENT CTAERR_BAD_SIZE CTAERR_FUNCTION_NOT_ACTIVE CTAERR_INVALID_CTAHD CTAERR_INVALID_SEQUENCE CTAERR_INVALID_STATE CTAERR_SVR_COMM 226 Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext buffer Pointer to buffer containing voice data to be played size Size of buffer bytes flags Set to if the given buffer is the last in the message otherwise set to 0 Description Application is out of synchronization with the play operation Submit buffers only when requested buffer is NULL size is not a multiple of framesize for the encoding in adiPlayAsync Either voice is not playing or the play operation was not initiated by calling adiPlayAsync Context handle is invalid adiStopPlaying was already invoked or the ADI_PLAY_LAST_BUFFER flag was already set in a previous call to adiSubmitPlayBuffer or adiPlayAsync Function not available in the current port state Server communication error NMS Communications ADI Service Developer s Reference Manual Function reference Events Event Description ADIEVN_PLAY_BUFFER_REQ Generated by the ADI service when a buffer with voice data is required ADIEVN_PLAY_DONE Generated by the ADI service when the play operation terminates with a reason value field of CTAERR_xxx or ADIERR_xxx Play failed CTA_REASON_DIGIT Aborted due to DTMF CTA_REASON_FINISHED Applic
26. CTAERR_SVR_COMM Server communication error Events Event Description ADIEVN_MF_DETECT_DONE DTMF detector is no longer running The event value field contains one of the following CTA_REASON_RELEASED Call terminated CTA_REASON_STOPPED Function stopped by adiStopMFDetector CTAERR_xxx or ADIERR_xxx DTMF detector failed ADIEVN_MF_DIGIT_BEGIN MF digit detected on ADIEVN_MF_DIGIT_END MF digit detected off NMS Communications 167 Function reference ADI Service Developer s Reference Manual Details The following DSP file must be loaded to the board before running adiStartMFDetector For these boards Load this DSP file The standard DSP file See DSP file summary on page 269 for DSP file descriptions Refer to the board installation and developer s manual for a table of MIPS usage for all functions Use this function to enable detection of MFs multi frequency tones Stop the function by calling adiStopMFDetector You must disable DTMF detection using adiStopDTMFDetector before initiating MF detection as there are some overlapping frequency ranges in which both a DTMF and an MF event are reported Likewise when the application is finished with MF detection re enable DTMF detection adiStartMFDetector if DTMFs are desired ADIEVN_MF_DIGIT_BEGIN and ADIEVN_MF_DIGIT_END are generated for every MF tone detected Each event contains an ASCII representation character of the MF digit in the event valu
27. Function reference ADI Service Developer s Reference Manual See also adiGetDigit adiStartDTMFDetector adiStopDTMFDetector Example int myGetDigits CTAHD ctahd char digits int maxdigits ADI_COLLECT_PARMS parms CTA_EVENT event mobigalies ctaGetParms ADI COLLECT PARMID amp parms sizeof parms parms firsttimeout 4000 wait 4 seconds for first digit parms intertimeout 2000 wait 2 seconds between digits adiCollectDigits ctahd digits maxdigits amp parms while 1 myGetEvent amp event see ctaWaitEvent example switch event id ADIEVN_COLLECTION_DONE if event value CTA_REASON_RELEASED return MYDISCONNECT remote hang up shar MS PES SEO return MYFAILURE AG Access API error else if strlen digits return MYFAILURE no digits provided else Reid ioi Glen my break ADIEVN CALL DISCONNECTED In case this event was on the way up when we started collection Wait for collection done event break ADIEVN DIGIT BEGIN ADIEVN_DIGIT_END Typically don t want digit events Wait for the Ore Viele s break 84 NMS Communications ADI Service Developer s Reference Manual Function reference adiCommandEchoCanceller Sends a data array containing raw commands to an actively running echo c
28. G723 ADI ENCODE EDTX G723 6 or ADI ENCODE EDTX G723 5 use the native record path To disable the native feature in the ADI NATIVE CONTROL structure set the mode to ADI IVR ONLY Because the native record mode responds to silence as well as to audio data the ADI port requires DSP resources for silence detection 152 NMS Communications ADI Service Developer s Reference Manual Function reference The ADI_NATIVE_CONTROL structure contains the following fields Field Description size Size of the structure in bytes mode ADI_NATIVE use the ADI service to play and record voice data directly to and from RTP endpoints associated with MSPP service connections ADI_IVR_ONLY use the PSTN play or record path play_encoding Native play data encoding format See Recording and playing on page 13 fora complete list rec_encoding Native record data encoding format See Recording and playing for a complete list frameformat Frame format in record buffers 0 Variable frame size with compressed silence 1 Variable frame size with expanded silence 2 Fixed frame size with compressed silence 3 Fixed frame size with expanded silence include2833 RFC2833 markers in record buffers 0 Disable 1 Enable payloadID Payload type used in egress RTP packets as defined in RFC3551 nsPayload Payload format of egress RTP packets 0 Standard payload format 1 Nonstandard payload format vadFlag Send SID frames 0 Enable defa
29. adiStopTimer stops the timer started with adiStartTimer Once the timer has stopped a DONE event is generated Stop timer event The following table lists the stop timer event Description ADIEVN_TIMER_DONE When the timer is stopped a DONE event is generated with the value field set to CTA_REASON_STOPPED 72 NMS Communications 4 Function summary Telephony protocol functions After setting up the ADI service you must start a telephony protocol on each context to perform telephony activities The NCC service provides a null protocol NOCC for applications that do not require call control Refer to the NMS CAS for Natural Call Control Developer s Manual for a list of telephony protocols and parameters and for information about controlling calls under specific trunk control protocols TCPs Record and play functions The ADI service provides functions for recording and playing speech data Initiating record and play operations Choose a set of functions to initiate record and play operations as appropriate to your application s data transfer method according to the following table Operation Memory transaction Asynchronous Callback adiPlayFromMemory adiPlayAsync adiStartPlaying adiRecordToMemory adiRecordAsync adiStartRecording Terminating record and play operations The ADI service provides the following functions to stop record and play regardless of the data transfer method Fun
30. if myret SUCCESS if bytesrecorded gt trimsize bytesrecorded trimsize else bytesrecorded 0 return myret 148 Sy n n A Ey i po SUCCESS NULL NMS Communications ADI Service Developer s Reference Manual Function reference adiSetBoardClock Sets the time on an AG or a CG board Supported board types AG e CG e PacketMedia process Prototype DWORD adiSetBoardClock CTAHD ctahd unsigned board unsigned long time Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext board Board number as specified in the board keyword file time Number of seconds elapsed since 1 1 70 Return values Return value Description SUCCESS CTAERR_DRIVER_SEND_FAILED Invalid board CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_SVR_COMM Server communication error Details Use adiSetBoardClock to update the time on an AG board or a CG board affecting the timestamp in all events that originate on the board board does not have to be the same board that the ADI service is opened on but it must be the same family of board AG or CG If you are opening the ADI service only to set the clock set services 0 mvipaddr mode to 0 zero in the call to ctaOpenServices so that no timeslot is used See also adiGetTimeStamp Example int mySetBoardClock CTAHD ctahd unsigned board time t lti
31. process Prototype DWORD adiGetBoardSlots32 CTAHD ctahd unsigned board unsigned mode unsigned maxslot ADI_TIMESLOT32 slotlist unsigned numslots Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext board Board number as specified in the board keyword file mode Stream capability which can be either ADI_FULL_DUPLEX both voice and signaling streams or ADI_VOICE_DUPLEX voice only I maxslot Maximum number of entries in slotlist array _ slotlist Pointer to the ADI_TIMESLOT array defined as typedef struct BYTE stream Eire ge 2 ADI_TIMESLOT32 I numslots Returned number of entries Return values m Return value Description SUCCESS CTAERR_BAD_ARGUMENT slotlist is NULL but maxslot is not zero or maxslot is 0 zero but slotlist is not NULL or numslots is NULL or invalid mode _ CTAERR_INVALID_BOARD board does not exist CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_SVR_COMM Server communication error NMS Communications 103 Function reference ADI Service Developer s Reference Manual Details Use adiGetBoardSlots32 to query the available MVIP stream slot pairs configured for a given board The ctahd argument is used to access the context on which the ADI service was opened The ADI service can be opened in driver only mode
32. 011 reorder ineffective other 101 vacant code 111 no circuit available Call progress analysis terminated by the application 155 Function reference ADI Service Developer s Reference Manual Event Description ADIEVN_CP_TDD Detected a TDD TTY device tone ADIEVN_CP_VOICE Call progress analysis detected voice The event value field contains one of the following ADI_CP_VOICE_BEGIN ADI_CP_VOICE_MEDIUM ADI_CP_VOICE_LONG ADI_CP_VOICE_EXTENDED ADI_CP_VOICE_END Details The following DSP files must be loaded to the board before running adiStartCallProgress For these boards Load these DSP files callp m54 ptf m54 callp f54 ptf 54 The standard QX DSP file Refer to DSP file summary on page 269 for DSP descriptions Refer to the board installation and developer s manual for a table of MIPS usage for all functions Use this function to start the call progress analysis operation This is the same functionality utilized by call control It can be used by applications that are not using standard call control or by any application during the connected state Caution Modifying the following fields in ADI_CALLPROG_PARMS can compromise your application s ability to interact with the telephone network voicetoneratio qualtonetime1 qualtonetime2 qualvoicetime1 qualvoicetime2 leakagetime noiselevel The call progress analysis operation always terminates when any of the following events occur
33. 11 Path number on which tone was detected e 0 Send path or echo canceller reference path e 1 Receive path 4 3 2 1 0 Level of the tone dB The tone level is equal to bits 4 0 x 3 dBm0 Dynamic goes from 0 to 93 0 Precision is 1 5 dB Examples e 0 0 0 1 1 9 dBmO e 0 0 1 0 1 15 dBmO Word 2 indicates the frequency or frequencies detected Because templates be programmed for a range of tones it is possible to detect multiple tones within the same template The following formula is used 2 x cos 2x x 8000 Examples e 15 0 7FFFh F 0 Hz lt lt 15 0 3254h F 1748 Hz e 15 0 896Ah F 2613 Hz When a tone is detected the program scans all templates and locks itself on the first template that satisfies the frequency and level detected Program templates appropriately to deal with this behavior For example e Template 2 800 1300 Hz e Template 3 1000 1020 Hz 88 NMS Communications ADI Service Developer s Reference Manual Function reference In this example when a 1010 Hz tone appears the program sends back an event associated with template 2 because it is the first template that meets all criteria for the detection Thus DCE detection is programmed on template exclusively Once tone is detected no path switching is performed until the end of detection If bit 9 of command A is set to 1 silence duration is computed according t
34. 86 NMS Communications ADI Service Developer s Reference Manual Function reference Command B Use the second command to specify the type of tone to be detected Word Description Valid range Typical values 1 Tone number 0 through 3 2 Maximum frequency 300 through 2100 15 for 3000 CED 3 Minimum frequency 300 through 2100 15 for CED 3000 Level 32 Compute the value using the following formula 17030 x pow 10 level 10 0 where level is in dBm in the range 42 to 0 5 Qualification time ms 0 through 32767 500 for CED Tone number 0 is reserved for CED detection phase reversal and amplitude modulation detection Templates 1 through 3 can be set to any value The template is deactivated when maximum frequency is set to 0 Command C Use the third command to modify the default configuration for CED detection including phase reversal detection and amplitude modulation Word Description Valid Typical range values 1 Maximum periodicity ms phase reversal 0 through 480 32767 2 Minimum periodicity ms phase reversal 0 through 420 32767 3 Maximum range of amplitude amplitude modulation detection A 0 through 6554 tolerance is taken by the program 32767 no detection 4 Periodicity amplitude modulation detection 0 through 67 The program on periodicity requirements takes a 20 to 25 percent 32767 tolerance 5 Time out before path switching send receive path switch 0 through 60 The
35. ADIERR_INVALID_CALL_STATE Function not valid in the current call state CTAERR_BAD_ARGUMENT Invalid encoding selected or NULL buffer pointer passed CTAERR_BAD_SIZE size is less than one frame CTAERR_FUNCTION_ACTIVE Record is already active or the energy detector is active CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_NOT_IMPLEMENTED Function not implemented CTAERR_OUTPUT_ACTIVE Record failed because there is another active output function CTAERR_RESOURCE_CONFLICT Silence detector is in use by adiStartEnergyDetector CTAERR_SVR_COMM Server communication error Events Event Description ADIEVN_RECORD_DONE The value field contains one of the following termination reasons or error codes CTA_REASON_DIGIT Aborted due to DTMF CTA_REASON_NO_VOICE No voice detected CTA_REASON_RELEASED Call terminated CTA_REASON_STOPPED Stopped by application request CTA_REASON_TIMEOUT Record time limit reached CTA_REASON_VOICE_END User stopped speaking CTAERR_FUNCTION_NOT_AVAIL Required DSP file not loaded on the board CTAERR_xxx or ADIERR_xxx Record failed NMS Communications 183 Function reference ADI Service Developer s Reference Manual Details When recording or playing speech files on AG boards a specific DSP file must be loaded for each encoding type For QX boards the standard DSP file supports the valid encoding types For m
36. AG and boards have an alternate DSP file dtmfe used specifically with echo cancellation To load dtmfe Step Action 1 Locate the reference to dtmf xxx the DSP C5x x Files y keyword DSP C5x x Files for CG boards where xxx is either dsp m54 or f54 There may be no file extension 2 Change dtmf to dtmfe 3 Save the changes and re initialize the board Echo cancellers of moderate length and adaptation time typically provide improvement of 10 to 15 dB in DTMF cut through performance Controlling echo NMS Communications echo cancellers can be used to implement echo control for the following applications Application Implementation PSTN terminal Improves DTMF detection DTMF cut through or automatic speech recognition performance by eliminating leakage of playback audio into the receive signal path This behavior typically applies to IVR or voice mail applications of NMS Communications boards Network echo Eliminates talker echo so that peer to peer human communications do not suffer the control annoying effects This behavior typically applies to IP telephony gateway applications on NMS Communications boards This topic presents e Echo cancellation examples e Echo canceller components e Specifying echo canceller parameters e Configuring boards for echo cancellation e Recommendations for controlling echo Echo cancellation examples DTMF cut through example In an IVR application the user ty
37. Developing applications ADI Service Developer s Reference Manual Initiating play The ADI service provides three functions to initiate playing speech The function used depends upon the data transfer method selected Use this function When the adiPlayFromMemory Application submits a single memory buffer to the ADI service adiStartPlaying ADI service invokes application callback when data is needed Note Applications running in client server mode do not support adiStartPlaying adiPlayAsync ADI service generates a buffer request event when more data is needed The application asynchronously submits play buffers in response The ADI service returns SUCCESS if the start playing command is successfully sent to the board Terminating play The play function terminates when the ADI service delivers ADIEVN_PLAY_DONE regardless of the transfer method selected The event value field contains the termination reason as follows If Then play ends with The application submitted a buffer with the CTA_REASON_FINISHED ADI_LASTBUFFER_SUBMITTED flag and the buffer finished playing The call was released by either party CTA_REASON_RELEASED A DTMF digit specified in the abort mask was entered by the remote CTA_REASON_DIGIT party The application aborted play by calling adiStopPlaying CTA_REASON_STOPPED The play was aborted by the speech recognizer CTA_REASON_RECOGNITION Playing voice data in callback mode In callback mod
38. Hz dBm ms IDU ms ADI Service Developer s Reference Manual Description Type of signaling e O DTMF e 1 Pulse Not applicable for the PacketMedia HMP process 2 MF US Do not modify Amount of delay associated with the comma character Valid range is 0 through 65535 Bandwidth of the first frequency of the dial tone detector Valid AG board CG board and PacketMedia HMP range is 20 through 800 Valid QX board range is 40 through 2000 Bandwidth of the second frequency of the dial tone detector Valid AG board CG board and PacketMedia HMP range is 20 through 800 Valid QX board range is 40 through 2000 First or only dial tone frequency Valid AG board CG board and PacketMedia HMP range is 330 through 3600 Valid QX board range is 1 through 4000 Second dial tone frequency Set this value to 0 zero to detect a single frequency Valid AG board CG board and PacketMedia HMP range is 330 through 3600 Valid QX board range is 1 through 4000 Minimum signal amplitude to qualify for dial tone detection Valid AG board CG board and PacketMedia HMP range is 40 through 0 Valid QX board range is 48 through 0 Minimum duration of a qualified tone to be considered dial tone Valid range is 0 through 32767 Do not modify Detects interrupted dial tones stuttered dial tone in certain countries Defaults to 0 zero which indicates that dialing can proceed as soon as a dial t
39. d DWORD dtmfofftime OFF duration of DTMFs ms DWORD dialtonewait max time to wait for dialtone ms Sf precise dialtone parameters DWORD tonefreq1 frequency to detect rd DWORD tonebandwl bandwidth ui DWORD tonefreg2 2nd frequency to detect dualtone DWORD tonebandw2 2nd bandwidth ny INT32 tonequalampl broadband qual level in dBm DWORD tonequaltime qualification time in ms DWORD tonereflevel reserved a DWORD reserved reserved mise INS 0 f DWORD tonetotaltime total time for dial tone with interruptions my ADI DIAL PARMS In some instances the dtmfofftime can increase by 20 ms Refer to ADI DIAL PARMS on page 257 for field descriptions 158 NMS Communications ADI Service Developer s Reference Manual Function reference Return values Return value Description SUCCESS CTAERR_BAD_ARGUMENT digitstr is NULL CTAERR_FUNCTION_ACTIVE Function already started CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_OUTPUT_ACTIVE Open port failed because the stream and slot are already opened on another port CTAERR_SVR_COMM Server communication error Events Description ADIEVN_DIAL_DONE The reason in the value field can contain either an error or one of the following CTA_REASON_FINISHED CTA_REASON_RELEASED CTA_REASON_STOPPED Details For AG boards and CG boards adiStartDial
40. event value field contains CTA_REASON_STOPPED stopped by application request Details Use adiStopSendingFSK to abort the transmission of FSK data initiated by adiStartSendingFSK For more information refer to Sending and receiving FSK data on page 69 NMS Communications 217 Function reference ADI Service Developer s Reference Manual adiStopSignalDetector Stops the out of band signaling bit detector Supported board types Prototype DWORD adiStopSignalDetector CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values Eee Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_SEQUENCE Attempt was made to stop a function that is already being stopped CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Description ADIEVN_SIGNAL_DETECT_DONE After signal detection stops the ADI service generates a DONE event with a value field of CTA_REASON_STOPPED Details Use adiStopSignalDetector to disable detection of incoming out of band signaling bits After calling this function incoming out of band bit transitions are not reported This function is incompatible with standard call control Contexts running a standar
41. operations If you do not specify a buffer size on the command line z playrec retrieves the board physical buffer using adiGetEncodingInfo The demonstration is constructed so that the play and record functions are synchronous within the application This is a single port single threaded demonstration Note adiStartPlaying and adiStartRecording and consequently this demonstration program are not supported while Natural Access is running in client server mode Usage playrec options where options are Option Use this option to Featured functions adiGetEncodingInfo adiPlayAsync adiRecordAsync adiStartPlaying adiStartRecording adiSubmitPlayBuffer adisubmitRecordBuffer 234 NMS Communications ADI Service Developer s Reference Manual Demonstration programs Running playrec The following procedure assumes that you are using an AG 2000 DID board with a 2500 type telephone connected to one of the lines To run playrec Step 1 2 Action Navigate to the nms ctaccess demos playrec directory Start playrec by entering the following command at the prompt playrec b n s n m r n z n Make sure that you specify the proper board and timeslot The default value for both arguments is zero You are prompted to record a brief message The prompt is played using asynchronous buffer submission and ADIEVN PLAY BUFFER REQ is displayed on your screen assuming you did not specify an app
42. parms Pointer to an ADI START PARMS structure as shown NULL uses default parameter values typedef struct DWORD size size of this structure ADI CALLCTL PARMS callctl call control parms z ADI_DIAL_PARMS dial dial control parms y ADI DTMFDETECT PARMS dtmfdet DTMF detection parms ADI_CLEARDOWN_PARMS cleardown cleardown detect parms ADI_ECHOCANCEL_PARMS echocancel echo canceller parms e ADI START PARMS Refer to ADI START PARMS on page 264 for field descriptions Return values Return value Description SUCCESS CTAERR BAD ARGUMENT protoname is invalid or NULL or parms contains an invalid size field CTAERR INVALID CTAHD Context handle is invalid CTAERR INVALID STATE Function not valid in the current port state CTAERR SVR COMM Server communication error Events Event Description ADIEVN STARTPROTOCOL DONE If successful the value field contains REASON FINISHED otherwise the value contains an error code such as CTAERR BAD ARGUMENT Invalid protocol name the protocol associated with protoname was not specified in the configuration file 174 NMS Communications ADI Service Developer s Reference Manual Function reference Details Use adiStartProtocol to specify the NOCC protocol The function initializes the ADI service and by default starts the DTMF detector The ADI_START_PARMS data structure consists of the following substructures e ADI_CALLC
43. size 12 Invoke adiRecordToMemory to begin recording audio data adiRecordToMemory ctahd buf bufsize rec param 13 Invoke adiStopRecording stop recording audio data adiStopRecording ctahd Example The following example shows how to perform a native record operation without decoding ret ctaCreateQueue NULL 0 amp hCtaQueueHd ret ctaCreateContext hCtaQueueHd 0 Record amp ctahd ServiceCount 2 ServDesc 0 name svcname ADI ServDesc 0 name svcmgrname ADIMGR ServDesc 0 mvipaddr mode ADI VOICE DUPLEX ServDesc 0 mvipaddr stream 0 ServDesc 0 mvipaddr timeslot record_timeslot ServDesc 1 name svcname MSP ServDesc 1 name svcmgrname MSPMGR ret ctaOpenServices ctahd ServDesc ServiceCount ret WaitForSpecificEvent CTAEVN OPEN SERVICES DONE amp Event IP Channel Initialization MSPHD 450 ephd MSP NO CONNECT MSPHD rtp ephd Create and init RTP endpoint amp mspCreateEndpoint ctaHd amp rtpaddr amp rtp params rtp ephd if WaitForSpecificEvent MSPEVN CREATE ENDPOINT DONE amp Event 5000 printf Failed waiting for MSPEVN_CREATE_ENDPOINT_DONE agmen Wy p return FAILURE chanaddr nBoard Board chanaddr channelType G711RecordChannel chanaddr FilterAttribs MSP FCN ATTRIB RFC2833 chan params size sizeof MSP CHANNEL PARAMETER chan params channelType G711RecordChannel chan params ChannelParms VoicePar
44. size of this structure gt DWORD mode echo canceller mode DWORD filterlength fiter length msec Sy DWORD adapttime filter adaptation time msec DWORD predelay offset of input sample msec ay INT32 gain receive gain db Sy ADI ECHOCANCEL PARMS For field descriptions and valid values refer to ADI START PARMS on page 264 Return values Return values Description SUCCESS em ADIERR_INVALID_CALL_STATE Function not valid in the current call state CTAERR_FUNCTION_NOT_ACTIVE Echo canceller function was not started CTAERR_INVALID_CTAHD Context handle is invalid lt CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_SVR_COMM Server communication error Events s d Event Description ADIEVN ECHOCANCEL STATUS Generated if the echo canceller enables send status mode For more information about this mode of operation refer to echocancel mode in ADI START PARMS The echo canceller stores the status information in an event buffer The information is arranged according to the ADI ECHOCANCEL STATUS INFO structure in adidef h QX 2000 boards do not support the sending of echo canceller status information NMS Communications 123 Function reference ADI Service Developer s Reference Manual Details The following DSP file must be loaded to the board before running adiModifyEch
45. ADI Service Developer s Reference Manual Example 96 NMS Communications ADI Service Developer s Reference Manual adiGetBoardInfo Function reference Obtains information about a board Supported board types e PacketMedia process Prototype DWORD adiGetBoardInfo CTAHD ctahd unsigned board unsigned size ADI_BOARD_INFO boardinfo Description typedef struct SUCCESS NMS Communications ctahd Context handle returned by ctaCreateContext or ctaAttachContext board Board number as specified in the board keyword file Size of boardinfo structure boardinfo Pointer to the ADI BOARD INFO structure as shown DWORD size Size of this structure DWORD boardtype Physical board type ADI_BOARDTYPE_xxx DWORD serial Serial number sf DWORD ioaddr Base IO address y DWORD intnum Interrupt number Sy DWORD bufsize Buffer size DWORD freemem Available memory z BYTE daughterboardid 4 Daughterboard IDs 0 none DWORD totalmips Total gross DSP MIPS DWORD trunktype of digital or analog trunk DWORD numtrunks Number of trunks ADI BOARD INFO Return values Return value Description CTAERR BAD ARGUMENT boardinfo pointer is NULL CTAERR BAD SIZE size is smaller than the size of DWORD CTAERR INVALID CTAHD Context handle is invalid CTAERR SVR COMM Ser
46. ADIEVN_ENERGY_DETECTED and ADIEVN_SILENCE_DETECTED are received as the detector changes between these states ADIEVN_ENERGY_DETECT_DONE can also be returned with the value field set to an error or CTA_REASON_STOPPED if adiStopEnergyDetector is called Note You cannot start the energy detector while a record operation is active unless both ADI_RECORD novoicetime and ADI RECORD silencetime are 0 zero when the record operation was started For a voice record operation the relevant parameters VCE_RECORD novoicetime VCE_RECORD silencetime For more information refer to Detecting energy on page 66 166 NMS Communications ADI Service Developer s Reference Manual Function reference adiStartMFDetector Enables the detection of MFs multi frequency tones Supported board types CG Prototype DWORD adiStartMFDetector CTAHD ctahd unsigned mftype _ Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext mftype Type of MF tone to detect ADI_MF_US ADI_MF_CCITT_FORWARD ADI_MF_CCITT_BACKWARD Return values Return value Description SUCCESS ADIERR_INVALID_CALL_STATE Function not valid in the current call state CTAERR_FUNCTION_ACTIVE Function already started CTAERR_FUNCTION_NOT_AVAIL mf dsp not loaded to the board CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state
47. After the dial operation stops the ADI service generates a DONE event with the value field set to CTA_REASON_STOPPED Details Use adiStopDial to stop the dial function started by adiStartDial You can restart the dial operation and any other operation requiring voice output after you receive the DONE event 204 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 205 Function reference ADI Service Developer s Reference Manual adiStopDTMFDetector Stops DTMF detection Supported board types e PacketMedia process Prototype DWORD adiStopDTMFDetector CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_SEQUENCE Attempt made to stop a function that is already being stopped CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Event Description ADIEVN_DTMF_DETECT_DONE After the detector stops the ADI service generates a DONE event with the value field set to CTA_REASON_STOPPED Details Use adiStopDTMFDetector to disable detection of DTMFs Detection is automatically enabled by the call con
48. CG 4000 4000 2000 4040 4040 Minimum echo return loss ERLmin 6 dB 6 dB 6 dB For all values of ERL greater than ERLmin the echo canceller delivers the expected performance If the real ERL is less than the ERLmin the echo canceller does not function correctly Maximum echo return loss enhancement ERLE 33 dB 33 dB 33 dB Non linear processor loss An additional loss 36 dB 36 dB 12 dB introduced in the reception path only when pure 24 dB echo is received no near end speech Typical convergence time on speech Convergence Less than 1 second Less than 1 Less time depends on the transmitted signal double Obtained using second than 1 talk events and adaptation time parameter for AG echo_v3 x54 For Obtained using second 2000 AG 2000C AG 4000 AG 4000C AG 4040 echo x54 the typical echo_v3 x54 AG 4040C CG boards and on echo return loss convergence time on of the network The convergence time can be speech is lt 4 seconds greater than the values presented in this table Recommendations for controlling echo Transmission level planning and echo For IP telephony applications proper audio levels and echo are tightly coupled It is desirable to provide adequate listening levels but increasing system gains anywhere in the four wire trunk portion of a connection can make proper echo control difficult to attain under a wide range of telephony equipment and connection s
49. CTAHD ctahd ADI RECORD STATUS recordstatus adiGetRecordStatus ctahd amp recordstatus sizeof recordstatus A termination condition of 0 indicates either record in progress or none yet started in this CTA context e printf Termination condition x bytes recorded d n recordstatus reason recordstatus bytesrecorded 118 NMS Communications ADI Service Developer s Reference Manual Function reference adiGetTimeStamp Converts an event timestamp to a count of the seconds elapsed since January 1 1970 Supported board types e CG e PacketMedia process Prototype DWORD adiGetTimeStamp CTAHD ctahd DWORD msgtime unsigned long timesec unsigned timems Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Leer enne msgtime Event time stamp c timesec Pointer to returned seconds timems Pointer to returned milliseconds Return values Return value Description SUCCESS CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_SVR_COMM Server communication error Details Use adiGetTimeStamp to convert an event timestamp to a count of the number of seconds elapsed since 00 00 00 January 1 1970 The msgtime is the CTA_EVENT timestamp value which is in millisecond units with a 10 millisecond resolution This function converts the msgtime into timesec seconds and timems milliseconds since midn
50. Callback transfer The ADI service manages the buffers and invokes an application callback function to retrieve or store data The functions used to initiate play or record depend upon the data transfer method selected as shown in the following table Operation Single memory Asynchronous Callback adiPlayFromMemory adiPlayAsync adiStartPlaying Record adiRecordToMemory adiRecordAsync adiStartRecording adiStartPlaying and adiStartRecording are not supported when Natural Access is running in client server mode For more information refer to the Natural Access Developer s Reference Manual Single memory transaction If the application invokes adiPlayFromMemory or adiRecordToMemory it supplies a single buffer that is retained by the ADI service for the duration of the function The ADI service divides the application buffer into physical segments and performs all handshaking with the board Note A buffer submitted for playing can be shared by multiple instances of the play function within the same process but the buffer submitted for recording must be unique for each active recording instance When the ADI service delivers ADIEVN PLAY DONE ADIEVN RECORD DONE to the application the buffer is then available for reuse or disposal 18 NMS Communications ADI Service Developer s Reference Manual Developing applications In summary e Single memory transaction is relatively simple and minimizes application intera
51. Context handle is invalid CTAERR_INVALID_SEQUENCE Attempt made to stop a function that is already being stopped CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Description ADIEVN_RECORD_DONE After recording stops and the final buffer is presented the ADI service generates a DONE event with the value field set to CTA_REASON_STOPPED Details Use adiStopRecording to stop the recording operation started by either adiStartRecording adiRecordToMemory or adiRecordAsync You can restart recording when you receive the DONE event For more information refer to Recording on page 20 216 NMS Communications ADI Service Developer s Reference Manual Function reference adiStopSendingFSK Stops sending frequency shift key FSK data Supported board types Prototype DWORD adiStopSendingFSK CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values ee Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Event Description ADIEVN_FSK_SEND_DONE Generated by the ADI service when the send operation terminates The
52. DCE detector switches back and forth from send to receive until a 32767 tone is detected This activity provides 50 percent MIPS load for tone detection on both send and receive paths The function needs about 50 ms to detect a tone and lock itself 6 Silence threshold echo cancellation reactivation Use the following N A 0021h formula to compute the value 17030 x pow 10 level 10 0 where level is in dBm in the range 42 to 0 7 Silence duration 200 NA through Since fax has a longer silence period echo cancellation could be 5000 reactivated during fax protocol after the specified amount of time NMS Communications 87 Function reference ADI Service Developer s Reference Manual ADIEVN_ECHOCANCEL_TONE contains two words of information about the tone that was detected Word 1 indicates if the tone was a DCE tone or a single tone Bit number Description 15 Type of event If bit 15 0 DCE tone detected e Bit 14 Amplitude modulation detected e Bit 13 Phase reversals detected Bit 12 Silence detected after DCE detection Examples e 14 13 12 0 0 0 ANS e 14 13 12 0 1 0 ANS e 14 13 12 1 0 0 ANSam e 14 13 12 1 1 0 ANSam e 14 13 12 x x 1 silence after ANSxxx detection If bit 15 1 single tone detected Bits 14 13 12 template s number detected Examples e 14 13 12 0 0 1 template 1 e 14 13 12 0 1 0 template 2 e 14 13 12 0 1 1 template 3
53. PARMS 3 te er aser adc Fea v Due 254 ADI COLLECT PARMS x e EP VA Vikas AW RA wa E 256 ADP DIAL PARMS Mexx eS Eva od Er Olea REN TURN ade aidan twee he 257 ADI DTMF PARM S a e Rer eA e Ere WARE IHR RAF DARIN D MEA ER ERE M 259 ADI DTMFDETEGT PARMS e ave ee RR REX VA REV RE ANA a Da a dn 260 ADI ENERGY PARM S c etm ne e cd e ot i n C e ie nee tn 260 ADI FSKREGEIVE PARMS iere rent ERE MM RAE RE EN ee ER 261 ADI FSKSEND PARMS o Reeve i vale 261 ADIT PEAY PARM Seles vc rer me vade e Red ur ER FERE n avid tetas 261 ADI RECORD PARM S xen era E E REPRE Te ERRARE RT 262 ADI START ert e sav RR RE VAR ERR a EVA ETUR 264 5 ex rr et nter ea ee Or e e Fe del RR e a oe 267 ADI TONEDETECT ra Enna MR KR DE RR NEP e ERE 268 Chapter 10 DSP 269 DSP Tile sumtriary cte cecinere Dea uar x E a IE ONERE RAW EXTA tats ERES 269 6 NMS Communications 1 Introduction The ADI Service Developer s Reference Manual describes how to develop an application using the ADI service in the Natural Access environment It al
54. Reference Manual Using on board timers The ADI service supports one on board timer per context on a board This on board timer has 10 ms resolution The timer generates periodic events You specify both the period and number of events when invoking adiStartTimer Starting the timer To start the timer call adiStartTimer and pass a context a timeout value and an event count value A DONE event is generated when the timer expires If the count value is greater than one a tick event is generated for each expiration of the timeout with a DONE event for the final expiration The timer can be reset or restarted with an additional call to adiStartTimer When restarted previous timer definitions are discarded and the timer begins with the new parameters Note Unlike most Natural Access asynchronous functions the timer is not automatically stopped when a call is released Start timer events The following table lists the start timer events Event Description ADIEVN_TIMER_DONE Once the timer has completed expired the ADI service generates a DONE event with the value field set to CTA_REASON_FINISHED A DONE event is received with an error in the value field only if the board has an error If the timer is stopped by calling adiStopTimer the value field is CTA_REASON_STOPPED ADIEVN TIMER TICK If count is greater than 1 the ADI service generates a tick event for the first count 1 expirations Stopping the timer
55. SUCCESS ADIERR_INVALID_CALL_STATE CTAERR_BAD_ARGUMENT CTAERR_FUNCTION_ACTIVE CTAERR_INVALID_CTAHD CTAERR_INVALID_STATE CTAERR_OUTPUT_ACTIVE CTAERR_SVR_COMM 136 ctahd Context handle returned by ctaCreateContext or ctaAttachContext encoding Encoding type See Voice encoding formats on page 13 for a complete list buffer Pointer to voice data buffer bufsize Number of bytes stored at the address in buffer bufsize can be arbitrarily large parms 1 to play parameters according to the following structure NULL uses default values parms related to adiStartPlaying DWORD size size of this structure A DWORD DTMFabort abort on DTMF INT32 gain Recording gain in dB DWORD speed initial speed in percent maximum play speed in percent Note Fields bold not applicable to the native play and record feature Refer to ADI_PLAY_PARMS on page 261 for field descriptions and valid values Description Function not valid in the current call state Either invalid encoding or NULL buffer Function already started Context handle is invalid Function not valid in the current port state Play failed because there is another active output function Server communication error NMS Communications ADI Service Developer s Reference Manual Events Event ADIEVN_PLAY_DONE Details Description Generated by the ADI service when playing terminates The event size field cont
56. United States MF name Specific digit address MF ST3P MF KP2 MF ST2P See also adiStartTones 162 NMS Communications ADI Service Developer s Reference Manual Function reference adiStartDTMFDetector Starts DTMF detection Supported board types e PacketMedia process Prototype DWORD adiStartDTMFDetector CTAHD ctahd ADI_DTMFDETECT_PARMS parms Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext parms Pointer to DTMF detection parameters according to the following structure NULL value uses the default values typedef struct DWORD size size of this structure 7 DWORD columnfour l detect sdonu t INT32 onqualampl min input lev to qual tone dBm DWORD onthreshold reserved S DWORD onqualtime qualify time of DTMF ms 51 INT32 offqualampl min input lev of valid DTMF dBm DWORD offthreshold reserved DWORD offqualtime disqualify time for tone ms sy ADI DTMFDETECT PARMS Refer to ADI DTMFDETECT PARMS on page 260 for field descriptions Return values Return value Description SUCCESS ADIERR INVALID CALL STATE Function not valid in the current call state CTAERR FUNCTION ACTIVE Function already started CTAERR INVALID CTAHD Context handle is invalid CTAERR INVALID STATE Function not valid in the current port state CT
57. and disables native play record mode for the adi port ADI_NATIVE ADI_IVR_ONLY Encoding type for native play refer to for a complete list of ADI_ENCODING xxx If the mode is ADI_NATIVE and this encoding matches the one specified in a subsequent play command the native path will be used the PSTN play or record path will be used Encoding type for native record refer to adidef h for a complete list of values If the mode is ADI_NATIVE and this encoding type matches the one specified in a subsequent record command the native path will used otherwise the PSIN play or record path will be used Specifies record frame format include REC2833 markers in record buffers RTP payload type for egress nonstandard payload indicator for Egress RTP 0 default RFC3267 AMR payload is used 1 AMR IF2 frames are packed as payload VAD enable 1 disable 0 sending of SID Refer to the Details section for field descriptions 151 Function reference ADI Service Developer s Reference Manual Return values Return value Description SUCCESS ADIERR_INVALID_CALL_STATE Function not valid in the current call state CTAERR_FUNCTION_ACTIVE Function already started CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_SVR_COMM Server communication error Details Use adiSetNativeInfo to set the native play and record parameters The native play and
58. application The last buffer before the DONE event can be a partial buffer The DONE event itself does not include a buffer of data The record operation terminates when the application receives ADIEVN RECORD DONE Note The final buffer submitted is not always returned to the application If the application dynamically allocates buffers it must keep track of submitted buffers to free any outstanding buffers when record is done For optimum performance the bufsize must be the largest frame multiple that fits in one board buffer You can obtain this size by calling adiGetEncodingInfo refer to the maxbufsize argument For proper operation each buffer must be submitted while the previous buffer is being filled If a buffer is submitted too late an underrun occurs and the input data is lost You can monitor for underruns by checking the ADI RECORD UNDERRUN bit in the value field of ADIEVN RECORD BUFFER FULL Use adiGetRecordStatus to retrieve a count of underruns that occurred since record started Note You cannot initiate a record operation while playing voice or generating tones unless you disable the record beep by setting either ADI RECORD beeptime or ADI RECORD beepfreq to 0 zero You cannot start a record operation if the energy detector is active unless both ADI RECORD novoicetime and ADI RECORD silencetime are 0 zero For more information refer to Recording on page 20 See also adiCommandRecord adiRecordToMemo
59. blocking and returns back to the application immediately after starting the pulse The out of band signal pattern is either the physical out of band signal bits of a digital protocol or it relates to the control of an analog interface board In both cases four signaling bits A B C and D often written as ABCD and defined by a bit mask 0x8 0 4 0 2 and Ox1 respectively used The following constants are adidef h They can be combined by using the OR operation to define any group of bits ADI_A_BIT ADI_B_BIT ADI_C_BIT and ADI_D_BIT For example if the line is off hook a O zero is pulsed for example generate a flash hook When using this function with an analog interface board refer to the hardware installation manual for the analog interface board for specific information on how the A and B bits affect the telephone line This function is not available if the current protocol reserves use of out of band signaling Typically call control protocols take over the line signaling and the application does not need to assert or reset line codes or pulses explicitly adiStartPulse overrides adiAssertSignal For the duration of the pulse the line pattern is determined by the signaling state specified by adiStartPulse It then reverts to the pattern previously asserted by adiAssertSignal For more information refer to Performing low level call control on page 71 178 NMS Communications ADI Service Developer s Refer
60. board range is 90 through dtmfampl2 INT32 dtmfofftime DWORD 80 ms Duration of the silence time between each digit Valid AG board CG board and PacketMedia HMP range is 0 through 65534 Valid QX board range is 0 through 2047 dtmfontime DWORD 80 ms Duration of each DTMF or MF digit Valid AG board CG board and PacketMedia HMP range is 0 through 65534 Valid QX board range is 0 through 2047 flashtime DWORD 500 ms Amount of time to assert the on hook signaling pattern for a flash character Valid AG board and CG board range is 0 through 65535 Valid QX board range is 0 through 32767 interpulse DWORD 700 ms Inter digit time for pulsed dialing Valid AG board and CG board range is 0 through 30000 Valid QX board range is 0 through 32767 longpause DWORD 5000 ms Amount of delay associated with the period character Valid range is 0 through 65535 maketime DWORD 40 ms Make off hook duration for dial pulses Valid AG board and CG board range is 0 through 30000 Valid QX board range is 0 through 32767 NMS Communications 257 Parameters Field name Default method DWORD 0 reserved DWORD 0 shortpause DWORD 2000 tonebandw1 DWORD 40 tonebandw2 DWORD 40 tonefreg1 DWORD 350 tonefreq2 DWORD 440 tonequalampl INT32 28 tonequaltime DWORD 50 tonereflevel DWORD 0xB000 tonetotaltime DWORD 0 258 Units mask internal ms Hz Hz Hz
61. callback function could interfere with event processing for any context opened on the same queue Playing voice data in asynchronous mode In asynchronous mode the application transfers voice data from the host to the board by cooperatively exchanging commands and events with the ADI service as shown Application ADI service ADIEVN_PLAY_BUFFER_REQ adiSubmitPlayBuffer ADIEVN_PLAY_BUFFER_REQ adiSubmitPlayBuffer ADIEVN_PLAY_DONE lt gt lt gt Transferring voice data asynchronously during play follows this process 1 The application invokes adiPlayAsync 2 The ADI service sends ADIEVN_PLAY_BUFFER_REQ whenever the board starts a new buffer 3 The application invokes adiSubmitPlayBuffer in response to ADIEVN_PLAY_BUFFER_REQ 4 Steps 2 and 3 are repeated until play completes and the ADI service generates ADIEVN_PLAY_DONE NMS Communications 27 Developing applications ADI Service Developer s Reference Manual The following illustration shows the life cycle for play in asynchronous transfer mode ADIEVN_PLAY_BUF_REQ adiSubmitPlayBuffer adiPlayAsync ADIEVN_PLAY_DONE adiStopPlaying ADIEVN_PLAY_DONE Stopping The three states for asynchronous play transfer are State Description Idle Play is not active Active When the application invokes adiPlayAsync the ADI service sends the initial buffer to the board and transits to the active state The play state remains active u
62. containing the current signaling pattern It is a mask of the following constants found in adidef h ADI_A_BIT ADI_B_BIT ADI_C_BIT and ADI_D_BIT Details The AG 2000 AG 2000C and AG 2000 BRI boards require signal m54 to be loaded Use adiQuerySignalState to query the out of band signaling detector for the current state of the signaling bits These signaling bits can be the actual T1 E1 digital carrier signaling bits or they can relate to specific detectors of analog interface boards for example a ring detector In both cases the ADI service recognizes four signaling bits A B C and D often written as ABCD and defined by the constants ADI A BIT ADI ADI and ADI D BIT Note This function can be called only if you started detection using adiStartSignalDetector NMS Communications 139 Function reference ADI Service Developer s Reference Manual Example 140 NMS Communications ADI Service Developer s Reference Manual Function reference adiRecordAsync Initiates recording in asynchronous buffer mode Supported board types e PacketMedia process Prototype DWORD adiRecordAsync CTAHD ctahd unsigned encoding unsigned maxmsec void buffer unsigned bufsize ADI_LRECORD_PARMS parms Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext encoding Encoding type See Voice encoding f
63. data 27 terminating a record function 20 274 ADI Service Developer s Reference Manual automatic gain control AGC 25 automatic speech recognition ASR 67 examples of echo cancellation 57 recommendations for controlling echo 64 B board configurations 78 echo cancellation 61 voice detection 68 call progress 74 adiStartCallProgress 154 adiStopCallProgress 201 managing 43 callback transfers 18 playing voice data 26 terminating a record function 20 collecting digits 53 adiCollectDigits 82 adiFlushDigitQueue 95 adiGetDigit 109 adiInsertDigit 121 adiPeekDigit 131 adiStopCollection 203 functions summary of 75 controlling echoes 57 adiCommandEchoCanceller 85 adiModifyEchoCanceller 123 functions summary of 75 CTA EVENT 241 CTA MVIP ADDR 11 adiGetBoardInfo 97 adiGetBoardSlots 100 adiGetBoardSlots32 103 adiGetEEPromData 111 adiGetTimeStamp 119 adiSetBoardClock 149 adiSetNativeInfo 150 NMS Communications ADI Service Developer s Reference Manual ctaCreateContext 10 ctaCreateQueue 10 ctademo c 231 ctademo h 231 CTAERR_XXX_XXX 237 239 ctaGetTimeStamp 119 ctaInitialize 10 ctaOpenServices 11 ctaWaitEvent 241 adiGetDigit 109 D demonstration programs 231 hostp2p 232 playrec 234 threads 236 detecting energy 66 adiStartEnergyDetector 165 adiStopEnergy Detector 208 detecting tones 50 adiStartEnergyDetector 165 adiStartToneDetector 194 adiStopEnergyDetector 208 adiStopToneDetector 222 functions summa
64. function is either SUCCESS or an error code For asynchronous functions a return value of SUCCESS indicates the function was initiated subsequent events indicate the status of the operation Refer to Alphabetical error summary on page 237 for a list of all errors returned by the ADI service functions Events If events are listed the function is asynchronous and is complete when the DONE event is returned If no events are listed the function is synchronous Additional information such as reason codes and return values is provided in the value field of the event Refer to Alphabetical event summary on page 243 for details of all ADI service events DSP file Lists the DSP file that is required for this function Refer to DSP file summary on page 269 for a list of DSP files Example Example functions that start with Demo are excerpts taken from the demonstration code which is shipped with the product Example functions that start with my are excerpts taken from sample application programs The notation indicates additional code which is not shown NMS Communications 79 Function reference ADI Service Developer s Reference Manual adiAssertSignal Asserts an out of band signaling pattern to the line Supported board types Prototype DWORD adiAssertSignal CTAHD ctahd unsigned pattern Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext
65. functionality NMS native play and record advantages When an application plays or records audio data over an IP network typically the application must encode or decode the data Audio data is often encoded compressed format such as G 711 or G 723 1 Encoding or decoding the audio stream can consume system resources and incrementally degrade the quality of the data When an application records audio data using native record the audio is stored in the NMS EDTX extended discontinuous transmission format without encoding the data The application can then either play back the audio data directly to a network interface or transfer the data to the PSTN interface through a decoder NMS Communications 31 Developing applications ADI Service Developer s Reference Manual The following illustration shows the advantages of native play and record Native play and record RTP ADI service endpoints Transcode Transcode Record PSTN Implementing NMS native play and record NMS native play and record uses an NMS proprietary format called EDTX extended discontinuous transmission to store and play back codec frames EDTX formatting incorporates an optional silence compression scheme that uses silence frames in the recorded stream to indicate periods of silence Native play and record supports the following encoding types e AMR CG boards only e G 711A G 711U e G 72
66. generates periodic events Specify both the period timeout and number of events count Stop the timer by calling adiStopTimer Reset or restart the timer with another call to adiStartTimer When the timer is restarted previous timer definitions are discarded and the timer begins with the new parameters Note Unlike most other ADI service asynchronous functions the timer function is not stopped automatically when a call is released For more information refer to Using on board timers on page 72 192 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 193 Function reference ADI Service Developer s Reference Manual adiStartToneDetector Starts detecting a precise tone Supported board types e PacketMedia HMP process Prototype DWORD adiStartToneDetector ctahd unsigned toneid unsigned freq1 unsigned bandwi unsigned freq2 unsigned bandw2 ADI TONEDETECT PARMS parms Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext ml toneid ID or instance of the detector The range is 1 through 6 If the current protocol is providing cleardown detection toneid 1 is not available freqi First or only frequency to detect in Hz IL bandw1 Bandwidth of the first frequency in Hz i freq2 The second frequency in Hz if the tone contains two freq
67. if desired In this case no actual board resources are reserved Set the board field in the MVIP_ADDR structure passed to ctaOpenServices to ADI_AG_DRIVER_ONLY This function also works with a context that has the ADI service opened on actual MVIP streams and timeslots If mode is zero the slots returned are the DSP addresses that correspond to actual trunks whether or not they are actually connected For example if an AG 2000 board is partially populated only the slots that contain line interfaces are returned Note The DSPs are automatically connected to the trunk if the telephony bus is not enabled If mode is not zero the function returns only those streams capable of supporting the given mode The base stream for the given mode is returned in the ADI_TIMESLOT32 stream field Examples e Foran AG 2000 board stream 18 is voice and stream 19 is signaling If adiGetBoardSlots32 is invoked with mode set to ADI_FULL_DUPLEX the function returns an array of eight ADI TIMESLOT32 structures each with the stream field set to 18 18 0 7 e Foran AG 2000 board stream 18 is voice and stream 19 is signaling If adiGetBoardSlots32 is invoked with mode set to ADI VOICE DUPLEX the function returns an array of 16 ADI TIMESLOT32 structures each with the stream field set to 18 or 19 18 0 7 19 0 7 For details on MVIP addressing refer to the Switching Service Developer s Reference Manual The maxslot argument is the
68. is active and then absent The following illustration shows generic tone characteristics Energy 4 Interpulse delay lt The ADI service uses precise tone detector a broadband tone detector to distinguish tones from voice data Precise tone detection The precise tone detector analyzes in band audio at specific frequencies to detect the following types of tones e Busy e Reorder e SIT special information tone e CED generated by fax terminals or modems e TDD TTY generated by devices for the hearing impaired e Number unassigned The application specifies which of these tones to detect by configuring the precmask in ADI_CALLPROG_PARMS If the busy tone detection is not enabled the ADI service takes more time to discern the busy tone using broadband tone detection If SIT detection and CED detection are not enabled these tones cannot be detected The precqualtime parameter determines the duration in which the tones are qualified This parameter applies to all three tones defined in this topic Set it to the time required to detect the tone of shortest duration 44 NMS Communications ADI Service Developer s Reference Manual Developing applications Broadband tone detection The broadband detection method uses simple high and low pass frequency discrimination together with broadband energy measurements over time to qualify network tones For ex
69. modify volume at any time while the play function is active by calling adiModifyPlayGain The default value of the gain is 0 dB no gain Gain can be set to any value in the range of 54 dB to 24 Controlling speed during play The playing speed can also be adjusted for some encodings To modify the play speed call adiModifyPlaySpeed during a currently active play Speed control is available for the following encoding formats e ADI_ENCODE_NMS_16 e ADI_ENCODE_NMS_24 e ADI_ENCODE_NMS_32 e ADI_ENCODE_NMS_64 e ADI_ENCODE_OKI_24 e ADI_ENCODE_OKI_32 If you invoke adiModifyPlaySpeed for a play operation with data in any other encoding format the play operation continues at its original speed Note The PacketMedia HMP process and the QX 2000 board do not support adiModifyPlaySpeed To enable speed control increase the maxspeed play parameter stored in ADI_PLAY_PARMS from its default value of 100 When play is started with a higher value of maxspeed the necessary DSP resources are allocated to support increased speed You can start play with a fast speed up to maxspeed by changing the value of the speed parameter in the function call For the AG boards and the CG boards slow down up to 50 percent of normal speed is supported Note Starting play with maxspeed greater than 100 requires additional DSP resources beyond that required for playing at normal speed To determine whether your boards and configuration can support speed
70. number of ADI TIMESLOT32 instances in the application supplied slotlist array The ADI service returns the number of ADI TIMESLOT32 instances written to the s otlist in the numslots variable This value is in the range zero to maxslot inclusive Note If maxslot is 0 zero and slotlist is NULL numslots returns the actual number of slots without copying any data adiGetBoardSlots32 can be used with adiGetBoardInfo to dynamically configure an application s contexts ctaOpenServices is called with a board number and MVIP stream slot to open the ADI service The application can retrieve a complete list of configured stream slot pairs for any board with adiGetBoardSlots32 104 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 105 Function reference ADI Service Developer s Reference Manual adiGetContextInfo Retrieves configuration information about a specified context Supported board types e PacketMedia HMP process Prototype DWORD adiGetContextInfo CTAHD ctahd ADI CONTEXT INFO unsigned size Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext _ info Pointer to a buffer to receive the information The ADI_CONTEXT_INFO structure is shown typedef struct User accessible CONTEXT INFO structure DWORD size returned size of this structure A DWORD queueid
71. of bytes recorded into buffer value Flags if the ADI RECORD BUFFER REQ bit is set more buffers are needed and the application must submit another empty buffer If the ADI RECORD UNDERRUN bit is set an underrun occurred There was no new buffer to record information when this one completed ADIEVN RECORD DONE Generated by the ADI service when the record operation terminates The event size field contains the total number of bytes recorded during the function instance The value field contains one of the following termination reasons or an error code CTA REASON DIGIT Aborted due to DTMF REASON VOICE Remote party never spoke CTA REASON RELEASED Call terminated CTA REASON STOPPED Stopped by application request CTA REASON TIMEOUT Maximum record limit reached CTA REASON VOICE END Remote party stopped speaking CTAERR xxx or ADIERR Xxx Record failed Details Use adisubmitRecordBuffer to asynchronously submit empty buffers to a record operation provided that the e Record operation was initiated by adiRecordAsync e Record operation is active e Application does not already have two actively submitted buffers The ADI service truncates the size so that the effective size is a multiple of the encoding frame size selected in adiRecordAsync If the effective size is zero CTAERR BAD SIZE is returned See also adiGetRecordStatus Example Refer to the playrec demonstration prog
72. of out of band signaling bits adiQuerySignalState Asynchronous Queries the current inbound out of band signaling bits adiStartDial Asynchronous Starts DTMF MF pulse dialing of digits adiStopDial Asynchronous Stops DTMF MF pulse dialing of digits On board timer functions The ADI service supports one application timer per port This on board timer has 10 ms resolution and can be used when the application is controlling the protocol from application space The following timer functions are provided by the ADI service Function Synchronous Description Asynchronous adiStartTimer Asynchronous Starts an on board timer adiStopTimer Asynchronous Stops an on board timer NMS Communications 77 Function summary ADI Service Developer s Reference Manual Configuration information functions The following functions retrieve information about a system configuration or specific board They also set the time or native play and record parameters adiGetBoardSlots Synchronous adiGetBoardSlots32 adiGetContextInfo Synchronous adiGetEEPromData Synchronous adiGetTimeStamp Synchronous adiSetBoardClock Synchronous adiSetNativeInfo Synchronous Function Synchronous Description Asynchronous adiGetBoardInfo Synchronous Retrieves information about the board Retrieves the board s MVIP configuration Retrieves the context status and configuration Retrieves OEM data for a given board Converts an event time
73. of the ADI ENCODE EDTX encoding formats all buffers submitted to the ADI service play functions must be large enough to contain an integral number of frames for the selected encoding format For example if you select ADI ENCODE NMS 24 the buffer size must be a multiple of 62 bytes Failure to submit a buffer meeting this size requirement causes the play function to terminate with CTAERR BAD SIZE For ADI ENCODE formatted data without EDTX headers that meet the multiple frame size requirement buffers submitted to the ADI service can be any size Use the ADI ENCODE EDTX encoding formats to record speech data directly from an IP endpoint Buffers recorded from encoded RTP codec streams can contain variable size frames and must contain marker frames representing silence and discontinuous transmission DTX periods These characteristics do not guarantee that any given buffer size will contain an integer multiple of codec frames marker frames or both Therefore buffers containing ADI ENCODE EDTX formatted data submitted to the ADI service can be any size Each board has a physical buffer size that is both board and encoding dependent If you submit a buffer larger than the physical size the ADI service divides the buffer into physical segments and submits those segments to the board To eliminate fractional buffers and to reduce the board to host interactions the optimum user buffer will be a multiple of the physical buffer size This size is
74. operation started by adiStartTimer For more information refer to Using on board timers on page 72 220 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 221 Function reference ADI Service Developer s Reference Manual adiStopToneDetector Stops a precise tone detector Supported board types e PacketMedia process Prototype DWORD adiStopToneDetector CTAHD ctahd unsigned toneid Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext A specified instance of the detector to stop Current range is 1 through 6 and corresponds to the toneid passed to adiStartToneDetector toneid Return values Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_SEQUENCE Attempt made to stop a function that is already being stopped CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Event Description ADIEVN_TONE_1_DETECT_DONE ADIEVN_TONE_2_DETECT_DONE ADIEVN_TONE_3_DETECT_DONE ADIEVN_TONE_4_DETECT_DONE ADIEVN_TONE_5_DETECT_DONE ADIEVN_TONE_6_DETECT_DONE 222 Precise tone detector 1 terminated Precise tone detector 2 terminated Precise tone detector 3 terminated Precise to
75. operations e Starts and stops recording audio data from a network audio stream Note Applications can perform DTMF detection using Fusion RFC 2833 support but silence detection is not supported Refer to the Fusion Developer s Manual for more information NMS Communications 35 Developing applications ADI Service Developer s Reference Manual The following illustration shows an overview of the native record mechanism without voice decoding ADI ADI service Ue port Sample procedure MSPP record connection Jitter filter JO MSP_NO_CONNECT Record channel RTP endpoint Applications use functions from the following Natural Access resources to implement native record functionality without inband silence detection or DTMF detection e Natural Access functions to set up event queues and contexts and to open services on the contexts e ADI service functions to start a protocol set native record settings and record incoming audio data e MSPP functions to create a voice connection consisting of a record channel and an RTP endpoint and to retrieve the unique filter ID associated with the record channel The following procedure shows functions used to implement a typical native record operation without decoding Step Action 1 Invoke ctaCreateQueue to create a Natural Access event queue ctaCreateQueue amp queuehd 2 Invoke ctaCreateContext to create a Natural Access context for the audio channel ctaCre
76. party The ADI event reason is Begins speaking voice begin ADI_CP_VOICE_BEGIN Has spoken for a period longer than the first time threshold voice ADI_CP_VOICE_MEDIUM medium Has spoken for a period longer than the second time threshold voice ADI_CP_VOICE_LONG long Has spoken for a period longer than the third time threshold voice ADI_CP_VOICE_EXTENDED extended Stopped speaking voice end ADI_CP_VOICE_END 48 NMS Communications ADI Service Developer s Reference Manual Developing applications Call progress termination events Call progress terminates when any of the following events occur If The ADI event is A dial tone is detected ADIEVN_CP_DIALTONE A busy tone is detected ADIEVN_CP_BUSYTONE A reorder tone is detected ADIEVN_CP_REORDERTONE A SIT tone is detected ADIEVN_CP_SIT There is no answer ADIEVN_CP_NOANSWER A fax or modem answer tone is detected ADIEVN_CP_CED A TDD TTY device tone is detected ADIEVN CP TDD Additionally you can configure the stopmask parameter in the ADI CALLPROG PARMS structure to selectively terminate on the occurrence of any of the following telephone network events Telephone network event ADI event A ring tone is detected ADIEVN CP RINGTONE There is a loss of ring tone with no subsequent events ADIEVN CP RINGQUIT Remote party begins speaking voice begin Check the ADIEVN CP VOICE with value field of the event for the voice event ADIEVN CP VOIC
77. service adiGetContextInfo does not fill in the tcpname field of the ADI_CONTEXT_INFO structure To retrieve this information the application must call nccGetLineStatusInfo The following table summarizes the ADI_CONTEXT_INFO structure Many of these context characteristics are described in other functions as noted Field Description Related functions size Returned size N A queueid Not used N A userid Not used N A agliberr NMS internal N A channel NMS internal N A board Board number on which the context s DSP resides ctaCreateContext stream Base MVIP stream for the context ctaCreateContext timeslot Context s MVIP 90 timeslot ctaCreateContext mode Context s MVIP mode ctaCreateContext maxbufsize Board physical buffer size adiGetEncodingInfo tcpname Protocol executing on the context adiStartProtocol state Context state N A stream95 Base MVIP 95 stream N A NMS Communications 107 Function reference ADI Service Developer s Reference Manual Example int myShowContextState CTAHD ctahd ADI_CONTEXT_INFO info if adiGetContextInfo ctahd amp info sizeof info SUCCESS return MYFAILURE printf Queue ID d n info queueid printf User ID 08Xh n info userid printf AG Channel 08Xh n info channel printf Last AGLIB Error d info agliberr printf AG Buffer Size dWMn info maxbufsize printf Protocol s n info tcpname
78. the DSPs on these boards occurs at a rate faster than 10 ms Using simultaneous play and record To use simultaneous play and record with an AG board add the following line to the board section in the board keyword file Buffers 0 Num n where n 4 times the number of ports on your board For example an AG 2000 board contains 8 ports so n would be 32 You must disable the beep when recording If you do not the record function tries to seize the output and generates CTAERR OUTPUT ACTIVE To disable the beep set the record parameter beepfreq or beeptime to O 30 NMS Communications ADI Service Developer s Reference Manual Developing applications Performing NMS native play and record NMS native play and record enables applications to maintain the quality of audio data played and recorded over network interfaces while minimizing the encoding and decoding resources needed to process the audio data Applications can perform the following tasks with NMS native play and record e Record voice data from RTP data streams transferred through MSPP service endpoints e Play and record media streams that contain silence SID frames RFC 2833 markers and lost frame markers e Perform silence and DTMF detection while recording RTP streams e Play media recorded directly from RTP streams to PSTN DSO ports without changing the native format of the data CG boards and PacketMedia HMP processes support NMS native play and record
79. tones voice and modem or fax terminal tones Call progress functions enable you to manage low level call control directly Call progress is affected by the parameters stored in the ADI CALLPROG PARMS structure This topic presents e Tone detection e Call progress tone events e Call progress voice events e Call progress termination events e System restrictions Tone detection Call progress functions are automatically invoked when nccPlaceCall is specified and turned off when the call reaches a connected state Once the call is in a connected state an application can invoke call progress functions and analyze in band energy as described in the following topics Telephone network tone detection The call progress functions analyze in band audio to detect the following telephone network signals e SIT special information tone e Reorder fast busy e Busy NMS Communications 43 Developing applications ADI Service Developer s Reference Manual e Ringing referred to as ring tone e Number unassigned tone The ADI_CALLPROG_PARMS parameters set the criteria to determine if the energy received is a telephone network tone or voice These parameters are sent to the board by adiStartCallProgress The following terms are used to characterize telephone network tones Term Description Pulse width Time during which a tone is active Inter pulse delay Time between two active tone pulses Tone cycle Time during which a tone
80. when needed ADI_PLAY_LAST_BUFFER When the ADI service finishes playing the buffer being returned from access ADIEVN_PLAY_DONE is generated with the value field set to CTA_REASON_FINISHED access is not invoked again for the current playing instance If the access return value is neither SUCCESS nor ADI_PLAY_LAST_BUFFER the ADI service immediately terminates the playing instance ADIEVN_PLAY_DONE is generated and the value field is set to ADIERR_PLAYREC_ACCESS access returns the number of bytes written to the buffer in the rsize variable If the returned size is larger than the buffer or the returned size is not a multiple of the framesize for the given encoding the ADI service terminates the play function and generates ADIEVEN_PLAY_DONE and the value field is set to CTAERR BAD SIZE Note Starting a play operation with the maxspeed parameter greater than 100 consumes additional DSP cycles You may not be able to run the number of ports normally supported Refer to the board installation and developer s manual for more information For more information refer to Playing on page 25 172 NMS Communications ADI Service Developer s Reference Manual Function reference See also adiGetPlayStatus adiModifyPlayGain adiModifyPlaySpeed adiPlayAsync adiPlayFromMemory adiSetNativeInfo adiStopPlaying Example This example shows a fragment of a program that plays the file test vce using adiStartPlaying and the associated access r
81. with the playing and recording functionality The Voice Message service uses the ADI service device level record and play functions To use the Voice Message service with the ADI service playing and recording functions open both services on the same context When using the Voice Message service you do not call the ADI playing and recording functions directly The Voice Message service calls the functions when needed For more information refer to the Voice Message Service Developer s Reference Manual To create an application using your own disk management functions call the ADI functions directly This topic presents e Voice encoding formats e Data transfer methods e DTMFabort mask e Recording e Playing e System restrictions e Using simultaneous play and record Voice encoding formats When recording or playing speech files you must select an encoding format The primary issue to consider when selecting a format is the compression ratio and the fidelity More aggressive compression requires less disk space and reduces host to board loading but uses more DSP resources Each encoding format has a minimum data block size called a frame Frames vary in size and duration depending upon the encoding format For NMS Communications boards a frame corresponds to 10 or 20 milliseconds of speech depending on the encoding format NMS Communications 13 Developing applications ADI Service Developer s Reference Manual AG and CG boa
82. 0 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 211 Function reference ADI Service Developer s Reference Manual adiStopPlaying Stops the play operation Supported board types e PacketMedia process Prototype DWORD adiStopPlaying CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values a Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_SEQUENCE Attempt made to stop a function that is already being stopped CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Description ADIEVN_PLAY_DONE After playing stops the ADI service generates a DONE event with the value field set to CTA_REASON_STOPPED Details Use adiStopPlaying to stop the play operation started by either adiStartPlaying adiPlayFromMemory or adiPlayAsync When the DONE event is received you can restart the play operation and any other operation requiring voice output For more information refer to Playing on page 25 212 NMS Communications ADI Service Developer s Reference Manual Function reference adiStopProtocol Stops the execution of a telephony protocol Suppo
83. 00012074 73844 ADIEVN TONE 3 BEGIN 0x00012075 73845 ADIEVN 3 END 0x00012076 73846 ADIEVN TONE 4 BEGIN 0x00012077 73847 ADIEVN TONE 4 END 0x00012078 73848 ADIEVN 5 BEGIN 0x00012079 73849 ADIEVN TONE 5 END 0x0001207A 73850 ADIEVN TONE 6 BEGIN NMS Communications 245 Events ADI Service Developer s Reference Manual Hex Decimal Event name 0x0001207B 73851 ADIEVN_TONE_6_END 0x00012080 73856 ADIEVN_SILENCE_DETECTED 0x00012081 73857 ADIEVN_ENERGY_DETECTED 0x00012090 73872 ADIEVN_TIMER_TICK 0x000120A0 73888 ADIEVN_SIGNALBIT_CHANGED 0x000120EE 73966 ADIEVN_BOARD_EVENT 0x000120FF 73983 ADIEVN_BOARD_ERROR 0x00012111 74001 ADIEVN_STARTPROTOCOL_DONE 0x00012112 74002 ADIEVN_STOPPROTOCOL_DONE 0x00012130 74032 ADIEVN_PLAY_DONE 0x00012131 74033 ADIEVN_RECORD_DONE 0x00012140 74048 ADIEVN_COLLECTION_DONE 0x00012141 74049 ADIEVN_DTMF_DETECT_DONE 0x00012142 74050 ADIEVN_MF_DETECT_DONE 0x00012150 74064 ADIEVN_CP_DONE 0x00012170 74096 ADIEVN_TONE_1_DETECT_DONE 0x00012171 74097 ADIEVN_TONE_2_DETECT_DONE 0x00012172 74098 ADIEVN_TONE_3_DETECT_DONE 0x00012173 74099 ADIEVN_TONE_4_DETECT_DONE 0x00012174 74100 ADIEVN TONE 5 DETECT DONE 0x00012175 74101 ADIEVN TONE 6 DETECT DONE 0x00012180 74112 ADIEVN ENERGY DETECT DONE 0x00012190 74128 ADIEVN TIMER DONE 0x000121A0 74144 ADIEVN PULSE DONE 0x000121A1 74145 ADIEVN SIGNAL DETECT DONE 0x000121A2 741
84. 0x00000014 20 CTAERR_DRIVER_OPEN_FAILED 0x00000015 21 CTAERR DRIVER VERSION 0x00000016 22 CTAERR DRIVER RECEIVE FAILED 0x00000017 23 CTAERR DRIVER SEND FAILED 0x00000014A 26 CTAERR INVALID BOARD 0x0000001B 27 CTAERR OUTPUT ACTIVE 0x0000001D 29 CTAERR LOCK TIMEOUT 0x00000041 65 CTAERR SVR COMM 0x00010001 65537 ADIERR ACCESS 0x00010002 65538 ADIERR INVALID QUEUEID 0x00010003 65539 ADIERR UNKNOWN BOARDTYPE 0x00010004 65540 ADIERR TOO MANY BUFFERS 0x00010005 65541 ADIERR INVALID CALL STATE 0x00010006 65542 ADIERR CANNOT CREATE CHANNEL 0x00010007 65543 ADIERR NO DSP PORT 0x00010008 65544 ADIERR NO DSP RESOURCES 0x0001000A 65546 ADIERR NOT ENOUGH RESOURCES 240 NMS Communications Events Event data structure The ADI service uses an asynchronous programming model to capitalize on the concurrent processing between board processors and the host CPU In response to commands executed by the application the ADI service generates events that indicate certain conditions or state changes All events are represented as a CTA_EVENT C data structure as shown typedef struct DWORD ave event id ADIEVN xxx adidef h s CTAHD ctahd context handle n DWORD timestamp timestamp E DWORD userid user id defined by ctaCreateContext DWORD size size of buffer if buffer NULL otherwise may contain event ey specific data g v
85. 3 1 G 726 e G 729A B For more information about supported vocoder types refer to the Fusion vocoder readme txt files 32 NMS Communications ADI Service Developer s Reference Manual Developing applications Applications can implement native play and record in the following ways Implementation Description Native play Application plays a stream of audio data from an ADI port to an RTP endpoint Native record without Application receives and records a stream of audio data from an RTP inband silence DTMF endpoint No data decoding takes place inband silence detection is not detection supported and DTMF detection is supported only through Fusion RFC 2833 support Native record with inband Application receives and records a stream of audio data from an RTP silence and DTMF detection endpoint and in parallel decodes the data from its network format for example G 711A or G 723 1 The application also performs silence detection DTMF detection or both with the data For a PacketMedia HMP process refer to the PacketMedia HMP Developer s Manual for implementation procedures Native play To implement native play functionality the application performs the following tasks e Opens the ADI service on the context and starts the nocc protocol e Opens the MSPP service on the context and creates an RTP endpoint e Retrieves the filter ID of the RTP endpoint e Supplies the ADI service with information about the RTP a
86. 46 ADIEVN QUERY SIGNAL DONE 0x000121B0 74160 ADIEVN TONES DONE 0 000121 0 74176 ADIEVN DONE 0x000121E0 74208 ADIEVN FSK RECEIVE DONE 0x000121E1 74209 ADIEVN FSK SEND DONE 246 NMS Communications ADI Service Developer s Reference Manual Events ordered by category Events This topic presents the ADI service events by category The following fields are always assigned regardless of the event id ctahd timestamp userid The remaining value size and buffer fields vary depending upon the event If there is no relevant information for a field it can be empty for the specific event The buffer field is filled only if data is given to the application Any events that yield data are noted The value field can contain an error code if the operation is in error when started or if the function fails This topic presents Administrative events Play and record events DTMF events MF events Call progress events Tone detector events Call control primitives Miscellaneous events Administrative events ID Value field Size field ADIEVN_BOARD_ERROR low word parmO low word parm1 high word xx00 high word parm2 ADIEVN BOARD EVENT low wordemsgtyp low word parmO high word obj high word parm1 ADIEVN STARTPROTOCOL DONE ADI REASON xxx ADIEVN STOPPROTOCOL DONE ADI_REASON_xxx NMS Communications 247 Events ADI Service Developer s Reference Manual Play and record even
87. 93 Function reference ADI Service Developer s Reference Manual The custom recording DPF sends data to the host by calling the DSPOS function dspkSendEvent The first parameter sent by the function displays in the value field of the CTA_EVENT structure All remaining parameters display in an attached buffer The application is responsible for freeing the buffer after it processes the data For more information refer to Detecting voice activity on page 67 Example This code sends a command to custom record DPF and prints the events from the DPF i myWaitForEvent ctaqueuehd event switch event gt id ie ier Br ease ADIEVN_RECORD_STARTED WORD 0522227 0 adiCommandRecord ctahd myParms 3 At the DSP level the DPF will see the following command packet ATORI gt size of command packet 09888 case ADIEVN_RECORD_EVENT if event gt buffer NULL event with multiple data WORD i WORD pData WORD event gt buffer printf event gt value x n event value printf event gt size x n event gt size for i20 i lt event gt size sizeof WORD i gate Peal een 10 if event gt size amp INTERNAL BUFFER ctaFreeBuffer event gt buffer printf Buffer freed n else event with only 1 data printf ev
88. ADI RECORD PARMS structure silencetime Maximum silence duration in milliseconds after the remote caller has stopped speaking silencetime is stored the ADI RECORD PARMS structure maxtime Record function time limit in milliseconds The remote caller has maxtime milliseconds after the beep to completely record a message maxtime is a function argument specified when initiating the record function Data transfer using callback mode In record callback mode the ADI service allocates two record buffers when the record function initiates The ADI service invokes the application specified callback routine whenever a record buffer is filled You specify the callback function when you initiate record with adiStartRecording When the ADI service fills a record buffer it invokes the record callback function and passes it the buffer pointer and the buffer size The callback routine writes the data to a storage medium such as a disk and returns Data transfer using asynchronous mode In asynchronous mode the application transfers voice data from the board to the host by cooperatively exchanging commands and events with the ADI service as shown in the following illustration Application ADI service DIEVN RECORD STARTED adiSubmitRecordBuffer ADIEVN_RECORD_BUFFER_FULL adiSubmitRecordBuffer ADIEVN_RECORD_DONE Time Time 22 NMS Communications ADI Service Developer s Reference Manual Developing appl
89. ADI recording function such as adiRecordAsync ADIEVN_RECORD_STARTED must be received before calling adiCommandRecord You can perform the following functions using adiCommandRecord e Enable and disable voice activity detection e Configure voice activity detection with application parameters e Enable and disable voice activity detection messaging e Pause and resume voice streaming from the board to the host 68 NMS Communications ADI Service Developer s Reference Manual Developing applications Sending and receiving FSK data The ADI service is capable of sending and receiving frequency shift key FSK data The transmit function is an implementation of the modem portion of Bellcore advisory TA NWT 000030 The basic modulation is continuous phase binary FSK at 1200 baud between 1200 Hz mark and 2200 Hz space The only supported baud rate is 1200 This topic presents e Sending FSK data e Terminating FSK data transmission e Receiving FSK data e Terminating FSK data reception Sending FSK data To send FSK data call adiStartSendingFSK While it is running the FSK transmitter is in one of the following states e Idle e Sending channel seizure e Sending mark e Sending data An FSK transmission consists of a sequence of states used to transmit a data packet and it is bracketed by silence or the idle state An FSK transmission with analog display services interface ADSI feature phones consists of the following sequen
90. AERR SVR COMM Server communication error NMS Communications 163 Function reference ADI Service Developer s Reference Manual Events RA Event Description ADIEVN_DIGIT_BEGIN Raw DTMF digit detected on i M M ADIEVN DIGIT END Raw DTMF digit detected off e ADIEVN DTMF DETECT DONE DTMF detector no longer running The event value field contains one of the following CTA REASON RELEASED Call terminated CTAERR xxx or ADIERR xxx DTMF detector failed REASON STOPPED Function stopped with adiStopDTMFDetector Details The following DSP file must be loaded to the board before running adiStartDTMFDetector For these boards Load this DSP file dtmf m54 or dtmfe m54 dtmf f54 or dtmfe f54 The standard QX DSP file See DSP file summary on page 269 for DSP file descriptions Refer to the board installation and developer s manual for a table of MIPS usage for all functions Use this function to enable detection of DTMFs By default the DTMF detector is active after the NOCC protocol is started or when the context enters the call control connected state Therefore this function is needed only to restart the DTMF detector if it was stopped using adiStopDTMFDetector or to modify the DTMF detector parameters An ADIEVN DIGIT BEGIN event an ADIEVN DIGIT END event are generated for every digit detected Each event contains the ASCII representation characte
91. CG board and PacketMedia HMP range is 51 through 15 Valid board range is 45 through NMS recommends that you use the default values Maximum non silent interval that is ignored by the silence detector Any sounds that last longer than this value reset the silence detector Valid AG board CG board and PacketMedia HMP range is 0 through 32767 NMS recommends that you use the default values Not used for QX boards Maximum length of silence after audio energy is detected before record stops with a reason of CTA_REASON_VOICE_END Use 0 to disable this timer Valid range is 0 through 65535 Bypass by passing a value of 0 263 Parameters ADI Service Developer s Reference Manual ADI_START_PARMS Dependent function adiStartProtocol Field name Type Default Units Description callctl blockmode DWORD 0 mask Not applicable callctl debugmask DWORD 0x0000 mask Not applicable callctl eventmask DWORD 0x0000 mask Not applicable callctl mediamask 0x001F Controls which functions are running or reserved when the call enters the connected conversation state The NOCC protocol enters this state immediately Reserved indicates that the DSP MIPS are committed to the operation before the operation actually starts The application must reserve DSP resources in advance by using this parameter for DTMF detection silence detection cleardown detection and echo cancellation See callctl mediamask valid va
92. D adiStartPulse CTAHD ctahd unsigned signal unsigned timeon unsigned timeoff m Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext el signal Bit mask pattern to pulse assert temporarily which is a combination of the following constants ADI_A_BIT 0x8 ADI_B_BIT 0x4 ADI_C_BIT 0x2 ADI_D_BIT 0x1 zero 0 timeon Duration of the pulse in milliseconds with the pattern activated timeoff Duration after the pulse in milliseconds before the DONE event is sent Return values Return value Description SUCCESS ADIERR_INVALID_CALL_STATE Function not valid in the current call state CTAERR_FUNCTION_ACTIVE Function already started CTAERR_FUNCTION_NOT_AVAIL Necessary dsp file was not downloaded to the board CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_SVR_COMM Server communication error Events Description ADIEVN_PULSE_DONE Generated by the ADI service when the pulse function terminates The event value field contains the termination reason NMS Communications 177 Function reference ADI Service Developer s Reference Manual Details AG 2000 and AG 2000C boards require signal m54 to be loaded For QX boards this function is supported in the standard DSP file Use adiStartPulse to output a specified signaling bit pattern for a precise duration This function is non
93. DI TIMESLOT structures each with the stream field set to 18 18 0 7 e For an AG 2000 board stream 18 is voice and stream 19 is signaling If adiGetBoardSlots is invoked with mode set to ADI VOICE DUPLEX the function returns an array of 16 ADI TIMESLOT structures each with the stream field set to 18 or 19 18 0 7 19 0 7 For details on MVIP addressing refer to the Switching Service Developer s Reference Manual maxslot argument is the number of ADI TIMESLOTSs in the application supplied slotlist array The ADI service returns the number of ADI TIMESLOTSs written to the slotlist in the numslots variable This value is in the range zero to maxslot inclusive Note If maxslot is 0 zero and slotlist is NULL numslots returns the actual number of slots without copying any data adiGetBoardSlots can be used with adiGetBoardInfo to dynamically configure an application s contexts ctaOpenServices is called with a board number and MVIP stream slot to open the ADI service The application can retrieve a complete list of configured stream slot pairs for any board with adiGetBoardSlots NMS Communications 101 Function reference ADI Service Developer s Reference Manual Example 102 NMS Communications ADI Service Developer s Reference Manual Function reference adiGetBoardSlots32 Returns the MVIP timeslots configured for the given board Supported board types e PacketMedia
94. DWORD terminators ADI COLLECT PARMS 82 Context handle returned by ctaCreateContext or ctaAttachContext Pointer to the buffer that receives the collected digits Because the returned string is NULL terminated the buffer must be sized to at least maxdigits 1 bytes Maximum number of digits to collect Pointer to a digit collection parameter structure as shown NULL designates default size of this structure S timeout waiting for the first digit use 0 to wait forever 27 timeout waiting for the next digit use 0 to wait forever oul if non zero collection does not yf end until the end of the final dtmf mask of acceptable digits use 0 Sy or ADI_DIGIT_ANY to accept all 7 mask of terminating digits use 0 to indicate no terminators A Refer to ADI_COLLECT_PARMS on page 256 for field descriptions and valid values NMS Communications ADI Service Developer s Reference Manual Function reference Return values Return value Description SUCCESS ADIERR_INVALID_CALL_STATE Function not valid in the current call state CTAERR_BAD_ARGUMENT buffer pointer is NULL CTAERR_BAD_SIZE maxdigits is 0 CTAERR_FUNCTION_ACTIVE Attempt was made to get a digit or flush the digit queue while collecting digits CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function is not valid in the current port state CTAERR_SVR_COMM Server communication error Eve
95. Deglitch time the minimum time in milliseconds before a transition between energy and silence is recognized autostop Automatic stop controls whether the energy detector continues running after the first event By default automatic stop is enabled The following illustration shows the energy detection parameters Signal energyqual 4 amplitude silencequal thresholdampl CUENTE Time The energy detector generates the following events e ADIEVN SILENCE DETECTED e ADIEVN ENERGY DETECTED e ADIEVN ENERGY DETECT DONE 66 NMS Communications ADI Service Developer s Reference Manual Developing applications Stopping energy detection adiStopEnergyDetector immediately terminates energy and silence detection The ADI service generates ADIEVN_ENERGYDETECT_DONE with the value set to CTA_REASON_STOPPED which means that the operation was stopped by application request The ADI service also generates ADIEVN_ENERGYDETECT_DONE and ADIERR_xxx CTAERR xxx or CTA_REASON_FINISHED When set to autostop one shot the value is set to CTA_REASON_FINISHED and the size field contains either ADIEVN_ENERGY_DETECTED or ADIEVN_SILENCE_DETECTED Detecting voice activity NMS Communications AG and CG boards as well as the PacketMedia HMP process provide a voice activity detector that suppresses user voice silence during dialogues with a voice recognition system By preventing silent data from being se
96. Details Use adiGetRecordStatus to retrieve status information about the active or most recently completed voice record operation for the specified context Up to size bytes of the ADI RECORD STATUS structure are copied to the address pointed to by info If size is greater than or equal to the size of ADI RECORD STATUS the complete structure is copied The number of bytes copied is returned in the ADI RECORD STATUS size field adiGetRecordStatus can be issued while actively recording If there is no active record operation the status information pertains to the most recently completed instance The ADI RECORD STATUS structure contains the following fields Field Description size Number of bytes copied to info reason Termination condition for the last ADIEVN RECORD DONE This field is 0 if the record operation is active or if it has not been started since the context was last opened buffercount Number of buffers submitted framecount Number of voice frames submitted totalbytes Number of bytes submitted by the application buffer Last buffer pointer submitted bytecount Size of the last buffer submitted bytesrecorded Total number of bytes received timestarted Timestamp for the start of the record operation Refer to adiGetTimeStamp underrun Total number of underruns during the record instance See also adiRecordAsync adiRecordToMemory adiStartRecording adiStopRecording Example void myShowRecordStatus
97. E BEGIN in the value field Remote party has spoken for a period longer than the ADIEVN CP VOICE with first time threshold voice medium Check the value ADIEVN CP VOICE MEDIUM in the value field of the event for the voice event field Remote party has spoken for a period longer than the ADIEVN CP VOICE with second time threshold voice long Check the value ADIEVN CP VOICE LONG in the value field field of the event for the voice event Remote party has spoken for a period longer than the ADIEVN CP VOICE with third time threshold voice extended Check the value ADIEVN CP VOICE EXTENDED in the value field of the event for the voice event field Remote party stopped speaking voice end Check the ADIEVN CP VOICE with value field of the event for the voice event ADIEVN CP VOICE END in the value field When call progress terminates ADIEVN DONE is generated System restrictions When using the NOCC protocol call progress functions can be run at any time With all other protocols call progress is under the control of the protocol until the call enters the connected state Once the call is in the connected state the application can run call progress functions NMS Communications 49 Developing applications ADI Service Developer s Reference Manual Detecting tones The tone detector runs a precise tone filter for a single or dual frequency tone Each instance of the ADI service for example each cont
98. ECT_PARMS when invoking adiCollectDigits Terminating asynchronous digit collection The collection operation has programmable termination conditions An application can also prematurely terminate the function by invoking adiStopCollection In all cases the ADI service sends ADIEVN_COLLECTION_DONE to the application which indicates that collection finished The value field contains the termination reason The maxdigits argument in adiCollectDigits specifies the maximum number of digits to collect Only digits written to the user buffer are counted For example digits discarded because they are not in the acceptable list are not counted Digit collection terminates when this maximum digit count is reached NMS Communications 55 Developing applications ADI Service Developer s Reference Manual If digits are stored in the ADI service s internal digit queue when adiCollectDigits is invoked the ADI service processes the digits individually from the front of the ADI service digit queue Each digit processed is checked against a list of acceptable digits and a list of terminating digits which are stored in the validDTMFs and terminator fields in the ADI COLLECT PARMS structure Invalid digits are discarded Terminating digits cause digit collection to terminate When digit collection terminates ADIEVN COLLECTION DONE is delivered to the application For information on reasons see adiCollectDigits Digit collection can also terminate when
99. G 4000 AG 4000C 0 ms 0 ms AG 4040 AG 4040C QX 2000 20 ms Not used 62 NMS Communications ADI Service Developer s Reference Manual To enable echo cancellation with specific parameters e Set ADI START echocancel mode or NCC X ADI_START echocancel mode to 2 e Set ADI START echocancel filterlength or Developing applications NCC X ADI_START echocancel filterlength to values of your choosing e Set ADI START echocancel adapttime or NCC X ADI_START echocancel adapttime to values of your choosing Features The following table provides general information about the echo canceller features Features Filter length Echo pre delay Double talk detector Input gain Echo suppressor enable disable Adaptation enable disable Windowing enable Bypass Comfort noise generation Tone disabling NMS Communications AG 2000 AG 2000C AG 4000 AG 4000C AG 4040 AG 4040C 2 4 6 8 10 16 20 24 32 40 48 64 ms 0 1 2 20 ms Yes Yes Yes Yes No Yes Yes Yes 2 4 6 8 10 16 20 24 32 40 48 64 5 0 1 2 20 ms Yes Yes Yes Yes No Yes Yes Yes 2000 1 2 20 ms 0 1 2 20 ms Yes No Yes Yes Yes Yes No No 63 Developing applications ADI Service Developer s Reference Manual Performance parameters The following table provides general information about the echo canceller performance parameters Performance AG 2000 AG 2000C
100. GCdecaytime decay time ms f ADI RECORD PARMS Refer to ADI RECORD PARMS on page 262 for field descriptions and valid values NMS Communications 141 Function reference ADI Service Developer s Reference Manual Return values Return value Description SUCCESS ADIERR_INVALID_CALL_STATE Function not valid in the current call state CTAERR_BAD_ARGUMENT Either invalid encoding selected or NULL buffer pointer passed CTAERR_BAD_SIZE size is less than one frame CTAERR_FUNCTION_ACTIVE Function already started CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_OUTPUT_ACTIVE Record failed because there is another active output function CTAERR_RESOURCE_CONFLICT Silence detector is in use by adiStartEnergyDetector CTAERR_SVR_COMM Server communication error 142 NMS Communications ADI Service Developer s Reference Manual Function reference Events Event Description ADIEVN_RECORD_STARTED Generated by the ADI service after the function is started on the board If the ADI RECORD BUFFER REQ bit in the event value field is set more buffers are needed and the application must submit another empty buffer ADIEVN RECORD BUFFER FULL Generated by the ADI service when a buffer is filled with recorded voice data The event contains the following fields e buffer Pointer to a previously submitted user buffer e size Number of bytes recorded into buff
101. ID_BOARD board does not exist CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_SVR_COMM Server communication error 100 NMS Communications ADI Service Developer s Reference Manual Function reference Details Use adiGetBoardSlots to query the available MVIP stream slot pairs configured for a given board The ctahd argument is used to access the context on which the ADI service was opened The ADI service can be opened in driver only mode if desired In this case no actual board resources are reserved Set the board field in the MVIP_ADDR structure passed to ctaOpenServices to ADI_AG_DRIVER_ONLY This function also works with a context that has the ADI service opened on actual MVIP streams and timeslots If mode is zero the slots returned are the DSP addresses that correspond to actual trunks whether or not they are actually connected For example if an AG 2000 board is partially populated only the slots that contain line interfaces are returned Note The DSPs are automatically connected to the trunk if the telephony bus is not enabled If mode is not zero the function returns only those streams capable of supporting the given mode The base stream for the given mode is returned in the ADI_TIMESLOT stream field Examples e Foran AG 2000 board stream 18 is voice and stream 19 is signaling If adiGetBoardSlots is invoked with mode set to ADI FULL DUPLEX the function returns an array of eight A
102. IEVN_RECORD_DONE ADIEVN_RECORD_EVENT ADIEVN_RECORD_STARTED ADIEVN_SIGNALBIT_CHANGED ADIEVN_SIGNAL_DETECT_DONE ADIEVN_SILENCE_DETECTED ADIEVN_STARTPROTOCOL_DONE ADIEVN_STOPPROTOCOL_DONE ADIEVN_TIMER_DONE ADIEVN_TIMER_TICK ADIEVN_TONE_1_BEGIN ADIEVN_TONE_1_DETECT_DONE ADIEVN_TONE_1_END ADIEVN_TONE_2_BEGIN ADIEVN_TONE_2_DETECT_DONE ADIEVN_TONE_2_END ADIEVN_TONE_3_BEGIN ADIEVN_TONE_3_DETECT_DONE ADIEVN_TONE_3_END ADIEVN TONE 4 BEGIN ADIEVN TONE 4 DETECT DONE ADIEVN TONE 4 END ADIEVN 5 BEGIN ADIEVN 5 DETECT DONE ADIEVN 5 END ADIEVN 6 BEGIN ADIEVN 6 DETECT DONE ADIEVN TONE 6 END ADIEVN TONES DONE 244 ADI Service Developer s Reference Manual Description Asynchronous buffer to write to disk Record operation complete Information sent by the custom recording function See adiCommandRecord for more detail Record operation started Signal detector reporting a change Signal detector terminated Energy detector reporting silence Acknowledgment of start protocol Acknowledgment of stop protocol Timer function complete expired Timer function reporting timer tick Precise tone 1 detected on Precise tone detector 1 terminated Precise tone 1 detected off Precise tone 2 detected on Precise tone detector 2 terminated Precise tone 2 detected off Precise tone 3 detected on Precise tone detector 3 terminated Precise tone 3 detecte
103. IPS usage for all functions Use this function to start detecting a precise tone which consists of one or two frequencies The precise tone is defined in terms of center frequency and bandwidth pairs specified in Hz Bandwidth is the total band around the center frequency for example bandwidth 2 After the detector is started if the specified tone is detected the ADI service generates a BEGIN event If the tone stops the ADI service generates an END event The detector continues until it is stopped by adiStopToneDetector which is followed by a DONE event You can change the minimum qualification time specified by qualtime in the ADI TONEDETECT PARMS structure To set a time limit on the detection use adiStartTimer to generate a timeout event Call adiStopToneDetector if a timeout occurred For more information refer to Detecting tones on page 50 196 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 197 Function reference ADI Service Developer s Reference Manual adiStartTones Starts generating one or more tones Supported board types e PacketMedia process Prototype DWORD adiStartTones CTAHD ctahd unsigned count ADI TONE PARMS parms Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext count Number of entries in the parms array pa
104. Info refer to the maxbufsize argument If bufsize is less than or equal to the board buffer size you can reuse the buffer as soon as this function returns Otherwise to avoid overwriting data you must wait for the second ADIEVN PLAY BUFFER REQ before you can reuse the buffer After play initiates the ADI service sends ADIEVN PLAY BUFFER REQ to the application whenever more data is needed The application responds to this event by submitting a filled voice buffer with adisubmitPlayBuffer The application must submit buffers only in response to ADIEVN PLAY BUFFER REQ For proper operation each buffer must be submitted while the previous buffer is being played If a buffer is submitted too late an underrun occurs and silence is played You can monitor for underruns by checking the ADI PLAY UNDERRUN bit in the value field of the ADIEVN PLAY BUFFER REQ event Use adiGetPlayStatus to retrieve a count of underruns that occurred since play started The application terminates play by submitting a buffer with the flags argument set to ADI PLAY LAST BUFFER After the ADI service has played the buffer that was submitted with the flag set it generates ADIEVN PLAY DONE with the value set to REASON FINISHED NMS Communications 133 Function reference ADI Service Developer s Reference Manual Refer to Recording and playing on page 13 for information about play operations in asynchronous mode Encoding formats and DSP files When
105. MS on page 259 for field descriptions Return values Return value Description SUCCESS CTAERR INVALID CTAHD Context handle is invalid CTAERR OUTPUT ACTIVE Open port failed because the stream and slot are already opened on another port CTAERR SVR COMM Server communication error Events Description ADIEVN TONES DONE Value field can contain REASON FINISHED or CTA_REASON_STOPPED NMS Communications 161 Function reference ADI Service Developer s Reference Manual Details The following DSP file must be loaded to the board before running adiStartDTMF For these boards Load this DSP file tone m54 tone f54 The standard QX DSP file See DSP file summary on page 269 for DSP file descriptions Refer to the board specific installation and developer s manual for a table of MIPS usage for all functions Use this function to start generating a sequence of DTMF tones or MF tones Use adiStopTones to terminate DTMF or MF generation Note While adiStartDTMF is active the DTMF detector is disabled digits can contain the following embedded escape characters that control the dialing sequence Character Description period Insert long pause in dialing comma Insert short pause in dialing Switch to DTMF dialing default Switch to MF dialing To generate MF tones precede the string with an M The following table lists the mapping to the United States MF digits for MF dialing
106. P file must be loaded for each encoding type except when using the native play and record feature The native play and record feature combines an ADI port with an MSPP endpoint and plays or records speech data directly to or from an IP endpoint with no transcoding For information on the native play and record feature refer to Performing NMS native play and record on page 31 For more information see Encoding formats and DSP files on page 134 The table lists the DSP files that must be loaded on the AG and CG boards It also lists the valid encoding types that QX boards and PacketMedia HMP processes support Refer to the board installation and developer s manual for MIPS usage Use adiRecordToMemory to initiate recording to memory resident buffer of size bufsize and return to the application The ADI service records data into the buffer until one of the terminating conditions described in ADIEVN_RECORDING_DONE occurs Note You cannot initiate a record operation while playing voice or generating tones unless you disable the record beep by setting either ADI_RECORD beeptime or ADI_RECORD beepfreg to 0 zero You cannot start a record operation if the energy detector is active unless both ADI_RECORD novoicetime and ADI_RECORD silencetime are 0 zero For more information refer to Recording on page 20 See also adiCommandRecord adiGetEncodingInfo adiSetNativeInfo adiStopRecording NMS Communications 147 Function reference Exampl
107. P file must be loaded to the board before running adiStartSendingFSK Load this DSP file Bellcore 1200 2200 Hz AG adsix m54 CG adsix f54 The standard DSP file See DSP file summary on page 269 for DSP file descriptions Refer to the board installation and developer s manual for a table of MIPS usage for all functions Use this function to initiate sending frequency shift key FSK data When parms is set to NULL the default parameter values are used A typical buffer size is 512 bytes The buffer size is limited to half the value of the maxbufsize field in the ADI CONTEXT INFO structure The only baud rate supported is 1200 Call adiStopSendingFSK to stop this function ADIEVN FSK SEND DONE is delivered when the send operation completes For these boards V 23 1300 2100 Hz adsix j m54 adsix j f54 The standard QX DSP file For more information refer to Sending and receiving FSK data on page 69 NMS Communications 187 Function reference ADI Service Developer s Reference Manual Example 188 NMS Communications ADI Service Developer s Reference Manual Function reference adiStartSignalDetector Starts detecting changes in incoming out of band signaling bits Supported board types Prototype DWORD adiStartSignalDetector CTAHD ctahd unsigned initial unsigned mask unsigned timeon unsigned timeoff m Argument Description ctahd Context handle
108. P process for voice activity detection set the value of the EnableVAD keyword to Yes For example EnableVAD Yes To enable voice activity detection call adicommandRecord on an actively running ADI recording function such as adiRecordAsync Automatic gain control and energy detection must be disabled when using voice activity detection Recording must be using ADI ENCODE MULAW ADI ENCODE ALAW or ADI ENCODE PCM8M16 Call adiCommandRecord after receiving ADIEVN RECORD STARTED 92 NMS Communications ADI Service Developer s Reference Manual Function reference The first parameter must be one of the following voice activity detector commands Command Description EVAD_CDE_FUNCTION_ENABLE Enable voice activity detection or update parameters Default is disabled EVAD_CDE_FUNCTION_DISABLE Disable voice activity detection Silence is no longer suppressed EVAD_CDE_DEFAULT_ENABLE Enable voice activity detection with default parameters EVAD_CDE_STREAMING_PAUSE Pause sending voice data silence or speech to the host application Useful for keeping voice activity detection energy thresholds update active when ASR is not active on the host EVAD_CDE_STREAMING_RESUME Resume sending voice data to the host application EVAD_CDE_SIGNALLING_ENABLE Send voice activity detection events to the host application even if voice activity detection or record streaming are disabled Default is disabled EVAD_CDE_SIGNALLING_DISABLE Stop send
109. RD filterlength filter length msec DWORD adapttime filter adaptation time msec DWORD predelay offset of input sample msec my INT32 gain receive gain db m ADI ECHOCANCEL PARMS Refer to the Parameters section for default values and a more detailed explanation of the fields in these structures When the protocol is NOCC adiStartProtocol must be called before any ADI functions are invoked The application can execute any function once ADIEVN STARTPROTOCOL DONE is received For details about using telephony protocols in the application refer to the NMS CAS for Natural Call Control Developer s Manual NMS Communications 175 Function reference ADI Service Developer s Reference Manual See also adiStopProtocol Example int mvstarLProtoool lt event start no call control protocol with all default parameters if adiStartProtocol ctahd NULL NULL SUCCESS return MYFAILURE do myGetEvent amp event see ctaWaitEvent example while event id ADIEVN STARTPROTOCOL DONE if CTA IS ERROR event value return MYFAILURE API error 7 else return SUCCESS started successfully 176 NMS Communications ADI Service Developer s Reference Manual Function reference adiStartPulse Starts the generation of an out of band pulse Supported board types Prototype DWOR
110. RR TOO MANY BUFFERS 0x00010004 65540 Attempted to submit a play or record buffer with two buffers pending ADIERR UNKNOWN BOARDTYPE 0x00010003 65539 Board type is unrecognized adiGetBoardSlots CTAERR_BAD_ARGUMENT 0 00000007 7 Function argument had an invalid value or a required pointer argument was NULL NMS Communications 237 Errors Error name CTAERR_BAD_SIZE CTAERR_BOARD_ERROR CTAERR_DRIVER_OPEN_FAILED CTAERR_DRIVER_RECEIVE_FAILED CTAERR_DRIVER_SEND_FAILED CTAERR_DRIVER_VERSION CTAERR_FATAL CTAERR_FUNCTION_ACTIVE CTAERR_FUNCTION_NOT_ACTIVE CTAERR_FUNCTION_NOT_AVAIL CTAERR_INVALID_BOARD CTAERR_INVALID_CTAHD CTAERR_INVALID_SEQUENCE 238 Hex 0x0000000B 0x00000003 0x00000014 0x00000016 0x00000017 0x00000015 0x00000002 0x0000000F 0 0000000 0x0000000D 0x0000001A 0x00000005 0x00000013 ADI Service Developer s Reference Manual Decimal 11 20 22 23 21 15 14 26 19 Description Size argument was too small to receive a data structure or a play or record buffer was not a multiple of the framesize for the specified encoding Unexpected error occurred on the board In most cases ADIEVN BOARD ERROR contains the board error code Driver open failed because either the driver was not installed or the maximum number of opens was exceeded Error occurred retrieving an event from the driver or no events were que
111. R_FUNCTION_ACTIVE CTAERR_INVALID_CTAHD CTAERR_INVALID_STATE CTAERR_SVR_COMM Events Event ADIEVN_CP_BUSYTONE ADIEVN_CP_CED ADIEVN_CP_DIALTONE ADIEVN_CP_DONE ADIEVN_CP_NOANSWER ADIEVN_CP_RINGQUIT ADIEVN_CP_RINGTONE ADIEVN_CP_REORDERTONE ADIEVN_CP_SIT ADIEVN_CP_STOPPED NMS Communications Function reference Description Function argument had an invalid value or a required pointer argument was NULL Function already started Context handle is invalid Function not valid in the current port state Server communication error Description Detected a busy tone Detected a called party modem or fax terminal tone Detected a dial tone Call progress analysis terminated normally The event value field can contain one of the following termination conditions or an error code CTA_REASON_FINISHED CTA_REASON_TIMEOUT CTA_REASON_RELEASED CTA_REASON_STOPPED Detected no answer The parameterized number of rings were detected without voice being detected Call progress analysis stopped detecting ring tones Ring was previously detected and another ring was not detected in time The cause can be a network error or a soft speaker answering the phone Detected ring tone Detected a reorder fast busy tone Detected a special information tone SIT If ADI_CPMSK_PRECISE_SITEXT is set in precmask the low order three bits in the event value field indicate the type of SIT detected 001 intercept
112. TAHD ctahd unsigned encoding ADIPLAY_ACCESS access void userarg ADI_PLAY_PARMS parms Argument ctahd 7 4 encoding access userarg parms 170 Description Context handle returned by ctaCreateContext or ctaAttachContext Data encoding selection See Voice encoding formats on page 13 for a complete list Pointer to a callback function that supplies data to be played See the Details section for a prototype of this function An arbitrary pointer or value to be passed to the callback function every time it is invoked Pointer to play parameters according to the following structure NULL value uses default values typedef DWORD DWORD INT32 DWORD DWORD Sierauicie size DTMFabort gain speed maxspeed ADI PLAY PARMS Refer to ADI PLAY PARMS on page 261 for field descriptions parms related to adiStartPlaying Size of this structure abort on DTMF playing gain in dB initial speed in percent maximum play speed in percent i 2 nu y 2 5 NMS Communications ADI Service Developer s Reference Manual Function reference Return values Return value Description SUCCESS ADIERR_INVALID_CALL_STATE Function not valid in the current call state CTAERR_BAD_ARGUMENT Invalid encoding CTAERR_FUNCTION_ACTIVE Function already started CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid
113. TATE Function not available in the current call state CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid lt CTAERR_INVALID_STATE Function not available in the current port state m CTAERR_SVR_COMM Server communication error Events Description ADIEVN_CP_DONE After the call progress analysis operation stops the ADI service generates a DONE event with the value field set to CTA_REASON_STOPPED Details Use adiStopCallProgress to disable the call progress analysis operation started by adiStartCallProgress After this function is called call progress analysis events are not reported Call progress analysis cannot be restarted until the DONE event is received NMS Communications 201 Function reference ADI Service Developer s Reference Manual Example 202 NMS Communications ADI Service Developer s Reference Manual Function reference adiStopCollection Stops the asynchronous digit collection operation Supported board types e PacketMedia HMP process Prototype DWORD adiStopCollection CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values Return value Description SUCCESS n ADIERR_INVALID_CALL_STATE Function not available in the current call state aaa CTAERR_FUNCTION_NOT_ACTIVE Attempt made to sto
114. TL_PARMS controls which functions are started automatically by adiStartProtocol The ADI CALLCTL PARMS structure is defined as typedef struct call control parameters ny DWORD size Biase Of nue DWORD eventmask not used DWORD mediamask functions to run ca define ADI_CC_RESVDTMF 0x0001 reserve dtmf detection SHA define ADI_CC_RESVSILENCE 0x0002 reserve silence detector 572 define ADI CC RESVCLRDWN 0x0004 reserve clear down det E define ADI CC AUTODTMF 0x0008 start DTMF detection define ADI CC AUTOECHO 0x0010 start echo canceller define ADI CC ALLMEDIA ADI CC RESVDTMF V AD CC RESVSILENCE ADI CC RESVCLRDWN AD CC AUTODTMF ADI CC AUTOECHO DWORD blockmode not used DWORD debugmask not used ADI_CALLCTL_PARMS e ADI_DIAL_PARMS specifies how to perform dialing Refer to adiStartDial for the structure definition e ADI_DTMFDETECT_PARMS controls DTMF detection if required by the protocol as well as initial DTMF detection in the conversation connected state if started automatically by the protocol Refer to adiStartDTMFDetector for the structure definition e ADI_ECHOCANCEL_PARMS controls the application of an echo cancellation algorithm to the context in the connected state and is defined as typedef struct parameters for echo cancellation DWORD size size of this structure DWORD mode echo canceller mode yp DWO
115. Tones For these boards Load this DSP file tone m54 tone f54 The standard DSP file See DSP file summary on page 269 for DSP file descriptions Refer to the board installation and developer s manual for a table of MIPS usage for all functions Use this function to start generating a sequence of tones each consisting of one or two frequencies and an iteration count The DONE event is generated when the tone sequence completes Each tone within the sequence comprises an ontime and an offtime as well as an iterations count all of which are contained in the ADI_TONE_PARMS structure The final iteration is complete when the offtime expires To generate a tone continuously set iterations to 1 and specify an offtime of O zero Use adiStopTones to prematurely terminate tone generation For more information refer to Generating tones on page 52 See also adiStartDTMF NMS Communications 199 Function reference ADI Service Developer s Reference Manual Example 200 NMS Communications ADI Service Developer s Reference Manual Function reference adiStopCallProgress Stops a call progress analysis operation Supported board types Prototype DWORD adiStopCallProgress CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values a Return value Description SUCCESS ADIERR_INVALID_CALL_S
116. VN CP VOICE ADI CP VOICE xxx Note Number of rings is set to 1 on the first occurrence of the event If the call progress stopmask is set to enable multiple ring events this field contains a count of the number of rings NMS Communications 249 Events Tone detector events ADI Service Developer s Reference Manual Size field is not applicable ID ADIEVN_TONE_1_BEGIN ADIEVN_TONE_1_DETECT_DONE ADIEVN_TONE_1_END ADIEVN TONE 2 BEGIN ADIEVN 2 DETECT DONE ADIEVN 2 END ADIEVN 3 BEGIN ADIEVN 3 DETECT DONE ADIEVN TONE 3 END ADIEVN TONE 4 BEGIN ADIEVN TONE 4 DETECT DONE ADIEVN TONE 4 END ADIEVN TONE 5 BEGIN ADIEVN TONE 5 DETECT DONE ADIEVN TONE 5 END ADIEVN TONE 6 BEGIN ADIEVN TONE 6 DETECT DONE ADIEVN 6 END Call control primitives Value field ADI 5 xxx ADI REASON xxx ADI 5 xxx ADI 5 xxx ADI 5 xxx ADI REASON xxx ID ADIEVN DIAL DONE ADIEVN FSK RECEIVE DONE ADIEVN FSK SEND DONE ADIEVN PULSE DONE ADIEVN QUERY SIGNAL DONE ADIEVN SIGNALBIT CHANGED ADIEVN SIGNAL DETECT DONE Value field ADI REASON xxx ADI REASON xxx ADI REASON xxx ADI REASON xxx ADI REASON xxx ADI x xxx ADI 5 xxx Size field Buffer size ADI xxx ADI BIT xxx Note The CTA EVENT buffer field for ADIEVN FSK RECEIVE DONE contains a
117. Y ADI ENCODE NMS 32 voice m54 voice f54 Y Y ADI ENCODE 5 64 voice m54 voice f54 Y Y ADI ENCODE MULAW rvoice m54 or rvoice f54 or Y Y rvoice vad m54 rvoice vad f54 ADI ENCODE 24 oki m54 oki f54 Y N ADI ENCODE OKI 32 oki m54 oki f54 Y Y 134 NMS Communications ADI Service Developer s Reference Manual Function reference Encoding type AG DSP file CG DSP file Qx PacketMedia HMP support support ADI ENCODE PCM8M16 rvoice m54 or rvoice f54 or Y Y rvoice_vad m54 rvoice_vad f54 ADI_ENCODE_PCM11M8 wave m54 wave 54 Y N ADI_ENCODE_PCM11M16 wave m54 wave 54 Y N ADI_ENCODE_VOX_32 y N Refer to DSP file summary on page 269 for DSP file descriptions Refer to the board installation and developer s manual for MIPS usage See also adiModifyPlayGain adiModifyPlaySpeed adiPlayFromMemory adiSetNativeInfo adiStartPlaying adiStopPlaying Example Refer to the playrec demonstration program NMS Communications 135 Function reference adiPlayFromMemory ADI Service Developer s Reference Manual Initiates a voice play operation using data from a single memory resident buffer Supported board types e PacketMedia process Prototype DWORD adiPlayFromMemory CTAHD ctahd unsigned encoding void buffer unsigned bufsize ADI_PLAY_PARMS parms Description typedef struct DWORD maxspeed ADI_PLAY_PARMS Return values Return value
118. _MF_DIGIT_BEGIN ADIEVN_MF_DIGIT_END ADIEVN_PLAY_BUFFER_REQ ADIEVN_PLAY_DONE ADIEVN_PULSE_DONE ADIEVN_QUERY_SIGNAL_DONE NMS Communications Description Unexpected board error returned This error can mean that the TCP initiated call clearing from an inappropriate state Low level board event returned Digit collection complete Call progress analysis detected busy Call progress analysis detected modem tone Call progress analysis detected dial tone Call progress analysis complete Call progress analysis detected no answer after ringing Call progress analysis detected ring tone remote alerting Call progress analysis detected ring but it stopped Call progress analysis detected reorder tone fast busy Call progress analysis detected SIT special information tone Call progress analysis detected voice Dial function complete Raw DTMF digit detected on Raw DTMF digit detected off DTMF detector terminated Arrival of echo cancellation status information Arrival of echo cancellation tone disabler information Energy detector terminated Energy detector reporting energy FSK receive operation complete FSK send operation complete MF detector terminated MF digit detected on MF digit detected off Asynchronous request for a buffer to play Play operation complete Pulse function complete Returned query of out of band signaling bits 243 Events Event name ADIEVN_RECORD_BUFFER_FULL AD
119. _filter_handle NULL this is record only so no egress handle amp parms get default adi record parms ret ctaGetParms ctahd ADI RECORD PARMID amp recparms sizeof ADI RECORD PARMS ret adiRecordToMemory ctahd ADI ENCODE EDTX MU LAW audio rec MemoryBuffer RecordedBytes amp recparms adiStopRecording ctahd Native record with inband silence and DTMF detection On CG boards use the following procedure to implement native record with inband silence detection or DTMF detection For PacketMedia HMP processes refer to the implementation procedure in the PacketMedia HMP Developer s Manual To implement native record functionality with inband silence detection or DTMF detection the application performs the following tasks e Opens the ADI service on a Natural Access context and starts the nocc protocol on the context e Opens the MSPP service and the ADI service on a second context and creates an RTP endpoint a DSO endpoint and a voice channel on the context e Connects the RTP endpoint DSO endpoint and voice channel to create a voice connection e Creates a switch connection between the ADI port and the DSO endpoint e Retrieves the filter ID of the jitter filter associated with the voice channel 38 NMS Communications ADI Service Developer s Reference Manual Developing applications e Supplies the ADI service with information about the RTP audio streams and specifies the desired behav
120. a HMP range is 22 through 32767 Valid QX board range is 30 through 32766 Do not modify Not used for QX boards Dependent function adiStartEnergyDetector Field name autostop deglitch thresholdampl 260 Type DWORD DWORD INT32 Default Units Description 1 mask 20 ms 45 dBm Controls whether the energy detector continues running after the first event Set this value to 1 to stop after the first event or 0 to run continuously Minimum time before a transition between silence and energy is recognized Valid AG board CG board and PacketMedia HMP range is O through 32767 Not used for QX boards Minimum signal level that is considered to be energy Anything below this level is considered to be silence Valid AG board CG board and PacketMedia HMP range is 51 through 15 Valid board range is 45 through 0 NMS Communications ADI Service Developer s Reference Manual Parameters ADI FSKRECEIVE PARMS Dependent function adiStartReceivingFSK Field Type Default Units Description name baudrate DWORD 1200 integer Transmission baud rate 1200 is the only valid value droptime DWORD 5 ms Minimum dropout to silence before a packet is considered terminated minlevel INT32 35 dBm Required minimum receive level minmark DWORD 10 ms Minimum required initial mark and seizure time ADI_FSKSEND_PARMS Dependent function adiStartSendingFSK Field name Type De
121. able of generating single and dual frequency tones Playing tones adiStartTones enables the application to play a list of single or dual frequency tones Each individual tone has the following attributes which are stored in the ADI_TONE_PARMS structure Parameter Description ontime A configurable active time period offtime A configurable inactive time period following the active time period iterations Number of times to repeat the tone The combined duration of ontime and offtime represents one complete cycle adiStartDTMF is a DTMF tone generator with programmable interdigit delays The function accepts a string of digits and an ADI_DTMF_PARMS structure The parameter structure allows you to specify interdigit pause duration for the comma and period characters which can be interspersed with the DTMFs in the digit string Terminating tone generation adiStopTones immediately terminates active tone generation Regardless of which tone type is active the ADI service generates ADIEVN_TONES_DONE with the value set to CTA_REASON_STOPPED The number of iterations is specified in ADI_TONE_PARMS which is passed to adiStartTones If the specified number of iterations is completed the ADI service generates ADIEVN_TONES_DONE with the value set to CTA_REASON_FINISHED If an error occurs in starting the function the DONE event is sent with the value set to ADIERR xxx or CTAERR xxx System restrictions Because only
122. ains the total number of bytes played during the function instance The event value field contains one of the following terminating conditions or an error code CTA_REASON_DIGIT Aborted due to DTMF CTA_REASON_FINISHED Complete buffer played CTA_REASON_RECOGNITION Aborted because of speech recognition CTA_REASON_RELEASED Call terminated CTA_REASON_STOPPED Stopped by application request When recording or playing speech files on AG boards a specific DSP file must be loaded for each encoding type For QX boards the standard DSP file supports the valid encoding types For more information refer to Voice encoding formats on page 13 When recording or playing speech files on CG boards a specific DSP file must be loaded for each encoding type except when using the native play and record feature The native play and record feature combines an ADI port with an MSPP endpoint and plays or records speech data directly to or from an IP endpoint with no transcoding For information on the native play and record feature refer to Performing NMS native play and record on page 31 For more information see Encoding formats and DSP files on page 134 The table lists the DSP files that must be loaded on the AG and CG boards It also lists the valid encoding types that QX boards and PacketMedia HMP processes support Refer to the board installation and developer s manual for MIPS usage adiPlayFromMemory starts playing a single memory resi
123. already active Necessary dsp file was not downloaded to the board Context handle is invalid Function not available in the current port state Server communication error Description Precise tone 1 detected on Call progress analysis detected modem tone Call progress analysis detected dial tone Call progress analysis complete Precise tone 1 detected off Precise tone 2 detected on Precise tone 2 detected off Precise tone 3 detected on Precise tone 3 detected off Precise tone 4 detected on Precise tone 4 detected off Precise tone 5 detected on Precise tone 5 detected off Precise tone 6 detected on Precise tone 6 detected off Precise tone detector 1 terminated Precise tone detector 2 terminated Precise tone detector 3 terminated Precise tone detector 4 terminated Precise tone detector 5 terminated Precise tone detector 6 terminated 195 Function reference ADI Service Developer s Reference Manual Details For AG and CG boards adiStartToneDetector requires one of the following DSP files to be specified in the board keyword file depending on the toneid specified CG AG Description boards boards dtmf f54 ptf m54 For toneid 1 dtmfe f54 ptf f54 ptf m54 For toneid 2 through 6 The CG board uses dtmf dtmfe for toneid 2 when detecting a single tone For QX boards this function is supported in the standard DSP file Refer to the QX 2000 Installation and Developer s Manual for a table of M
124. ample the DSP determines that a ring tone is present if all of the following conditions are met e There is energy below the telephone network tone frequency threshold 1 kHz e There is little or no energy above the network tone frequency threshold e The amplitude and frequency are reasonably steady over the period of time defining the ring tone Two signal characteristics are used for broadband tone detection time period and cadence When defining time period the application specifies time limits for excluding each telephone network tone The following illustration shows the effect these limits have on the tones The waveforms depicted are in milliseconds and are representative of tones in the USA Max reorder 7 Reorder Time Busy Time m 2000 4000 Ringing gt Time Dialtone 1 1 1 1 1 T 1 1 1 1 1 1 1 NMS Communications 45 Developing applications ADI Service Developer s Reference Manual The time parameters shown in the previous illustration are stored in ADI_CALLPROG_PARMS on page 254 Note The ADI service presumes that maxreorder is less than maxbusy and maxbusy is less than maxring This relationship defines a time tolerance minimum and maximum for each of the three tones detected The second characteristic used for broadband tone detection is the signal s cadence Th
125. ample to set the A bit high and the B bit low call adiAssertSignal as follows aduAsisertougnal Crand ADI A BET ADL BET 80 NMS Communications ADI Service Developer s Reference Manual Function reference When using this function with a system that includes an analog interface board refer to the hardware installation manual for the analog interface board for specific information on how the A and B bits affect the telephone line For more information refer to Performing low level call control on page 71 See also adiQuerySignalState adiStartDial Example Not using standard call control managing actual line interface directly E define MY_ONHOOK 0x00 define MY_OFFHOOK ADI_A BIT ADI_B BIT void myPickUp CTAHD ctahd adiAssertSignal ctahd MY_OFFHOOK void myHangUp CTAHD ctahd adiAssertSignal ctahd MY ONHOOK NMS Communications 81 Function reference adiCollectDigits ADI Service Developer s Reference Manual Starts collecting DTMF digits Supported board types e PacketMedia process Prototype DWORD adiCollectDigits CTAHD ctahd char buffer unsigned maxdigits ADI_COLLECT_PARMS parms m Argument Description ctahd buffer maxdigits parms values for parameters typedef struct DWORD DWORD size firsttimeout DWORD intertimeout DWORD waitendtone DWORD validDTMFs
126. an be modified after the echo canceller is started by calling adiModifyEchoCanceller For all board types the predelay parameter time shifts the correlation buffer This enables shorter filter lengths to be shifted in time allowing more echo energy to be captured as shown in the following illustration Port input data Correlated port output data predelay 3 4 filter length _ The default mode mode 1 chooses the best possible echo cancellation for the available DSP power on the board Choosing echo cancellation parameters that consume more DSP power than is available can result in errors when all ports are active To determine whether your boards support echo cancellation refer to Default filter length and adaptation time values on page 62 Configuring boards for echo cancellation Echo cancellation requires board specific settings Note The PacketMedia HMP process does not support echo cancellation Configuring AG boards for echo cancellation For AG boards configure the system for echo cancellation by editing the board keyword file Add echo m54 echo_v3 m54 or echo_v4 m54 depending on the features you require to the list of files in DSP C5x x Files y For information on DSP file features see DSP file summary on page 269 To enable echo cancellation with the board s default settings set the parameter ADI START echocancel mode or NCC X ADI_START e
127. ancellation function Use adiCommandEchoCanceller to enable and configure echo canceller tone detection Supported board types e AG e CG Prototype DWORD adiCommandEchoCanceller CTAHD ctahd WORD data DWORD nwords Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext data Pointer to an array of 16 bit data containing the commands nwords Number of 16 bit data words Return values Return value Description SUCCESS ADIERR_INVALID_CALL_STATE Function not valid in the current call state CTAERR_FUNCTION_NOT_ACTIVE Echo canceller function was not started before calling adiCommandEchoCanceller 4 CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_SVR_COMM Server communication error Events Description ADIEVN ECHOCANCEL STATUS Generated if the echo canceller enables send status mode For information about this mode of operation refer to echocancel mode in ADI START PARMS The echo canceller stores the status information in an event buffer The information is arranged according to the ADI ECHOCANCEL STATUS INFO structure in adidef h QX 2000 boards do not support the sending of echo canceller status information ADIEVN_ECHOCANCEL_TONE This event contains two words of information about the to
128. artProtocol 174 adiStopProtocol 213 TDD TTY device 154 254 terminating play function 26 test vce 182 threads demonstration program 236 tone detection 50 transferring data 18 two wire switching 64 U underruns 17 V voice activity detection 67 91 277
129. at runs on the host or on the board A necessary condition for a correct recognition is an echo free received signal The echo canceller on the local board must respond quickly to any changes and totally cancel the echo without distorting the incoming signal The echo canceller provides settings to optimize performance for ASR applications The ASR application may need to defeat its endpointing until the echo canceller has fully converged Empirical tests have shown that the echo suppressor part of the echo canceller sometimes called the non linear processor or NLP must be disabled These controls can be used through ADI functions IP telephony gateway network echo canceller example Another important application of echo cancellation can be found in IP telephony gateways The following illustration shows the two gateways Local and near end Speech decoder echo IP IP Echo PSTN network 77 interface canceller interface Speech 4 encoder For a two wire connection the gateway echo canceller cancels the local echo generated by the on board hybrid and the near end echo generated by the near end hybrid The returned echo level for the echo canceller must be as low as possible because the one way delay for this type of connection can be 100 ms or more 58 NMS Communications ADI Service Developer s Reference Manual Developing applications For a four wire connection to
130. ateContext queuehd amp ctahd 3 Invoke ctaOpenServices to open the ADI and MSPP services on the context ctaOpenServices ctahd svclist nsvcs 4 Invoke mspCreateEndpoint to create an audio RTP endpoint mspCreateEndpoint returns an endpoint handle ephd mspCreateEndpoint ctahd mspaddrstruct mspparmstruct amp rtpephd 5 Invoke mspCreateChannel to create a record channel mspCreateChannel ctahd chnladdr chnlparms amp chanhd 6 Invoke mspConnect to connect the record channel with the RTP endpoint Specify MSP NO CONNECT instead of a DSO endpoint handle mspConnect MSP NO CONNECT chanhd rtpephd 7 Invoke mspEnableChannel to enable the record channel to process data mspEnableChannel msphd 8 Invoke adiStartProtocol to start the nocc protocol on the audio channel adiStartProtocol ctahd nocc NULL startparms 9 Invoke mspGetFilterHandle to retrieve the filter identifier fltID associated with the MSPP record channel mspGetFilterHandle chanhd MSP FILTER JITTER amp fltID 36 NMS Communications ADI Service Developer s Reference Manual Developing applications Step Action 10 Invoke adiSetNativeInfo to set NMS native record parameters Specify both the context handle of the ADI port and the returned by mspGetFilterHandle adiSetNativeInfo ctahd fltID NULL natpr parms 11 Invoke ctaGetParms to return parameter values for the ADI RECORD PARMS structure ctaGetParms ctahd parmid buffer
131. ation Pointer to record parameters according to the following structure NULL uses default values typedef DWORD DWORD INT32 DWORD DWORD TNTS 2 DWORD DWORD INT32 DWORD DWOR TNTS TNTS DWOR DWOR AD D D Struct size DTMFabort gain novoicetime silencetime Silenceampl beepfreq beepampl beeptime AGCenable AGCtargetampl AGCsilenceampl silence level AGCattacktime AGCdecaytime RECORD PARMS size of this structure abort on DTMF recording gain in dB SLC parms recording used if silence det length of initial silence to stop ms use 0 to deactivate initial silence detection length of silence to stop recording after voice has been detected use 0 to deactivate qualif level for silence silencedeglitch deglitch while qualifying silence ms f PSO EOI ccc EE beep frequency beep amplitude ms a beep time AGC parms Hz dBm 0 beep dBm enable AGC use 1 to activate target AGC level attack time decay time dBm dBm ms ms Refer to ADI RECORD 5 on page 262 for field descriptions 57 v nu y 27 A 5 M ms 2 n 20d ui nu NMS Communications ADI Service Developer s Reference Manual Function reference Return values Return value Description SUCCESS
132. ation submitted buffer with ADI_PLAY_LAST_BUFFER set and the buffer was completely played CTA_REASON_RELEASED Call terminated CTA_REASON_STOPPED Stopped by application request Details Use adiSubmitPlayBuffer to asynchronously submit buffers provided that the e Play operation was initiated by adiPlayAsync e Play operation is currently active e ADI PLAY LAST BUFFER flag was not set for any buffer submission for the current playing instance e ADI service issued ADIEVN PLAY BUFFER REQ to the application and the application did not subsequently submit a buffer only one buffer can be submitted to a play operation at a time size can be arbitrarily large but must be an integral multiple of the frame size for the selected encoding For optimum performance size must be the largest frame multiple that will fit in one board buffer You can obtain this size by calling adiGetEncodingInfo refer to the maxbufsize argument If size is less than or equal to the board buffer size you can re use the buffer as soon as this function returns buffer can be set to NULL and size set to 0 zero only if the ADI PLAY LAST BUFFER flag is set In this case the play operation terminates when the previously submitted buffer finishes See also adiGetPlayStatus adiStopPlaying Example Refer to the playrec demonstration program NMS Communications 227 Function reference ADI Service Developer s Reference Manual adiSubmitRecordBuffe
133. ce of data sending mark sending data The sending channel seizure state never occurs in ADSI feature phones Therefore noseizureflag in the ADI_FSKSEND_PARMS structure must be set to 1 Parameters for sending FSK data adiStartSendingFSK requires the following parameters defined in the ADI_FSKSEND_PARMS structure Field name Description Default Valid value values noseizureflag 0 Allows send channel seizure state and sending mark 1 0 1 state 1 Allows only sending mark state level Transmit output level 14 dBm seizetime Length of channel seizure in milliseconds ignored if 1000 noseizureflag is set to 1 marktime Length of initial mark signal in milliseconds 500 baudrate Transmission baud rate 1200 1200 NMS Communications 69 Developing applications ADI Service Developer s Reference Manual Terminating FSK data transmission Use adiStopSendingFSK to stop the send function The event value field contains CTA_REASON_STOPPED The number of bytes sent before the function was stopped cannot be determined Receiving FSK data Call adiStartReceivingFSK to enable an application to receive FSK data While it is running the FSK receiver is in one of the following four states e Idle e Receiving channel seizure e Receiving mark e Receiving data A complete packet of FSK data consists of either of the following sequences e Receive channel seizure receive mark receive data e Receive mark receive data D
134. cenarios In general have no more than a zero GB of gain in each direction of the complete four wire part of a connection If it is necessary to increase the gain prior to a low bit rate codec for example there should be a commensurate loss at the output of the decoder Using Microsoft NetMeeting or other IP telephony clients In IP telephony applications the connection can be asymmetric For example you can talk on a telephone through an IP telephony gateway connected through an IP link to someone using Microsoft NetMeeting client on the remote end At this NetMeeting client the microphone and loudspeakers should not be used a microphone headset is preferred With a microphone and speaker combination at the NetMeeting client the person on the telephone end of the connection will hear considerable echo due to the acoustic loudspeaker to microphone acoustic coupling 64 NMS Communications ADI Service Developer s Reference Manual Developing applications Delay and echo In IP telephony applications a user s tolerance to echo in a telephone conversation is reduced by the more end to end delay there is in the connection IP packet delay is caused by routers and WAN facilities High packet inter arrival packet jitter usually must be absorbed by jitter buffers in the media gateway The more jitter there is in the IP network the longer the jitter buffer must be so the user does not experience poor audio quality due to packet loss Designer
135. chocancel mode to 1 The AG 4000 AG 4000C AG 4040 and AG 4040C boards do not have default settings See Default filter length and adaptation time values on page 62 NMS Communications 61 Developing applications ADI Service Developer s Reference Manual For AG boards as the predelay value is in increments the correlated data buffer is shifted later in time The predelay can be adjusted to center the correlated data on most of the echo energy The valid range is from 0 to 20 milliseconds Refer to the board s installation and developer s manual for more information Configuring QX boards for echo cancellation For boards using analog ports predelay must be set to 0 milliseconds to capture local and near end echo QX boards reduce the level of the echo less than 60 dBm Therefore depending on the level of the transmitted signal and impedance adaptation the improvement of the QX boards can be greater than 30 dB Refer to the QX 2000 Installation and Developer s Manual for more information Configuring CG boards for echo cancellation The resource definition string and the list of data processing modules DPM loaded on the DSPs on the CG boards have a default setup that includes echo To configure a CG board for echo cancellation edit the board keyword file Add echo f54 echo_v3 f54 or echo_v4 f54 depending on the features you require to the list of files in DSP C5x x Files For information on DSP file features see DSP fi
136. cise busy detected DWORD ringcount Number of ring cycles until report and quit DWORD maxreorder Separates fast busy from busy ms DWORD maxbusy Separates busy from ring cycle ms DWORD maxring Separates ring from dial tones ms DWORD maxringperiod Maximum ring period before CP RING QUIT ms DWORD voicemedium Time after VOICE BEGIN until VOICE MEDIUM ms DWORD voicelong Time after VOICE BEGIN until VOICE LONG ms DWORD voicextended Time after VOICE BEGIN until VOICE EXTENDED ms DWORD silencetime Silence period after voice til VOICE END ms DWORD precqualtime Precise tone qualification time ms DWORD precmask Precise tone mask DWORD stopmask mask to auto stop adiCallProgress INT32 silencelevel Reference level below which is silence dBm DWORD voicetoneratio voice vs tone ratio IDUs DWORD qualtonetimel Qualify time 1 for the TONE state ms DWORD qualtonetime2 Qualify time 2 for the TONE state ms DWORD qualvoicetimel Qualify time 1 for the VOICE state ms DWORD qualvoicetime2 Qualify time 2 for the VOICE state ms DWORD leakagetime Leaky integrator time constant in ms DWORD noiselevel Level window for QT2 state in IDUs ADI CALLPROG PARMS Refer to ADI CALLPROG 5 on page 254 for field descriptions 154 NMS Communications ADI Service Developer s Reference Manual Return values Return value SUCCESS CTAERR_BAD_ARGUMENT CTAER
137. coming calls and call teardown detection of hang up For more information about controlling calls under specific TCPs refer to the NMS CAS for Natural Call Control Developer s Manual For more information refer to Performing low level call control on page 71 190 NMS Communications ADI Service Developer s Reference Manual See also adiQuerySignalState Example define ALL BITS ADI A BIT ADI B BIT ADI_C_BIT ADI_D BIT int myMonitorSignal CTAHD ctahd CTA_EVENT event start function to monitor all bit changes of 100 ms Function reference if adiStartSignalDetector ctahd 0 ALL BITS 100 100 SUCCESS return MYFAILURE while 1 Chee myGetEvent amp event see ctaWaitEvent example switch event id case ADIEVN_SIGNAL_DETECT_DONE if event value REASON STOPPED return SUCCESS else return MYFAILURE case ADIEVN SIGNALBIT CHANGED switch event value value contains the change size contains current state case 0 1 A ON break case OxBl ON break case OxCl C ON break case OxD1 D ON break case 0 0 pc A OFF break case OxB0 B OFF break case 0 0 pc C OFF break case 0 0 D OFF break printf MVIP bit change s tsignalling bits 0x x W SCSCSCoC NIN pc event value amp Oxf event size amp 0x8 A event size amp 0x4 B
138. ction e Single memory transaction consumes a large virtual address space for large voice files An application may experience latency reading or writing large files to and from storage Asynchronous transfer The asynchronous transfer method gives you maximum latitude with buffer address size and submission When the play or record function is started with adiPlayAsync or adiRecordAsync an initial buffer is submitted Whenever the board starts a new buffer an event is generated The application must submit a new buffer using adiSubmitPlayBuffer or adiSubmitRecordBuffer before the board finishes the current buffer In summary e The programmer can control buffer addresses and sizes with asynchronous transfer and have asynchronous access to a storage medium e Asynchronous transfer is more complicated to program Callback transfer The callback transfer method balances simplicity in programming and resource consumption The ADI service allocates the buffers and invokes an application specified callback function whenever a buffer needs to be filled during a play function or when a buffer needs to be emptied during a record function Within the callback routine the application synchronously accesses the storage medium before returning In summary e Callback transfer minimizes virtual memory consumption and is simple to implement e The application cannot control the buffer addresses or sizes with callback transfer and
139. ction Using the ADI service in driver only mode To access only the board driver use the special board argument ADI_AG_DRIVER_ONLY in place of a real board number in the CTA_MVIP_ADDR structure This argument permits the application to use a virtual port The application can use the following functions on a context in driver only mode since they do not require physical board resources e adiGetBoardInfo e adiGetBoardSlots e adiGetBoardSlots32 e adiGetTimeStamp e adiGetEEPromData adiGetTimeStamp and adiGetEEPromData are not available for QX boards Note All other functions that take a context handle ctahd require board level resources Linking with the ADI service The ADI service contains two components the ADI service interface and the ADI service implementation When building a Natural Access application that uses the ADI service link to adiapi lib under UNIX ibadiapi so For existing applications modify the make files to link with adiapi lib libadiapi so Since earlier applications using the ADI service linked to adimgr lib under UNIX libadimgr so it is included only for backward compatibility See the Natural Access Service Writer s Manual for more details about service implementation 12 NMS Communications 3 Developing applications Recording and playing The most convenient way to program playing and recording applications is to use the Voice Message service since it provides disk management
140. ction Use callp xxx if any outgoing or two way trunk protocol is in use and for adiStartCallProgress dtmf m54 dtmf fxx Contains the DTMF receiver and the energy silence detector Use dtmf xxx for DTMF detection The energy silence detector is used by the record functions and by adiStartEnergyDetector dtmfe m54 dtmfe fxx Is a variation of dtmf xxx optimized for use with the echo canceller echo xxx dtmfe xxx yields better talk off resistance but requires the echo canceller to achieve the best cut through performance echo m54 echo fxx Contains the echo cancellation function The echo canceller removes reflected energy from the incoming signal which improves DTMF detection and voice recognition while playing Use echo xxx if echo cancellation is enabled See adiStartProtocol and the ADISTART_PARMS category Note Substitute dtmfe xxx for dtmf xxx when using the echo canceller echo v3 m54 echo v3 fxx Provides higher performance and support for longer echo tails Requires more resources than echo x54 and can decrease the number of ports NMS Communications 269 DSP files AG boards echo_v4 m54 None g726 m54 None gsm_ms m54 gsm mspl m54 ima m54 mf m54 oki m54 ptf m54 rvoice m54 rvoice vad m54 signal m54 not required for AG 4000 C and AG 4040 C boards 270 CG boards echo v4 fxx g723 fxx g726 fxx g729 fxx gsm ms fxx gsm mspl fxx ima fxx mf fxx oki fxx ptf
141. ction Synchronous Description Asynchronous adiStopPlaying Asynchronous Terminates playing adiStopRecording Asynchronous Terminates recording Using buffer management functions For the asynchronous data transfer methods a buffer is submitted using one of the following functions Function Synchronous Description Asynchronous adiSubmitPlayBuffer Asynchronous Supplies a buffer to an asynchronous play operation adiSubmitRecordBuffer Asynchronous Supplies a buffer for an asynchronous record operation NMS Communications 73 Function summary ADI Service Developer s Reference Manual Using status and modification functions The following functions provide status information or modify an active record or play operation Function Synchronous Description Asynchronous adiModifyPlayGain Synchronous Changes the gain applied to the speech while playing adiModifyPlaySpeed Synchronous Changes the play speed while playing adiGetPlayStatus Synchronous Retrieves play or last play status adiGetRecordStatus Synchronous Retrieves record or last record status adiGetEncodingInfo Synchronous Returns frame size data rate and maximum buffer size for a given encoding format adiCommandRecord Asynchronous Sends a data array containing raw commands to an actively running recording function Use this function to enable voice activity detection Call progress functions Call progress analysis primaril
142. ction was not implemented CTAERR OUTPUT ACTIVE 0x0000001B 27 port failed because the stream and slot are already opened on another port e Output operation such as play failed because there is another active output function CTAERR_OUT_OF_MEMORY 0 00000006 6 Unable to allocate memory for driver or port context for play or record buffers or for temporary storage When this error occurs in a DONE event it can mean that there was insufficient memory on the board CTAERR_OUT_OF_RESOURCES 0x00000008 8 Unable to create shared resources CTAERR_SHAREMEM_ACCESS 0x00000010 16 Failed accessing shared memory CTAERR_SVR_COMM 0 00000041 65 Server communication error The following table numerically lists the ADI service errors NMS Communications Hex Decimal Error name 0x00000002 2 CTAERR_FATAL 0x00000003 3 CTAERR_BOARD_ERROR 0x00000005 5 CTAERR_INVALID_CTAHD 0x00000006 6 CTAERR_OUT_OF_MEMORY 0 00000007 7 CTAERR_BAD_ARGUMENT 0x00000008 8 CTAERR_OUT_OF_RESOURCES 0 00000009 9 CTAERR_NOT_IMPLEMENTED 0 0000000 10 CTAERR_NOT_FOUND 0x0000000B 11 CTAERR BAD SIZE 0x0000000C 12 CTAERR INVALID STATE 0x0000000D 13 CTAERR FUNCTION NOT AVAIL 0x0000000E 14 CTAERR FUNCTION NOT ACTIVE 0x0000000F 15 CTAERR FUNCTION ACTIVE 239 Errors ADI Service Developer s Reference Manual Hex Decimal Error name 0x00000010 16 CTAERR_SHAREMEM_ACCESS 0x00000013 19 CTAERR_INVALID_SEQUENCE
143. ctmask and disconnectmask to force call resolution on any of these voice thresholds as well as on the voice end condition For example the application expects a voice to begin speaking with a short salutation for example Hello The voice medium time threshold should be set accordingly 46 NMS Communications ADI Service Developer s Reference Manual Developing applications The precise definition of each of these conditions is controlled by parameters in the callprog structure in ADI_CALLPROG_PARMS Voice Description Controlling parameter in callprog in condition ADI_CALLPROG_PARMS Voice begin Remote party begins speaking None Voice Remote party has spoken for a period voicemedium ms first time threshold medium longer than the first time threshold Voice long Remote party has spoken for a period voicelong ms second time threshold longer than the second time threshold Voice Remote party has spoken for a period voicextended ms third and final time extended longer than the third time threshold threshold Voice end Remote party stopped speaking silencetime ms qualification time before concluding voice end Voice begin can be triggered when the remote party begins speaking Voice end occurs after an absence of voice for silencetime milliseconds The following illustration shows call progress analysis voice detection Energy Voice begin Voice end NMS Hello Communications silencetime si
144. d protocol other than NOCC are usually excluded from using this function Protocols usually use out of band signaling bits for call setup detection of incoming calls and call teardown detection of hang up For information about controlling calls under specific TCPs refer to the NMS CAS for Natural Call Control Developer s Manual For more information refer to Performing low level call control on page 71 218 NMS Communications ADI Service Developer s Reference Manual Function reference See also adiStartSignalDetector Example NMS Communications 219 Function reference ADI Service Developer s Reference Manual adiStopTimer Aborts the timer operation Supported board types e PacketMedia process Prototype DWORD adiStopTimer CTAHD ctahd Argument Description Context handle returned by ctaCreateContext or ctaAttachContext ctahd Return values gt gt gt 55 gt Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_SEQUENCE Attempt made to stop a function that is already being stopped CTAERR_SVR_COMM Server communication error Events Description ADIEVN_TIMER_DONE After the timer operation stops the ADI service generates a DONE event with a value field of CTA_REASON_STOPPED Details Use adiStopTimer to abort the timer
145. d PacketMedia HMP range is 54 through 3 Valid board range is 90 through Frequency of the record beep tone 0 disables the beep Valid AG board CG board and PacketMedia HMP range is 200 through 3600 Valid QX board range is 0 through 4000 Duration of the record beep tone 0 disables the beep Valid AG board CG board and PacketMedia HMP range is 0 through 65535 Valid QX board range is 0 through 8000 Mask that enables you to control which DTMFs abort a record See Valid DTMF values on page 256 Gain applied to the signal before it is encoded If automatic gain control AGC is enabled this value is the initial gain when record is started Valid AG board CG board and PacketMedia HMP range is 54 through 24 Valid QX board range is 42 through 48 Use zero to record with no gain Values specified out of range are translated into one of the boundary values NMS Communications ADI Service Developer s Reference Manual Field name Type novoicetime DWORD silenceampl INT32 silencedeglitch DWORD silencetime DWORD NMS Communications Default Units 5000 ms 45 dBm 100 ms 3000 ms Parameters Description Maximum length of silence at the beginning of a recording before record is stopped with a reason of 5 VOICE Use 0 to disable this timer Valid range is 0 through 65535 Bypass by passing a value of 0 Maximum signal level considered to be silence Valid AG board
146. d in the ADI_PLAY_STATUS size field adiGetPlayStatus can be issued while actively playing If there is no active play operation the status information pertains to the most recently completed instance The ADI_PLAY_STATUS structure contains the following fields Field Description size Number of bytes copied to info reason Termination condition for the last ADIEVN_PLAY_DONE This field is O if the play operation is active or if it has not been started since the context was last opened buffercount Number of buffers submitted framecount Number of voice frames submitted totalbytes Number of bytes submitted by the application buffer Last buffer pointer submitted bytecount Size of the last buffer submitted bytesplayed Total number of bytes actually processed by the DSP and transmitted timestarted Timestamp for when the play operation started Refer to adiGetTimeStamp underrun Total number of underruns during the play instance See also adiPlayAsync adiPlayFromMemory adiStartPlaying adiStopPlaying Example void myShowPlayStatus CTAHD ctahd ADI_PLAY_STATUS playstatus adiGetPlayStatus ctahd amp playstatus sizeof playstatus printf Termination condition x bytes played d n playstatus reason playstatus bytesplayed 116 NMS Communications ADI Service Developer s Reference Manual adiGetRecordStatus Function reference Retrieves the record operation status Supported board types
147. d off Precise tone 4 detected on Precise tone detector 4 terminated Precise tone 4 detected off Precise tone 5 detected on Precise tone detector 5 terminated Precise tone 5 detected off Precise tone 6 detected on Precise tone detector 6 terminated Precise tone 6 detected off Tone generation function complete NMS Communications ADI Service Developer s Reference Manual Events Numerical event summary The following table numerically lists the ADI service events Hex Decimal Event name 0x00012030 73776 ADIEVN PLAY BUFFER REQ 0x00012031 73777 ADIEVN RECORD STARTED 0x00012032 73778 ADIEVN RECORD BUFFER FULL 0x00012034 73780 ADIEVN RECORD EVENT 0x00012035 73781 ADIEVN ECHOCANCEL STATUS 0x00012036 73782 ADIEVN ECHOCANCEL TONE 0x00012040 73792 ADIEVN DIGIT BEGIN 0x00012041 73793 ADIEVN_DIGIT_END 0x00012048 73800 ADIEVN_MF_DIGIT_BEGIN 0x00012049 73801 ADIEVN_MF_DIGIT_END 0x00012050 73808 ADIEVN_CP_VOICE 0x00012051 73809 ADIEVN_CP_DIALTONE 0x00012052 73810 ADIEVN_CP_BUSYTONE 0x00012053 73811 ADIEVN_CP_REORDERTONE 0x00012054 73812 ADIEVN_CP_RINGTONE 0x00012055 73813 ADIEVN_CP_NOANSWER 0x00012056 73814 ADIEVN CP RINGQUIT 0x00012057 73815 ADIEVN SIT 0x00012059 73817 ADIEVN CED 0x00012070 73840 ADIEVN 1 BEGIN 0x00012071 73841 ADIEVN 1 END 0x00012072 73842 ADIEVN 2 BEGIN 0x00012073 73843 ADIEVN 2 END 0x
148. d range is 0 through 32767 Length of time of the last ringing tone plus the silence that follows before call progress reports a ringing ended event Do not modify Mask to control which precise detectors to run To form a value use the OR operator with any of the following bit masks e ADI CPMSK PRECISE 0x0001 CED tone modem e ADI CPMSK PRECISE SIT 0x0002 SIT ADI CPMSK PRECISE BUSY 0x0004 Busy and reorder tone US e ADI CPMSK PRECISE 425 0x0008 425 Hz tone busy and reorder tone non US e ADI CPMSK PRECISE SITEXT 0x0010 SIT type reporting ADI CPMSK PRECISE TDD 0x0020 TDD TTY device e ADI CPMSK PRECISE NU 0x0040 Unassigned number You can run only three of the four detectors concurrently If you specify all four detectors busy and reorder tones are determined by cadence alone and only the SIT CED and TDD TTY detectors are enabled Busy and reorder tone bit value 0x0004 and the 425 Hz tone selection bit value 0x0008 are mutually exclusive If you choose both only the 425 Hz filter is in effect Precise tone qualification time All precise tones must be longer than this time to qualify NMS Communications ADI Service Developer s Reference Manual Field name Type qualtonetime1 DWORD qualtonetime2 DWORD qualvoicetime1 DWORD qualvoicetime2 DWORD ringcount DWORD silencelevel INT32 silencetime DWORD stopmask DWORD timeout voicextended DWORD voicel
149. d to the collected digit string Specify ADI DIGIT ANY to accept all digits See Valid DTMF values on page 256 for information Optionally the value ADI COLLECT QUIETLY can be added to this parameter to suppress all but the final ADIEVN DIGIT BEGIN and ADIEVN DIGIT END events that are normally generated as each digit arrives Flag to indicate that collection ends at the trailing edge of the last digit If O collection ends as soon as the final digit is detected If 1 collection does not end until the end of the final digit NMS Communications ADI Service Developer s Reference Manual Parameters ADI DIGIT POUND 0x0800 ADI DIGIT A 0x1000 ADI DIGIT B 0x2000 ADI DIGIT C 0x4000 ADI_DIGIT_D 0 8000 ADI_DIAL_PARMS Dependent function adiStartDial Field name Default Units Description breaktime DWORD 60 ms Break on hook duration for dial pulses Valid AG board and CG board range is 0 through 30000 Valid board range is 0 through 32767 dialtonewait DWORD 5000 ms Maximum time to wait for dial tone character Valid range is 0 through 65535 dtmfampl1 INT32 6 dBm Amplitude of the low frequency component of the DTMF pair Valid AG board CG board and PacketMedia HMP range is 54 through 3 Valid board range is 90 through 0 4 dBm Amplitude of the high frequency component of the DTMF pair Valid AG board CG board and PacketMedia HMP range is 54 through 3 Valid
150. data pointer 250 NMS Communications ADI Service Developer s Reference Manual Events Miscellaneous events ID Value field Size field ADIEVN ECHOCANCEL STATUS Size of ADI ECHOCANCEL STATUS INFO ADIEVN_ECHOCANCEL_TONE low word type of tone high word frequency ADIEVN_ENERGY_DETECT_DONE ADI_REASON_xxx Event ID if condition is FINISHED ADIEVN_ENERGY_DETECTED ADIEVN_SILENCE_DETECTED ADIEVN_TIMER_DONE ADI_REASON_xxx ADIEVN_TIMER_TICK Tick count Note The CTA_EVENT buffer field for ADIEVN_ECHOCANCEL_STATUS contains a data pointer NMS Communications 251 Parameters Overview of the ADI service parameters The behavior of many ADI functions is controlled by multiple parameters These parameters are grouped together into structures Each parameter structure has a set of default values that is sufficient for many configurations The parameters can be modified to e Enable or disable function features e Adapt the function for exceptional configurations For example when recording voice data the application programmer can alter the function s behavior by modifying any of the record parameters that specify e Any subset of DTMF keys entered by the telephone caller that abort the function e Gain applied to the input signal Aninitial timeout that defines the time in which the caller must start speaking before the operation terminates e The amount of silence after a caller has stopped speaking be
151. dent buffer of bufsize bytes The ADI service generates ADIEVN_PLAY_DONE when the function terminates To avoid unintentionally modifying data the application must not modify the buffer until it receives the DONE event For more information refer to Playing on page 25 See also adiGetEncodingInfo adiGetPlayStatus adiModifyPlayGain adiModifyPlaySpeed adiPlayAsync adiSetNativeInfo adiStartPlaying adiStopPlaying NMS Communications Function reference 137 Function reference ADI Service Developer s Reference Manual Example 138 NMS Communications ADI Service Developer s Reference Manual Function reference adiQuerySignalState Queries the current state of the out of band signaling bits Use only with NOCC protocol Supported board types Prototype DWORD adiQuerySignalState CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE adiStartSignalDetector was not called CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_RESOURCE_CONFLICT A protocol other than NOCC is active CTAERR_SVR_COMM Server communication error Events Description ADIEVN_QUERY_SIGNAL_DONE After the ADI service queries the board for the current signaling pattern the ADI service generates an event with the size field
152. diFlushDigitQueue 95 adiGetBoardInfo 97 adiGetBoardSlots 100 adiGetBoardSlots32 103 adiGetContextInfo 106 adiGetDigit 109 121 adiGetEEPromData 111 adiGetEncodingInfo 113 adiGetPlayStatus 115 adiGetRecordStatus 117 adiGetTimeStamp 119 adiInsertDigit 121 adimgr lib 12 adiModifyEchoCanceller 123 adiModifyPlayGain 128 adiModifyPlaySpeed 130 adiPeekDigit 131 adiPlayAsync 132 adiPlayFromMemory 136 adiQuerySignalState 139 adiRecordAsync 141 adiRecordToMemory 145 150 adiSetBoardClock 149 adiSetNativeInfo 150 adiStartCallProgress 154 adiStartDial 158 adiStartDTMF 161 273 Index adiStartDTMFDetector 163 adiStartEnergyDetector 165 adiStartMFDetector 167 adiStartPlaying 170 adiStartProtocol 174 adiStartPulse 177 adiStartReceivingFSK 179 adiStartRecording 182 adiStartSendingFSK 186 adiStartSignalDetector 189 adiStartTimer 192 adiStartToneDetector 194 adiStartTones 198 adiStopCallProgress 201 adiStopCollection 203 adiStopDial 204 adiStopDTMFDetector 206 adiStopEnergyDetector 208 adiStopMFDetector 210 adiStopPlaying 212 adiStopProtocol 213 adiStopReceivingFSK 215 adiStopRecording 216 adiStopSendingFSK 217 adiStopSignalDetector 218 adiStopTimer 220 adiStopToneDetector 222 adiStopTones 224 adiSubmitPlayBuffer 226 adiSubmitRecordBuffer 228 AGC automatic gain control 25 ASR automatic speech recognition 67 examples of echo cancellation 57 recommendations for controlling echo 64 asynchronous transfers 18 playing voice
153. ds by either submitting a full buffer adiSubmitPlayBuffer or a full or partial buffer adiSubmitPlayBuffer with flag indicating ADI_PLAY_LAST_BUFFER If the ADI_PLAY_UNDERRUN bit is set an underrun occurred meaning that playing was temporarily suspended because there was no buffer to play ADIEVN_PLAY_DONE Generated by the ADI service when the play operation terminates The event size field contains the total number of bytes played during the function s instance The event value field contains one of the following termination conditions or an error code CTA_REASON_DIGIT Aborted due to DTMF CTA_REASON_FINISHED Buffer submitted with the ADI_PLAY_LAST_BUFFER flag set completed playing CTA_REASON_RECOGNITION Aborted because of speech recognition You receive this reason only if the application is using a speech recognition library CTA_REASON_RELEASED Call terminated CTA_REASON_STOPPED Stopped by application request Details Use adiPlayAsync to initiate a voice playback operation The voice data is supplied in a sequence of buffers The application has complete latitude and responsibility for allocating filling and submitting buffers to the ADI service The bufsize can be arbitrarily large but must be an integral multiple of framesize bytes for the selected encoding For optimum performance the bufsize must be the largest frame multiple that fits in one board buffer You can obtain this size by calling adiGetEncoding
154. e aie Record to supplied buffer myRecord CTAHD ctahd ADI_RECORD_PARMS parms CTA_EVENT event unsigned datarate myret unsigned silencetime unsigned trimsize 0 unsigned bufsize ADI Service Developer s Reference Manual stopping after 1 second of silence unsigned encoding unsigned bytesrecorded average bytes sec 1000 Modify default silence timeout ctaGetParms ADI RECORD PARMID amp parms sizeof parms parms silencetime silencetime if adiRecordToMemory ctahd encoding buf bufsize amp parms return MYFAILURE do myGetEvent amp event see ctaWaitEvent example while event id ADIEVN RECORD DONE switch event value gase CTA_REASON_FINISHED Buffer filled myret SUCCESS break case CTA_REASON_NO_VOICE No voice detected bytesrecorded 0 myret SUCCESS break case CTA_REASON_RELEASED The call was terminated myret MYDISCONNECT break case CTA_REASON_STOPPED adiStopRecording was called case CTA_REASON_DIGIT Aborted due to touchtone DTMF is trimmed automatically by AG board bytesrecorded event size myret SUCCESS break case CTA REASON VOICE END Silence after voice bytesrecorded event size adiGetEncodingInfo ctahd encoding NULL amp datarate trimsize datarate silencetime 1000 myret SUCCESS break default an error code myret MYFAILURE break
155. e the ADI service allocates a buffer and invokes an application specified function to play voice data into it You specify the callback function when play is initiated with adiStartPlaying When the ADI service requires data it invokes the callback function passing it a buffer to fill and the buffer size The application s callback routine reads data from a storage medium for example a disk into the buffer The callback returns the amount of data read and a flag indicating whether to terminate the playing session after the buffer is played Playing voice data using callback mode follows this process 1 The application invokes adiStartPlaying The ADI service invokes the callback function from within the adiStartPlaying context to retrieve the initial buffer before adiStartPlaying returns 2 The ADI service invokes the application s callback function when a play buffer needs to be filled with voice data 26 NMS Communications ADI Service Developer s Reference Manual Developing applications 3 The application s callback function fills the buffer before returning At this point if the application indicates that this is the last buffer using the ADI_LASTBUFFER_SUBMITTED flag or if a termination condition occurs the play operation may terminate 4 Steps 2 and 3 are repeated until the ADI service generates ADIEVN_PLAY_DONE The application cannot invoke ADI service functions while the callback is executing Delaying the
156. e application specifies tone counts in ADI_CALLPROG_PARMS The signal must satisfy the single tone criteria described in the following illustration for the respective number of cycles before the ADI service concludes the signal is present The following table defines the cadence for each signal Parameter Description busycount Busy signal received Reorder busycount Reorder received ringcount Call not answered For example when busycount reorder tones are counted the ADI service concludes it is receiving a reorder fast busy signal The following illustration depicts ring tone termination After having established that the line is receiving a ring tone the ADI service concludes that the remote trunk has quit ringing if a ring tone is not received in the maxringperiod This parameter controls the ring quit event Energy Ring quit a Time Voice detection If the ADI service does not detect a network tone call analysis advances into the final stage of voice detection The ADI service detects when the remote party starts and stops speaking These are the voice begin and voice end conditions respectively The voice begin condition indicates that the call is being answered by the remote party The ADI service supports three voice duration time thresholds medium long and extended The duration for these three thresholds is specified in the ADI_CALLPROG_PARMS structure The application can set the conne
157. e field This table lists the MF frequencies for each mftype along with the digit value returned in the event s value field Digit US MF ITU forward ITU backward 1 700 900 1380 1500 1140 1020 2 700 1100 1380 1620 1140 900 3 900 1100 1500 1620 1020 900 4 700 1300 1380 1740 1140 780 5 900 1300 1500 1740 1020 780 6 1100 1300 1620 1740 900 780 7 700 1500 1380 1860 1140 660 8 900 1500 1500 1860 1020 660 9 1100 1500 1620 1860 900 660 0 1300 1500 1740 1860 780 660 B 700 1700 1380 1980 1140 540 900 1700 1500 1980 1020 540 D 1100 1700 1620 1980 900 540 E 1300 1700 1740 1980 780 540 F 1500 1700 1860 1980 660 540 168 NMS Communications ADI Service Developer s Reference Manual Function reference The following table lists the mapping to the United States MF digits for MF dialing United States MF name Specific digit address MF ST3P MF KP2 MF ST2P Note The digit values are the same as those used by adiStartDTMF and adiStartDial when MF digits are dialed See also adiStartDTMFDetector adiStopDTMFDetector NMS Communications 169 Function reference adiStartPlaying ADI Service Developer s Reference Manual Starts a playing operation using a callback routine to get data This function is not supported when Natural Access is running in client server mode Supported board types e PacketMedia process Prototype DWORD adiStartPlaying C
158. e signal can be distorted The non linear processor functions only during single talk situations The non linear processor attenuates the residual echo that could not be cancelled by the adaptive filter For all boards except QX boards the application can provide input signal gain or loss The application can bypass the echo canceller and restart at any time Use Bypass when voiceband modems or fax machines terminate both ends of the connection in an IP telephony application NMS Communications ADI Service Developer s Reference Manual Developing applications Specifying echo canceller parameters If you use echo cancellation in your application you may need to modify the callctl mediamask in ADI_START_PARMS or the mediamask in NCC_ADI_START before you start a telephony protocol The mediamask controls which functions are running or reserved when the call enters the connected state Reserved indicates that the DSP MIPS have been committed to the operation before the operation starts The application must reserve DSP resources in advance by using mediamask for DTMF detection silence detection cleardown detection and echo cancellation The ADI service initiates echo cancellation when a telephony protocol is started The appropriate parameters must be set before calling adiStartProtocol or nccStartProtocol For information on the echo cancellation parameters refer to ADI_START_PARMS on page 264 The echo canceller parameters c
159. ecords speech data directly to or from an IP endpoint with no transcoding For information on the native play and record feature refer to Performing NMS native play and record on page 31 NMS Communications 143 Function reference ADI Service Developer s Reference Manual For more information see Encoding formats and DSP files on page 134 The table lists the DSP files that must be loaded on the AG and CG boards It also lists the valid encoding types that QX boards and PacketMedia HMP processes support Refer to the board installation and developer s manual for MIPS usage Use adiRecordAsync to initiate a voice record operation The data is supplied to the application in a sequence of buffers The application submits empty buffers using adiSubmitRecordBuffer for the duration of the operation These buffers are then filled with recorded voice data and ADIEVN_RECORD_BUFFER_FULL events are returned The application has complete latitude and responsibility for allocating flushing and submitting the buffers When the ADI service needs another buffer it sets the ADI RECORD BUFFER REQ bit in the event value field for ADIEVN RECORD STARTED ADIEVN RECORD BUFFER FULL The application responds by submitting another empty buffer using adisubmitRecordBuffer The application submits buffers only when requested by the ADI service The ADI service owns the buffer until either ADIEVN RECORD BUFFER FULL or ADIEVEN RECORD DONE is delivered to the
160. efined in the adidef h and ctaerr h include files The error codes are prefixed with ADIERR_ or CTAERR_ For a complete list of CTAERR codes refer to the Natural Access Developer s Reference Manual Asynchronous functions return SUCCESS if the input arguments and context state are valid for the given function and if the ADI service sent the command to the hardware providing the service SUCCESS in this case means the function was initiated and a DONE event is generated for the function The following table alphabetically lists the ADI service errors Error name Hex Decimal Description ADIERR CANNOT CREATE CHANNEL 0x00010006 65542 Unable to create a channel to the board due to either board or driver limitations ADIERR INVALID CALL STATE 0x00010005 65541 Function not valid in the current call state For example many functions require the call to be in ADI CC STATE CONNECTED ADIERR INVALID QUEUEID 0x00010002 65538 Bad queue or driver ID ADIERR NO DSP PORT 0x00010007 65543 No input or output stream for requested function ADIERR NO DSP RESOURCES 0x00010008 65544 Not enough free DSP resources to run the requested function ADIERR NOT ENOUGH RESOURCES 0x0001000A 65546 Unable to obtain port resource from on board resource management ADIERR ACCESS 0x00010001 65537 User callback routine for playing or recording returned a value other than SUCCESS or ADI PLAY LAST BUFFER ADIE
161. emote party are appended to the queue as shown in the following illustration The digit is stored in the ADI service digit queue when ADIEVN_DIGIT_BEGIN is received If the ADI service digit queue is full when ADIEVN_DIGIT_BEGIN arrives the oldest digit is discarded and the latest digit is queued The ADI service digit queue can hold 64 digits NMS Communications 53 Developing applications ADI Service Developer s Reference Manual The following illustration shows background digit collection ADI ee service User buffer ADI service digit ADIEVN_DIGIT_BEGIN 8 queue s ADIEVN DIGIT END 8 ADIEVN DIGIT BEGIN 3 ADIEVN_DIGIT_END 3 adiCollectDigits 8 3 ADIEVN_DIGIT_BEGIN 7 ADIEVN_COLLECTION_DONE ADIEVN_DIGIT_END 7 The ADI service provides four synchronous functions that access the internal ADI service digit queue Function Description adiGetDigit Retrieves a single digit from the ADI service internal digit queue thus removing the oldest digit from the queue If the queue is empty a zero 0 is returned otherwise the ASCII value is returned adiInsertDigit Inserts a digit at the end of the ADI service internal digit queue adiPeekDigit Retrieves the oldest digit from the ADI service internal digit queue without removing the digit from the queue adiFlushDigitQueue Discards all digits
162. ence Manual Function reference adiStartReceivingFSK Receives frequency shift key FSK data Supported board types Prototype DWORD adiStartReceivingFSK CTAHD ctahd void buffer unsigned bufsize ADI FSKRECEIVE PARMS parms Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext buffer Pointer to buffer to hold received data bufsize Size of buffer to receive parms Pointer to the FSK receive parameters stored in the following structure NULL designates default values typedef struct 1 Return values Return value SUCCESS CTAERR BAD ARGUMENT CTAERR FUNCTION ACTIVE CTAERR INVALID CTAERR INVALID STATE CTAERR SVR COMM NMS Communications DWORD size Size of this structure sl INT32 minlevel Required minimum receive level dB 8 DWORD minmark Minimum required initial mark and seizure DWORD droptime Minimum dropout to silence before a packet is considered terminated ms DWORD baudrate Baud rate only 1200 supported yf ADI FSKRECEIVE PARMS Refer to ADI FSKRECEIVE PARMS on page 261 for field descriptions Description buffer is NULL or size is O zero Function already started Context handle is invalid Function not valid in the current port state Server communication error 179 Function reference ADI Service Developer s Reference Manual Events Event Descri
163. ence detector in use by a record function CTAERR SVR COMM Server communication error Events Description ADIEVN ENERGY DETECTED Energy detector reporting energy ADIEVN ENERGY DETECT DONE Energy detector terminated ADIEVN SILENCE DETECTED Energy detector reporting silence NMS Communications 165 Function reference ADI Service Developer s Reference Manual Details The following DSP file must be loaded to the board before running adiStartEnergyDetector For these boards Load this DSP file AG dtmf m54 or dtmfe m54 CG dtmf f54 or dtmfe f54 The standard DSP file See DSP file summary on page 269 for DSP file descriptions Refer to the board installation and developer s manual for a table of MIPS usage for all functions Use this function to start a low level energy detector that reports energy and silence transitions thresholdampl is the dBm threshold below which is considered silence Once energy or silence is internally qualified as detected the deglitch time is used during transitions above and below the threshold The autostop field indicates that the function stops once energy or silence is detected The maximum valid value for energyqual and silencequal is 65535 If autostop is set ADIEVN_ENERGY_DETECT_DONE is received with the value field set to CTA_REASON_FINISHED and the size field is set to either ADIEVN_ENERGY_DETECTED or ADIEVN_SILENCE_DETECTED In continuous mode
164. end status automatically 2 0 Enable HPF on reference stream not used in v3 and up 1 Disable HPF on reference stream 3 0 Disable comfort noise generation used in v3 and up 1 Enable comfort noise generation 0 Enable HPF on echo input stream not used in v3 and up 1 Disable HPF on echo input stream Control flags 4 0 Normal 1 Reset filter taps to zero 5 0 Normal 1 Bypass echo canceler 6 0 No adapt filter taps 1 Adapt filter taps 7 0 Enable NLP echo suppressor 1 Disable NLP Status flags 8 0 Diverged 1 Converged 9 0 Double talk 1 Qualifying no double talk 10 0 Double talk 1 Qualified no double talk 11 0 Not suppressing output 1 Suppressing output 12 0 Normal 1 Possible double talk but energy still within range of estimated ERL See also adiStartProtocol 126 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 127 Function reference ADI Service Developer s Reference Manual adiModifyPlayGain Sets the play gain for the duration of the active play operation Supported board types e PacketMedia process Prototype DWORD adiModifyPlayGain CTAHD ctahd int gain Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext gain The gain dB applied to the data as it is playing The valid range is 54 through 24 Return values ee
165. ene ert ex E A CREER 128 adiMo difyPlaySpeed us iene ava tor Beenie aa teres TA EN CERES 130 ev 131 ACIPIAVASYING 2 seti ade aie xA ER ee ERA n 132 ACIPIAYFrOMMEMOLy 136 adiQ erySigrnalState tini licere eiua 139 adiRecordASync vA Ea via CER RUNE 141 adiRecordToMemory e Rev eed nee eased 145 adiSetBoardCGlOCKk 5 2 2 0 heated oae ag gius 149 adiSetNativeInfo 1 secet mese vn Ra REN NA es 150 adiStartCallProgress rer er e Un ERR RR RR RR t a ek aa 154 AdIStartDial sts EET 158 adiStartDTMF eti tices dias cand 161 adiStartDTMFDetectOr vives iis erika eaters YR ORE E a A TEE E Sa vee as 163 adiStartEnergyDetector siesta tse EE Rad LET RR TRES 165 adiStartMEDetectOr 222 ete ve x Vion Ra CER Lee ER RAE Ta Xa EDEN ES 167 adiStartPlayirig oak ce e eR eR ERRARE REA OX RHENO Ra ERRARE EAR ERA 170 AadIStartProtocol
166. ent gt value x n event value break 94 NMS Communications ADI Service Developer s Reference Manual Function reference adiFlushDigitQueue Flushes the internal digit collection queue Supported board types e PacketMedia process Prototype DWORD adiFlushDigitQueue CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values Return value Description SUCCESS CTAERR_FUNCTION_ACTIVE Digit collection function is active CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_SVR_COMM Server communication error Details Use adiFlushDigitQueue to discard all digits in the ADI service internal digit collection queue This function cannot be invoked while the application is actively collecting digits using adiCollectDigits If any digits are queued in the ADI service when a play or record voice operation is started and the voice operation is to terminate on those specific touchtones the voice operation terminates immediately To prevent this from happening use adiFlushDigitQueue or adiGetDigit to remove the escape key from the queue The digit queue is automatically flushed when a call is released For more information refer to Collecting digits on page 53 See also adiPeekDigit adiStopCollection NMS Communications 95 Function reference
167. er CTAERR_FUNCTION_ACTIVE Digit collection function is already active CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_SVR_COMM Server communication error Details Use adiGetDigit to retrieve a single DTMF digit character from the front of the ADI service internal digit queue The oldest digit is removed from the queue and copied to the address pointed to by digit If the digit queue is empty the value copied is 0 zero The application must also be using ctaWaitEvent for digits to accumulate in the ADI service internal digit queue This function cannot be invoked if the application is actively collecting digits using adiCollectDigits To read the first digit without removing it from the collection queue use adiPeekDigit If there is a digit in the internal digit queue that is configured in the abort_mask of a play or record operation to terminate the operation the operation terminates immediately Use adiGetDigit to remove the digit from the queue For more information refer to Collecting digits on page 53 NMS Communications 109 Function reference ADI Service Developer s Reference Manual See also adiFlushDigitQueue adiStopCollection Example Remove and display digits in the digit queue void getandshowdigits CTAHD ctahd for char adiGetDigit ctahd amp digit UNO S break
168. er e value Flags If the ADI RECORD BUFFER REQ bit is set more buffers are needed and the application must submit another empty buffer If the ADI RECORD UNDERRUN bit is set an underrun occurred There was no new buffer to record information when this one was completed ADIEVN RECORD DONE Generated when the record operation completes The event size field contains the total number of bytes recorded during the record instance lifetime The value field contains one of the following termination reasons or error codes REASON DIGIT Aborted due to DTMF CTA REASON NO VOICE No voice detected CTA REASON RELEASED Call terminated CTA REASON STOPPED Stopped by application request CTA REASON TIMEOUT Record time limit maxmsec reached REASON VOICE END User stopped speaking CTAERR FUNCTION NOT AVAIL Required DSP file not loaded on the board CTAERR xxx or ADIERR Xxx Record failed Details When recording or playing speech files on AG boards a specific DSP file must be loaded for each encoding type For QX boards the standard DSP file supports the valid encoding types For more information refer to Voice encoding formats on page 13 When recording or playing speech files on CG boards a specific DSP file must be loaded for each encoding type except when using the native play and record feature The native play and record feature combines an ADI port with an MSPP endpoint and plays or r
169. er second for given encoding format maxbufsize Pointer to returned board buffer size in bytes for given encoding format on the specified context For information specific to QX boards refer to the QX 2000 Installation and Developer s Manual Return values Return value Description SUCCESS CTAERR_BAD_ARGUMENT Invalid encoding format CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_SVR_COMM Server communication error Details Use adiGetEncodingInfo to return data size information for the given encoding format on the specified context When submitting buffers of voice data for play or record the buffers must be an integral multiple of the encoding frame size and should be a multiple of the board s physical buffer maxbufsize All buffers of voice data submitted to the ADI service must be an integral number of framesize bytes For example if the frame size is 62 bytes a submitted buffer must be sized as n x 62 bytes where n 1 2 3 NMS Communications 113 Function reference ADI Service Developer s Reference Manual The datarate is provided for resource management optimization The datarate defines the required throughput between the host CPU and AG board in bytes second It can be used for positioning For example to skip ahead four seconds in a message move your data pointer 4 x datarate bytes modulo framesize The maxbufsize is the maximum
170. ervice sends the initial buffer to the board The board responds with ADIEVN_RECORD_STARTED at which time the board is actively recording The application must submit the second required record buffer if the ADI RECORD BUFFER REQ bit is set in the event s value field The record function enters the active state after receiving ADIEVN RECORD STARTED The record function remains active until one of the terminating conditions described in Terminating record on page 20 occurs The ADI service and the application exchange buffer full events and submit buffer commands while in this state as described e The ADI service generates ADIEVN RECORD BUFFER FULL when a record buffer is full e Inresponse the application invokes adiSubmitRecordBuffer to continue recording e maximum of two user record buffers can be actively submitted at any given time adisubmitRecordBuffer returns the error ADIERR TOO MANY BUFFERS if a third buffer is submitted The application can immediately abort the record function by invoking adiStopRecording The ADI service does not execute any more record functions from the application while in the stopping state Any record functions invoked by the application result in the ADI service returning CTAERR INVALID SEQUENCE When ADIEVN RECORD DONE is delivered to the application the record state returns to idle NMS Communications ADI Service Developer s Reference Manual Developing applications Recording w
171. etection SWI_TERM NUS input 2 SWI TERMINUS output 2 output bus MVIP95 LOCAL BUS output Stream BoardStream output timeslot record timeslot Stream BoardStream timeslot fusion timeslot bus MVIP95 MVIP BUS 0 0 0 output 1 bus MVIP95 LOCAL BUS 1 01 42 NMS Communications ADI Service Developer s Reference Manual Developing applications input 0 stream BoardStream 1 input 0 timeslot fusion timeslot input 1 bus MVIP95 MVIP BUS input 1 stream BoardStream 1 imone aee com swiMakeConnection swihd input output 2 get cg6xxx board handle ret mspGetFilterHandle msphd MSP FILTER JITTER amp cg6xxx board filter handle ADI NATIVE CONTROL parms 0 fps Native parameters B parms frameFormat 0 parms include2833 OF parms vadFlag OF parms nsPayload 02 parms mode ADI NATIVE parms rec encoding ADI ENCODE EDTX MU LAW parms payloadID 0 ret adiSetNativeInfo ctahd cg6xxx_board_filter_handle NULL this is record only so no egress handle amp parms get default adi record parms ret ctaGetParms ctahd ADI RECORD PARMID amp recparms sizeof ADI RECORD PARMS ret adiRecordToMemory ctahd ADI ENCODE EDTX MU LAW audio rec MemoryBuffer RecordedBytes amp recparms adiStopRecording ctahd Managing call progress Call progress functions monitor in band energy to detect network
172. eturns an MSPP service endpoint handle ephd mspCreateEndpoint ctahd mspaddrstruct mspparmstruct amp rtpephd 6 Invoke mspGetFilterHandle to retrieve the runtime filter ID associated with the RTP endpoint handle ephd The application uses the returned as the destination for the audio stream played out from the ADI port mspGetFilterHandle rtpephd MSP ENDPOINT RTPFDX amp fltID 7 Invoke adiSetNativeInfo to set NMS native play parameters specifying both the context handle of the ADI port and the RTP endpoint returned by mspGetFilterHandle adiSetNativeInfo ctahd NULL fltlID fltlID parms 8 Invoke adiPlayFromMemory to begin playing a message adiPlayFromMemory ctahd encoding buffer bufsize parms 9 Invoke adiStopPlaying to stop playing the message adiStopPlaying ctahd 34 NMS Communications ADI Service Developer s Reference Manual Developing applications Example The following example shows how to perform a native play operation ret ctaCreateQueue NULL 0 amp hCtaQueueHd ret ctaCreateContext hCtaQueueHd 0 Play amp ctahd ServiceCount 2 ServDesc 0 name svcname ADI ServDesc 0 name svcmgrname ADIMGR ServDesc 0 mvipaddr board board ServDesc 0 mvipaddr mode 0 ServDesc 1 name svcname MSP ServDesc 1 name svcmgrname MSPMGR ret ctaOpenServices ctahd ServDesc ServiceCount ret WaitForSpecificEvent CTAEVN OPEN SERVICES DONE amp event
173. ext has up to six programmable tone detectors If the current telephony protocol employs an in band cleardown tone detector the first tone detector is not available The tone detectors can generate the following events e ADIEVN TONE n BEGIN where n is the programmable tone ID 1 6 e ADIEVN TONE n END where n is the programmable tone ID 1 6 This topic presents e Starting tone detection e Stopping tone detection Starting tone detection In addition to the tone detector identifier that specifies a tone ID of 1 through 6 adiStartToneDetector takes four parameters that describe a single or dual frequency tone Parameter Description Frequency 1 The center frequency in Hz of a single tone or the first of two frequencies a dual tone bandw Bandwidth 1 The bandwidth around Frequency 1 that is acceptable freq2 Frequency 2 The center frequency in Hz of the second of two frequencies in a dual tone Set this value to zero for single frequency tones bandw2 Bandwidth 2 The bandwidth around Frequency 2 that is acceptable Set this value to zero for single frequency tones 50 NMS Communications ADI Service Developer s Reference Manual Developing applications The range of frequencies detected is the center frequency plus or minus one half of the bandwidth The following illustration describes the tone detection frequency parameters Hz Frequency 4 Bandwidth lt You further mod
174. fault Units Description baudrate DWORD 1200 integer Transmission baud rate 1200 is the only valid value level INT32 14 dBm Transmit output level marktime DWORD 500 ms Length of initial mark signal noseizureflag DWORD 1 integer Controls whether channel seizure is omitted e 0 send channel seizure e 1 just send mark seizetime DWORD 1000 ms Duration of channel seizure ignored if noseizureflag 1 ADI_PLAY_PARMS Dependent functions adiStartPlaying adiPlayFromMemory adiPlayAsync Field Type Default Units Description name DTMFabort DWORD OxFFFF mask Mask that enables you to control which DTMFs abort play See Valid DTMF values on page 256 gain INT32 0 dB Gain applied to the encoded audio Ignored for encoding types for which applied gain is not supported Valid AG board CG board and PacketMedia HMP range is 54 through 24 Valid QX board range is 48 through 42 maxspeed DWORD 100 percent Maximum speed that is used Determines how much DSP processing power is allocated to the play function The valid AG board and CG board range is 100 through 200 Ignored for encoding types for which speed modification is not supported Not used for QX boards speed DWORD 100 percent Initial speedup or slowdown factor to apply to the encoded audio The valid AG board and CG board range is 50 to maxspeed Ignored for encoding types for which speed modification is not supported Not used for QX boards
175. ffer bufsize Number of bytes stored at the address in buffer flags Indicates if the specified buffer is the only buffer to be played can be set to ADI_PLAY_LAST_BUFFER or 0 parms Pointer to play parameters according to the following structure NULL value uses the default play parameters typedef struct DWORD size size of this structure a DWORD DTMFabort abort on DTMF INT32 gain playing gain in dB oA DWORD speed initial speed in percent AG boards only DWORD maxspeed max play speed in percent AG boards only ADI PLAY PARMS Refer to ADI PLAY PARMS on page 261 for field descriptions and valid values Return values Return value Description SUCCESS ADIERR INVALID CALL STATE Function not valid in the current call state CTAERR BAD ARGUMENT Either invalid encoding or NULL buffer CTAERR BAD SIZE bufsize is not a multiple of framesize for selected encoding CTAERR FUNCTION ACTIVE Function already started CTAERR INVALID CTAHD Context handle is invalid CTAERR INVALID STATE Function not valid in the current port state CTAERR OUTPUT ACTIVE Play failed because there is another active output function CTAERR SVR COMM Server communication error 132 NMS Communications ADI Service Developer s Reference Manual Function reference Events Event Description ADIEVN_PLAY_BUFFER_REQ Generated when the ADI service needs a buffer containing voice data The application respon
176. fore the operation terminates e Record synchronization prompt frequency amplitude and duration e Automatic gain control settings For QX boards refer to the QX 2000 Installation and Developer s Manual for each category of structure and default parameters values For information about parameter management in Natural Access refer to the Natural Access Developer s Reference Manual NMS Communications 253 Parameters ADI_CALLPROG_PARMS ADI Service Developer s Reference Manual Dependent function adiStartCallProgress Field name busycount leakagetime maxbusy maxreorder maxring maxringperiod noiselevel precmask precqualtime 254 Type DWORD DWORD DWORD DWORD DWORD DWORD DWORD DWORD DWORD Default 4 1500 700 3000 8000 0x14000 7 150 Units Description count ms ms ms ms ms IDU mask ms Number of non precise busy tones that must occur before busy or fast busy is reported Valid range is 1 through 32767 Do not modify Threshold time defining the total time period on time plus off time for distinguishing between slow busy and ringing tone Valid range is 0 through 32767 Threshold time defining the total time period on time plus off time for distinguishing between fast busy reorder and slow busy Valid range is 0 through 32767 Maximum duration of a tone to distinguish a ringing tone from a dial tone Vali
177. g These settings ensure that the default DSP to line interface connections are set up by NMS OAM 232 NMS Communications ADI Service Developer s Reference Manual Demonstration programs To run hostp2p Step 1 Action Start hostp2p by entering the following command at the prompt hostp2p 1 0 d digits hostp2p starts and the following information appears CTA host port to port voice Demo V 1 0 Dec 5 1997 Port 1 Board 0 Stream 0 Slot 0 Protocol 1 50 Port 2 Board 0 Stream 0 Slot 1 Protocol 1 50 Encoding 10 Buffer time 60 msec Echocanceling length 4 msec adapt time 100 msec Initializing and opening the CTA context Daemon not running Using process global default parms Trace disabled Wabting for incoming call hostp2p waits for an incoming call Place a call to the telephone line connected to port The following information appears incoming Call Answering call Call connected em cedi me 55512129 hostp2p places a call to the number you specified When the called party answers you have a connection NMS Communications 233 Demonstration programs ADI Service Developer s Reference Manual Play and record playrec playrec demonstrates voice play and record using asynchronous buffer submission and play and record callback routines This demonstration operates in two phases asynchronous voice play and record operations and callback voice play and record
178. git is a NULL pointer CTAERR_FUNCTION_ACTIVE Digit collection function is already active CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_SVR_COMM Server communication error Details adiPeekDigit reads a single DTMF digit character from the front of the ADI service internal digit queue without removing it The digit is copied to the address pointed to by digit Valid digit values are the ASCII characters 0 through 9 number sign and asterisk as well as A B C and D If the digit queue is empty the value is 0 zero This function cannot be invoked if the application is actively collecting digits using adiCollectDigits For more information refer to Collecting digits on page 53 See also adiFlushDigitQueue adiStopCollection NMS Communications 131 Function reference ADI Service Developer s Reference Manual adiPlayAsync Initiates a voice play operation with asynchronous buffer submission Supported board types e PacketMedia process Prototype DWORD adiPlayAsync CTAHD ctahd unsigned encoding void buffer unsigned bufsize unsigned flags ADI PLAY PARMS parms Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext encoding Data encoding format See Voice encoding formats on page 13 for a complete list buffer Pointer to initial voice data bu
179. he voice end time period see the CTA_REASON_VOICE_END voice end illustration The remote party spoke longer than the maximum duration see the CTA_REASON_TIMEOUT timeout illustration 20 NMS Communications ADI Service Developer s Reference Manual Record termination no voice The following illustration shows record termination no voice Start Record recording started command event Record done event REASON_NO_VOICE Time 5 gt novoicetime beeptime maxtime Record termination voice end The following illustration shows record termination voice end Start Record recording started command event Record done event 5 VOICE END Call me at work Qe FS gt hovoicetime beeptime silencetime maxtime Record termination timeout The following illustration shows record termination timeout Start Record Record done event recording started REASON TIMEOUT command event B I m going to leave instructions about 5 gt 5 beeptime Time maxtime NMS Communications Developing applications 21 Developing applications ADI Service Developer s Reference Manual Three timer parameters terminate the record function Parameter Description novoicetime Time in milliseconds that the remote party has after the beep sync prompt to start speaking novoicetime is stored in the
180. iRecordToMemory ctahd buf bufsize rec param Invoke adiStopRecording stop recording the audio portion of the message adiStopRecording ctahd NMS Communications ADI Service Developer s Reference Manual Developing applications Example The following example shows how to perform a native record operation that supports ADI silence and DTMF detection on CG boards ret ctaCreateQueue NULL 0 amp hCtaQueueHd create context for ADI port ret ctaCreateContext hCtaQueueHd 0 Record amp ctahd ServiceCount 1 ServDesc 0 name svcname ADI ServDesc 0 name svcmgrname ADIMGR ServDesc 0 mvipaddr mode ADI VOICE DUPLEX ServDesc 0 mvipaddr stream 0 ServDesc 0 mvipaddr timeslot record_timeslot ret ctaOpenServices ctahd ServDesc ServiceCount ret WaitForSpecificEvent CTAEVN OPEN SERVICES DONE amp Event printf Failed to receive CTAEVN OPEN SERVICES DONE event return FAILURE adiStartProtocol adiStartProtocol ctahd nocc NULL NULL if WaitForSpecificEvent ADIEVN STARTPROTOCOL DONE amp Event 5000 printf Failed to receive ADIEVN STARTPROTOCOL DONE event return FAILURE ret swiOpenSwitch ctahd agsw Board 0 amp swihd if ret SUCCESS printf Makeconnections Failed to open board dWMn Board return FAILURE create context for MSPP channel ret ctaCreateContext hCtaQueueHd 0 MSPP amp ipHd ServiceCount 2
181. ications Transferring voice data during record follows this process 1 The application initiates recording in asynchronous mode by invoking adiRecordAsync 2 The ADI service generates ADIEVN_RECORD_STARTED to inform the application to submit the second buffer 3 The application submits the buffer by invoking adiSubmitRecordBuffer The ADI service sends ADIEVN_RECORD_BUFFER_FULL to the application when a record buffer has been filled The buffer address and size are provided 5 If the ADI RECORD BUFFER REQ bit is set in the value field in ADIEVN_RECORD_BUFFER_FULL the ADI service needs another record buffer In response the application invokes adiSubmitRecordBuffer 6 Steps 2 5 are repeated until recording completes and the ADI service generates ADIEVN_RECORD_DONE The following illustration shows the complete life cycle for record using asynchronous data transfer ADIEVN_RECORD_BUFFER_FULL adiSubmitRecordBuffer ADIEVN_RECORD_DONE ADIEVN_RECORD_STARTED adiRecordAsync adiStopRecording ADIEVN_RECORD_DONE adiStopRecording ADIEVN_RECORD_DONE NMS Communications 23 Developing applications ADI Service Developer s Reference Manual The states for asynchronous record transfer are as follows State Idle Wait record started Active Stopped 24 Description The function is not active The record function enters this state when the application invokes adiRecordAsync The ADI s
182. icted when running other CAS protocols For example all channel associated signaling CAS protocols reserve out of band signaling so ADI service functions that perform out of band signaling may not be available For information about CAS protocols refer to the NMS CAS for Natural Call Control Developer s Manual The following low level control functions are available in the ADI service If you want to Then use Assert an out of band signaling pattern adiAssertSignal Pulse an out of band signaling pattern for a duration adiStartPulse Start detection of out of band signaling bits adiStartSignalDetector Stop detection of out of band signaling bits adiStopSignalDetector Query the current inbound out of band signaling bits adiQuerySignalState Start DTMF pulse dialing of digits adiStartDial Stop DTMF pulse dialing of digits adiStopDial The out of band signaling functions relate to either the physical out of band signal bits of digital protocols or the control of analog interface boards In both cases four signaling bits are addressed A B C and D often written as ABCD and defined by a bit mask 0 8 0x4 0 2 Ox1 respectively When using these functions refer to the appropriate manual for your telephone line interface board adiStartDial and adiStopDial enable you to perform dialing operations when you are not running formal call control NMS Communications 71 Developing applications ADI Service Developer s
183. id encoding or NULL buffer CTAERR_FUNCTION_ACTIVE Function already started CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_OUTPUT_ACTIVE Record failed because there is another active output function CTAERR_RESOURCE_CONFLICT Silence detector is in use by adiStartEnergyDetector CTAERR_SVR_COMM Server communication error Events Event Description ADIEVN_RECORDING_DONE Generated when the recording operation terminates The event size field contains the total number of bytes written into the buffer The value field contains one of the following termination reasons or error codes CTA_REASON_DIGIT Aborted due to DTMF CTA_REASON_FINISHED Buffer filled CTA_REASON_NO_VOICE No voice detected CTA_REASON_RELEASED Call terminated CTA_REASON_STOPPED Stopped by application request CTA_REASON_VOICE_END User stopped speaking CTAERR_FUNCTION_NOT_AVAIL Required DSP file not loaded on the board CTAERR_xxx or ADIERR_xxx Record failed 146 NMS Communications ADI Service Developer s Reference Manual Function reference Details When recording or playing speech files on AG boards a specific DSP file must be loaded for each encoding type For QX boards the standard DSP file supports the valid encoding types For more information refer to Voice encoding formats on page 13 When recording or playing speech files on CG boards a specific DS
184. ield in the MVIP_ADDR structure passed to ctaOpenServices to ADI_AG_DRIVER_ONLY This function also works with a context that has the ADI service opened on actual MVIP streams and timeslots Note QX 2000 boards do not support this function If this function is called using a 2000 board CTAERR_FUNCTION_NOT_AVAIL is returned NMS Communications 111 Function reference See also adiGetBoardInfo Example 5 Lomake Vane alia void showeeprom unsigned drvid ADI_EEPROM_DATA eeprom adiGetEEPromData drvid 0 sizeof eeprom amp eeprom printf data 0 x n eeprom data 0 112 ADI Service Developer s Reference Manual NMS Communications ADI Service Developer s Reference Manual Function reference adiGetEncodingInfo Returns data size parameters for a given voice encoding format on a specified context Supported board types e PacketMedia process Prototype DWORD adiGetEncodingInfo ctahd unsigned encoding unsigned framesize unsigned datarate unsigned maxbufsize Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext encoding Data encoding method See Voice encoding formats on page 13 for a complete list of valid encoding methods framesize Pointer to returned size in bytes of a single voice frame for given encoding format datarate Pointer to returned required throughput in bytes p
185. ify the tone detector s default behavior by specifying the following parameters which reside in the ADI_TONEDETECT_PARMS structure when invoking adiStartToneDetector or by modifying the system defaults Parameter Description qualampl Qualification amplitude the broadband qualification level in dBm required to further qualify any energy as tone qualtime Qualification time the time in milliseconds in which the tone must be present before reporting ADIEVN_TONE_n_BEGIN After qualifying at tone this parameter is used to qualify the absence of the tone to report ADIEVN_TONE_n_END The following illustration describes the tone detection qualification parameters Signal qualtime amplitude qualtime Time Note Do not modify the reflevel and reserved parameters in ADI_TONEDETECT_PARMS These parameters apply to the DSP algorithms and are provided for diagnostic purposes when working with NMS Technical Services Stopping tone detection adiStopToneDetector immediately terminates a tone detector The ADI service generates ADIEVN_TONE_n_DETECT_DONE with the value set to CTA_REASON_STOPPED The ADI service can also generate ADIEVN_TONE_n_DETECT_DONE with an error code ADIERR xxx or CTAERR xxx if the function is incorrectly started NMS Communications 51 Developing applications ADI Service Developer s Reference Manual Generating tones NMS Communications boards are cap
186. ight 1 1 70 Because the event timestamp is 32 bits it wraps every 2 milliseconds about 49 days adiGetTimeStamp assumes the event occurred within 24 days Note This function is not supported on a QX 2000 board If this function is called using a QX 2000 board CTAERR_FUNCTION_NOT_AVAIL is returned Use ctaGetTimeStamp instead NMS Communications 119 Function reference ADI Service Developer s Reference Manual Example 120 NMS Communications ADI Service Developer s Reference Manual Function reference adiInsertDigit Inserts a digit at the end of the ADI service internal digit queue Supported board types e QX e AG e CG e PacketMedia process Prototype DWORD adiInsertDigit CTAHD ctahd char digit Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext digit Alphanumeric characters to store in the digit queue Valid values are ASCII characters 0 through 9 number sign and asterisk as well as A B C and D Return values Return value Description SUCCESS CTAERR_BAD_ARGUMENT digit is not a valid character CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Protocol not started CTAERR_SVR_COMM Server communication error Details Use adiInsertDigit to insert a digit into the ADI digit queue If digit collection is active the digit is moved to the collection buffer and the interdigit timer is reset This func
187. in nms include evad h EVAD_EVN_FUNCTION_DISABLED Voice activity detection disabled EVAD_EVN_FUNCTION_ENABLED Voice activity detection enabled EVAD_EVN_FUNCTION_ERROR Unknown or invalid parameter EVAD_EVN_SIGNALLING_DISABLED Voice activity detection messaging disabled EVAD_EVN_SIGNALLING_ENABLED Voice activity detection messaging enabled EVAD_EVN_SPEECH_BEGIN Speech started The event buffer contains the energy of the frame generating the event and the energy of the background noise in dB EVAD_EVN_SPEECH_END Speech stopped The event buffer contains the energy of the frame generating the event and the energy of the background noise in dB EVAD_EVN_STREAMING_PAUSED Voice streaming from board to application paused EVAD_EVN_STREAMING_RESUMED Voice streaming from board to application resumed Note The application receives ADIEVN_RECORD_EVENT asynchronously while the speech buffers arrive every buffersize x framerate framesize msec attached to ADIEVN_RECORD_BUFFER_FULL when speech is detected Details The following DSP file must be loaded to the board to enable voice activity detection For these boards Add this DSP file rvoice_vad m54 rvoice_vad f54 To configure CG boards for voice activity detection specify rvoice_vad in the resource definition For example Resource 0 Definitions dtmf det all amp rvoice vad rec alaw amp rvoice vad play alaw To configure the PacketMedia HM
188. in the current port state CTAERR_NO_MEMORY Could not allocate an internal buffer CTAERR_NOT_IMPLEMENTED Function not implemented CTAERR_OUTPUT_ACTIVE Play failed because there is another active output function CTAERR_SVR_COMM Server communication error Events Event Description ADIEVN_PLAY_DONE Playing terminated with one of the following reasons in the value field CTAERR xxx ADIERR Xxx Error codes indicate play failed CTA REASON DIGIT Aborted due to DTMF REASON FINISHED ADI service finished playing the last buffer REASON RECOGNITION Aborted because of speech recognition CTA REASON RELEASED Call terminated CTA_REASON_STOPPED Stopped by application request Details When recording or playing speech files on AG boards a specific DSP file must be loaded for each encoding type For QX boards the standard DSP file supports the valid encoding types For more information refer to Voice encoding formats on page 13 When recording or playing speech files on CG boards a specific DSP file must be loaded for each encoding type except when using the native play and record feature The native play and record feature combines an ADI port with an MSPP endpoint and plays or records speech data directly to or from an IP endpoint with no transcoding For information about the native play and record feature refer to Performing NMS native play and record on page 31 NMS Communications 171 F
189. info address The ADI service stores the actual number of bytes written in the ADI BOARD INFO size field See also adiGetEEPromData 98 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 99 Function reference ADI Service Developer s Reference Manual adiGetBoardSlots Returns the MVIP timeslots configured for the given board Supported board types e PacketMedia HMP process Prototype DWORD adiGetBoardSlots CTAHD ctahd unsigned board unsigned mode unsigned maxslot ADI_TIMESLOT s otlist unsigned numslots Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext lt board Board number as specified in the board keyword file mode Stream capability which can be either ADI_FULL_DUPLEX both voice and signaling streams or ADI_VOICE_DUPLEX voice only I maxslot Maximum number of entries in slotlist array _ slotlist Pointer to the ADI_TIMESLOT array defined as typedef struct BYTE stream BYTE slot s ADI_TIMESLOT I numslots Returned number of entries Return values m Return value Description SUCCESS CTAERR_BAD_ARGUMENT slotlist is NULL but maxslot is not zero or maxslot is 0 zero but slotlist is not NULL or numslots is NULL or invalid mode _ CTAERR_INVAL
190. ing voice activity detection events EVAD_SPEECH_BEGIN and EVAD_SPEECH_END to the host application When enabling voice activity detection EVAD_CDE_FUNCTION_ENABLE modify the voice activity detector s default behavior with the following parameters also defined in nms include evad h Parameter Type Default Units Description INT16 Signal to noise ratio Valid range is 5 to 30 dB hold stop INT16 1000 Speech hangover time Valid range is 300 to 2000 ms min noise INT16 Minimum noise floor Valid range is 100 to 40 dB max_noise INT16 40 dB Maximum noise floor Valid range is 65 to 25 dB signal_attack INT16 30 ms Signal attack time constant Valid range is 10 to 200 ms signal_release INT16 60 ms Signal release time constant Valid range is 10 to 200 ms noise_attack INT16 3000 ms Noise attack time constant Valid range is 500 to 5000 ms noise_release INT16 600 ms Noise release time constant Valid range is 100 to 2000 ms Convert signal_attack signal_release noise_attack and noise_release into DSP format using the following formula time constant tc and period need to have the same units of time int epsilon float to float period float eps LO rloa Cowal return int eps 32767 alin S15 essere LATENCY 10 10 msec record DPF period DSP_value epsilon time_constant LATENCY NMS Communications
191. ion is running in client server mode Usage threads options where options are Option Use this option to specify the bn Board number n Default is 0 s MVIP stream and timeslot for the first channel Default is 0 0 n nports Number of ports and threads to use Default is 1 p protocol Protocol to run Default is IpsO f filename Voice file to use for answering message Default is answer vce Encoding is assumed to be ADI ENCODE 5 24 Featured functions adiStartPlaying in DemoPlayFile Running threads Before running threads verify that your system has the proper configuration It must have the desired number of lines connected to loop start hybrids having the same MVIP stream and successive MVIP timeslots To run threads type the following command at the prompt threads b n s n m n nports p protocol f filename Specify the MVIP stream the lowest numbered MVIP timeslot and the number of timeslots to use The demonstration continues to answer all of the lines until you stop it by pressing Ctrl C Note Code in threads parses and documents the command line arguments and creates threads under various operating systems RunDemo performs the call handling 236 NMS Communications Errors Alphabetical error summary All ADI service functions return either SUCCESS or an error code indicating that the function failed and the reason for the failure ADI service error codes are d
192. ior for native record operations e Starts and stops recording audio data from a network audio stream The following illustration shows an overview of the native record mechanism with voice decoding enabled MSPP voice connection ADI port Voice channel LA voice decoder filter JO DSO endpoint RTP endpoint f Silence 1 PERS and DTMF D ADI detection service f gt Audio data Sample procedure Applications use functions from the following Natural Access resources to implement native record functionality with inband silence detection or DTMF detection e Natural Access functions to set up event queues and contexts and to open services on the contexts e ADI service functions to start a protocol set native record settings and record incoming audio data e MSPP functions to create a voice connection consisting of a voice decoding channel an RTP endpoint and a DSO endpoint and to retrieve the unique filter ID of the RTP endpoint s jitter filter e SWI functions to switch together the ADI service port and the MSPP service connection through the DSO endpoint The following procedure shows functions used to implement a typical native record operation with decoding on CG boards Step Action 1 Invoke ctaCreateQueue to create a Natural Access event queue ctaCreateQueue amp queuehd 2 Invoke ctaCreateContext to create a Natural Access context for the audio channel ctaCreateC
193. ission to and from four wire transmission Most modern circuit switched telephony switching is done at four wire points in a connection Older two wire switching still exists Each interface from a two wire to a four wire connection can be a source of echoes Therefore wherever possible minimize the use of two wire switching NMS Communications 65 Developing applications ADI Service Developer s Reference Manual Detecting energy The ADI service is capable of running an energy detector that examines the in band signal and reports energy and silence transitions Note Do not use the energy detector if you are using voice activity detection This topic presents e Starting energy detection e Stopping energy detection Starting energy detection adiStartEnergyDetector takes the following qualification time parameters Parameter Description energyqual Energy qualification time the time in milliseconds that energy must be present to report an energy event silencequal Silence qualification time the time in milliseconds that energy must be absent to report a silence event You can modify the energy detector s default behavior by specifying the following parameters stored in ADI_ENERGY_PARMS when invoking adiStartEnergyDetector Parameter Description thresholdampl Threshold amplitude the noise level in dBm below which is considered silence Noise above this level is further qualified as energy deglitch
194. it requires synchronous access to a storage medium DTMFabort mask By default the board terminates play and record when any DTMF key is entered You can specify which DTMF keys terminate the function using the DTMFabort mask in ADI PLAY PARMS on page 261 or ADI RECORD PARMS on page 262 The DTMFabort mask is a 16 bit entity in which each bit corresponds to a specific key on the telephone keypad Setting a bit in the mask terminates the voice function if that particular key is entered The DTMFabort mask corresponds to the DTMF telephone keys as shown Most significant bit to least significant bit 918 7 6 51 4 3 2 1 0 D C Bit position DTMF key NMS Communications 19 Developing applications ADI Service Developer s Reference Manual For example if the abort mask is set to OxO3FF the play or record function terminates if the remote party enters any digit from 0 through 9 The adidef h include file contains defines ADI_DTMF_xxx for each digit and for certain digit groups Note The DTMFabort mask has no effect on digit collection If any digits are queued in the ADI service when a play or record voice operation is started and the voice operation is to terminate on those specific touchtones the voice operation terminates immediately To prevent this from happening use adiFlushDigitQueue or adiGetDigit to remove the escape key from the queue The digit queue is automatically flushed whe
195. ith automatic gain control By default AGC is disabled and the record gain is determined only by the gain parameter To enable AGC set AGCenable in ADI RECORD PARMS to 1 The following illustration shows the automatic gain control AGC record parameters input signal output signal amplitude silence level time AGCtargetampl AGCsilenceampl AGCattacktime and AGCdecaytime control the behavior of the AGC The default values for these parameters are appropriate for most applications Refer to ADI RECORD 5 on page 262 for a description of each of the AGC parameters Note When AGC is enabled the gain parameter in ADI RECORD PARMS determines the gain applied when record begins AGC must be disabled if you are using voice activity detection Playing Playing follows this process 1 The application invokes a function to initiate playing 2 The ADI service prompts the application for data 3 The application provides data to the ADI service and can instruct the ADI service to automatically stop playing after the buffer plays by setting the ADI LASTBUFFER SUBMITTED flag Steps 2 and 3 are typically performed multiple times 4 The ADI service terminates play upon delivering ADIEVN PLAY DONE Refer to Terminating play on page 26 for termination reasons that can be included as part of the event The ADI PLAY PARMS structure contains the play function parameters NMS Communications 25
196. key FSK data Supported board types Prototype DWORD adiStopReceivingFSK CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Event Description ADIEVN_FSK_RECEIVE_DONE Generated by the ADI service when the FSK receive function terminates The event value field contains CTA_REASON_STOPPED Stopped by application request Details Use adiStopReceivingFSK to stop the receipt of data initiated by adiStartReceivingFSK For more information refer to Sending and receiving FSK data on page 69 NMS Communications 215 Function reference ADI Service Developer s Reference Manual adiStopRecording Stops the recording operation Supported board types e PacketMedia process Prototype DWORD adiStopRecording CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values a Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD
197. le summary on page 269 CG 6565 C boards and CG 6060 C boards use C5441 DSPs and not C5420 DSPs for applications The DSP files have f41 extensions instead of f54 extensions For information about configuring hardware echo cancellation on CG 6565 C boards and CG 6060 C boards refer to the board installation and developer s manual The default echo Echo In20_apt25 specified in the resource definition string has a 20 ms filter length and an adapt rate of 25 percent of the maximum adaptation rate If an echo different from Echo In20_apt25 is needed change the resource definition string Replace the current echo in the resource definition string with the new echo Note Changing a function in the resource definition string can decrease the number of ports that run on the board Each DSP function has its own resource requirement If the new function has higher resource requirements than the function it is replacing the number of ports the board can run can be less Refer to the board installation and developer s manual for more information Default filter length and adaptation time values To enable echo cancellation with default settings set ADI START echocancel mode or NCC X ADI_START echocancel mode to 1 The following table shows the default filter length and adaptation time values for each board type Board type Filter length Adaptation time CG 20 ms 200 25 percent of maximum adaptation rate AG 2000 AG 2000 4ms 100 ms A
198. lencetime Using call placement timeout Time To ensure that call placement is resolved within a certain time period the ADI service provides a timeout parameter The timeout parameter in ADI_CALLPROG_PARMS specifies the maximum time after the last detected event before the ADI service generates ADIEVN_CP_DONE with a value of CTA_REASON_TIMEOUT Setting the timeout parameter in ADI_CALLPROG_PARMS to zero overrides the timeout feature NMS Communications 47 Developing applications ADI Service Developer s Reference Manual Call progress tone events The call progress tone events are mapped from tone events described in e Telephone network tone detection e Precise tone detection e Broadband tone detection Call progress tone events are controlled by the ADI_CALLPROG_PARMS structure The following tones are detected by call progress If the detected tone is The ADI event is Dial tone ADIEVN_CP_DIALTONE Reorder tone ADIEVN_CP_REORDERTONE Ring tone ADIEVN_CP_RINGTONE Ring quit ADIEVN_CP_RINGQUIT SIT ADIEVN_CP_SIT Fax modem answer tone ADIEVN_CP_CED TDD TTY tone ADIEVN_CP_TDD Call progress voice events The call progress voice events are mapped from the voice events described in Voice detection on page 46 and are controlled by the ADI_CALLPROG_PARMS structure Whenever a voice event occurs during call progress ADIEVN_CP_VOICE is generated The event value field contains the voice event If the remote
199. lephony functions are performed It contains physical and logical resources on the board A port is represented by a context and a context handle ctahd a software handle that enables the application and its developer to keep track of software activities To access most functionality on a port the application must associate a telephony protocol with the port On AG and CG hardware the telephony protocol is embodied by a trunk control program TCP and must be loaded during board initialization NMS Communications provides TCPs for most standard telephone line interfaces Starting a protocol enables the use of call control functions Almost all functions require a protocol to be loaded For applications that do not use call control functions or choose to manage the line interface manually the NOCC no call control TCP is provided For more information about controlling calls under specific TCPs refer to the NMS CAS for Natural Call Control Developer s Reference Manual NMS Communications 9 Overview of the ADI service ADI Service Developer s Reference Manual Setting up the Natural Access environment Before you can call functions from the ADI library the application must initialize Natural Access and open the ADI service Application setup for Natural Access consists of the following steps 1 Initialize Natural Access for the process 2 Create event queues and contexts 3 Open services on each context To set up a second Na
200. levent break might include cases to handle disconnect event NMS Communications DTMFs etc 191 Function reference ADI Service Developer s Reference Manual adiStartTimer Starts or restarts a timer on the board Supported board types e PacketMedia process Prototype DWORD adiStartTimer CTAHD ctahd unsigned timeout unsigned count Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext timeout Timeout value in milliseconds count Number of events Return values Return value Description SUCCESS CTAERR INVALID CTAHD Context handle is invalid CTAERR SVR COMM Server communication error Events Event Description ADIEVN TIMER DONE After the timer completes expires the ADI service generates a DONE event with the value field set to REASON FINISHED If the board is in error there is an error the value field The value is REASON STOPPED if the timer is halted with adiStopTimer ADIEVN TIMER TICK If count is greater than 1 the ADI service generates a tick event for the first count 1 expirations On the final expiration TIMER DONE is generated Details The ADI service supports one application timer per port This on board timer has 10 ms resolution The timer can be used when the application is controlling the protocol from application space The timer
201. lication are also associated with the context Refer to the Natural Access Developer s Reference Manual for details on the programming models created by the use of contexts and event queues 10 NMS Communications ADI Service Developer s Reference Manual Overview of the ADI service Opening services Open services on a context by calling ctaOpenServices When opening the ADI service specify a context a specific board a timeslot and a mode The parameter structure CTA_MVIP_ADDR contains the following fields board bus stream timeslot and mode For all boards bus and stream can be The board field specifies the board number you want to use For AG and CG boards refer to the system configuration file for the board keyword identifying each board in the system See the NMS OAM System User s Manual for more information For QX boards refer to the qx cfg configuration file for board identification See the QX 2000 Installation and Developer s Manual for more information The timeslot and mode fields are used to calculate which timeslots to allocate to the service The timeslot specifies the base timeslot and the mode dictates how many timeslots are allocated The mode field can be one of the following values Value Description ADI_VOICE_INPUT Receives in band data only The data is received by the DSP on the given timeslot ADI_VOICE_OUTPUT Transmits in band data only The data is transmitted by the DSP on the given time
202. lication buffer large enough to fit the whole prompt file You can prematurely terminate the prompt by entering a touchtone At the record beep prompt begin speaking ADIEVN RECORD BUFFER FULL displays on your screen for each buffer size time period You can prematurely terminate the recording by entering a touchtone or by ceasing to speak The recording you just made is played back Again the message ADIEVN PLAY BUFFER REQ displays on your screen Repeat steps 2 and 3 The process repeats using callback mode Since Natural Access automatically invokes the callback routine the displayed event messages are replaced with the corresponding callback events Note This demonstration program enables you to experiment with buffer sizes The encoding format for the files is ADI ENCODE NMS 24 which has a 62 byte frame size Buffer sizes you specify with the z option must therefore be multiples of 62 NMS Communications 235 Demonstration programs ADI Service Developer s Reference Manual Multi threaded application threads threads demonstrates handling multiple ports using one thread per port This demonstration application is a multi threaded answering machine using ctademo Each thread opens a port and repeatedly waits for calls on the port Each time a call is received it answers plays the answering message and hangs up Note adiStartPlaying and consequently this demonstration program is not supported when the applicat
203. lling adiStartDial expect a DONE event If the function is dialing DTMFs the outbound voice path must be available not in use by another function If the function is pulse dialing the outbound signaling path must be available See also adiStartMFDetector adiStartProtocol adiStopDial 160 NMS Communications ADI Service Developer s Reference Manual Function reference adiStartDTMF Starts generating a string of DTMFs or MFs Supported board types e QX e AG e CG e PacketMedia process Prototype DWORD adiStartDTMF CTAHD ctahd char digits ADI DTMF PARMS parms E Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext l digits Pointer to a string of DTMF digits including O though 9 A through F asterisk number sign and comma or period for pauses All other characters are ignored _ parms Pointer to DTMF parameters according to the following structure NULL value uses the default values typedef struct DWORD size size of this structure ard INT32 ampll level of first tone dBm m INT32 ampl2 level of second tone dBm n DWORD ontime 2 DWORD offtime off duration of DTMF tone ms DWORD shortpause duration of ms DWORD longpause duration of ms Sf ADI_DTMF_PARMS In some instances the dtmfofftime can increase by 20 ms Refer to ADI_DTMF_PAR
204. llocated by the ADI service size Size bytes of valid data in the buffer If the application s access returns a value other than SUCCESS the ADI service terminates the record operation and generates ADIEVN_RECORD_DONE with a value field of ADIERR_PLAYREC_ACCESS Note You cannot initiate a record operation while playing voice or generating tones unless you disable the record beep by setting either ADI_RECORD beeptime or ADI_RECORD beepfreg to 0 zero You cannot start a record operation if the energy detector is active unless both ADI_RECORD novoicetime and ADI_RECORD silencetime are 0 zero For more information refer to Recording on page 20 Refer to ADI RECORD PARMS on page 262 for field descriptions See also adiCommandRecord adiGetRecordStatus adiRecordAsync adiRecordToMemory adiSetNativeInfo adiStopRecording 184 NMS Communications ADI Service Developer s Reference Manual Function reference Example The following code fragment records into the file test vce using adiStartRecording NMS Communications 185 Function reference adiStartSendingFSK ADI Service Developer s Reference Manual Sends frequency shift key FSK data Supported board types Prototype DWORD adiStartSendingFSK CTAHD ctahd void buffer unsigned bufsize ADI_FSKSEND_PARMS parms Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext buffer Buffer to send
205. lues on page 266 cleardown bandw1 DWORD 40 Hz Not applicable cleardown bandw2 DWORD 40 Hz Not applicable cleardown freqi DWORD 350 Hz Not applicable cleardown freq2 DWORD 440 Hz Not applicable cleardown qualampl INT32 28 dBm Not applicable cleardown qualtime DWORD 1000 ms Not applicable cleardown reflevel DWORD 0 000 IDU Not applicable cleardown reserved DWORD 0 internal Not applicable cleardown tonecount DWORD 0 integer Not applicable cleardown maxofftime DWORD 0 ms Not applicable cleardown maxontime DWORD 0 ms Not applicable cleardown minofftime DWORD 0 ms Not applicable cleardown minontime DWORD 0 ms Not applicable dial breaktime DWORD 60 ms Not applicable dial dialtonewait DWORD 5000 ms Not applicable dial dtmfampl1 INT32 6 dBm Not applicable dial dtmfampl2 INT32 4 dBm Not applicable dial dtmfofftime DWORD 80 ms Not applicable dial dtmfontime DWORD 80 ms Not applicable dial flashtime DWORD 500 ms Not applicable dial interpulse DWORD 700 ms Not applicable 264 NMS Communications ADI Service Developer s Reference Manual Parameters Field name Type Default Units Description dial longpause DWORD 5000 ms Not applicable dial maketime DWORD 40 ms Not applicable dial method DWORD 0 mask Not applicable dial reserved DWORD 0 internal Not applicable dial shortpause DWORD 2000 ms Not applicable dial tonebandw1 DWORD 40 Hz Not applicable dial toneba
206. me time NULL return adiSetBoardClock ctahd board ltime NMS Communications 149 Function reference ADI Service Developer s Reference Manual adiSetNativeInfo Enables native play and record mode for an ADI port Supported board types e CG e PacketMedia process Prototype DWORD adiSetNativeInfo CTAHD ctahd DWORD ingresshd DWORD egresshd ADI NATIVE CONTROL control Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext l ingresshd MSPP filter handle that connects the ADI native record channel on the board to the MSP jitter buffer egresshd MSPP endpoint handle that connects the ADI native play channel on the board to the RTP endpoint 150 NMS Communications ADI Service Developer s Reference Manual Argument Description typedef struct DWORD size FS DWORD mode F5 S B DWORD play_encoding f adidef h values type otherwise DWORD rec_encoding 5 pu ADI ENCODING xxx B B pl B DWORD frameformat 5 Sy DWORD include2833 FS Bri WORD payloadID WORD nsPayload Ps B Er 7 WORD vadFlag ee frames ADI NATIVE CONTROL NMS Communications Function reference control Pointer to the ADI NATIVE CONTROL structure as shown Size this structure Enables
207. mmunications 241 Events ADI Service Developer s Reference Manual DONE events A DONE event is a Natural Access event informing the application that an asynchronous function completed processing DONE event codes are in the form ADI_function_DONE where function is the completed function for example PLAY RECORD COLLECTION DONE events have no special physical or processing characteristics they have the same physical structure and are retrieved identically as all other events An asynchronous function can return SUCCESS to the application when invoked and the function can later fail on the board If the board detects an error when running a function the ADI service delivers a DONE event to the application and the event value field contains an error code 242 NMS Communications ADI Service Developer s Reference Manual Events Alphabetical event summary The following table alphabetically lists the ADI service events Event name ADIEVN_BOARD_ERROR ADIEVN_BOARD_EVENT ADIEVN_COLLECTION_DONE ADIEVN_CP_BUSYTONE ADIEVN_CP_CED ADIEVN_CP_DIALTONE ADIEVN_CP_DONE ADIEVN_CP_NOANSWER ADIEVN_CP_RINGTONE ADIEVN_CP_RINGQUIT ADIEVN_CP_REORDERTONE ADIEVN_CP_SIT ADIEVN_CP_VOICE ADIEVN_DIAL_DONE ADIEVN_DIGIT_BEGIN ADIEVN_DIGIT_END ADIEVN_DTMF_DETECT_DONE ADIEVN_ECHOCANCEL_STATUS ADIEVN_ECHOCANCEL_TONE ADIEVN_ENERGY_DETECT_DONE ADIEVN_ENERGY_DETECTED ADIEVN_FSK_RECEIVE_DONE ADIEVN_FSK_SEND_DONE ADIEVN_MF_DETECT_DONE ADIEVN
208. monstration only and is subject to change without notice NMS Communications 231 Demonstration programs ADI Service Developer s Reference Manual Host port to port connection hostp2p hostp2p demonstrates live voice connection between two ports using play and record functions This program uses simultaneous play and record of small buffers to simulate a real time voice connection between two voice calls It uses the asynchronous play and record functions of the ADI service Usage hostp2p options where options are Option Use this option to specify the bn Board number Default 0 Bn Second board number if different s n m First port DSP address Default 0 0 Specify only the timeslot S n m Second port DSP address Default 0 1 Specify only the timeslot p protocol Protocol to run Default LPSO P protocol Second port protocol if different en Encoding type Refer to adidef h Default 10 mu law fn Buffer size ms Default 60 d digits Digits to dial on port 2 if not NOCC E len tim Echo cancellation length adaptime Default 4 100 Running hostp2p This procedure assumes that you are testing on an AG 2000 board with loop start line interfaces connected to phone lines hostp2p requires rvoice m54 and echo m54 for an AG 2000 board Ensure that the board keyword file is set to SwitchConnections Yes or Clocking HBus ClockMode STANDALONE for the board you are usin
209. ms size sizeof MSP VOICE CHANNEL PARMS Create channel mspCreateChannel ctaHd amp chanaddr amp chan params amp msphd CTA EVENT CtaEvent ai 1 WaitForSpecificEvent MSPEVN CREATE CHANNEL DONE amp Event 5000 printf Failed waiting for MSPEVN CREATE CHANNEL DONE return FAILURE NMS Communications 37 Developing applications ADI Service Developer s Reference Manual connect mspp endpoints ret mspConnect 450 ephd msphd rtp ephd if WaitForSpecificEvent MSPEVN_CONNECT_DONE amp Event 5000 printf Failed waiting for MSPEVN CONNECT DONE return FAILURE connect mspp enable channel mspEnableChannel msphd ae WaitForSpecificEvent MSPEVN ENABLE CHANNEL DONE amp Event 5000 printf Failed waiting for MSPEVN ENABLE CHANNEL DONE return FAILURE adiStartProtocol adiStartProtocol ctahd nocc NULL NULL if WaitForSpecificEvent ADIEVN STARTPROTOCOL DONE amp Event 5000 printf Failed to receive ADIEVN STARTPROTOCOL DONE event return FAILURE get cg6xxx board handle ret mspGetFilterHandle msphd MSP_FILTER_JITTER amp cg6xxx_board_filter_handle ADI_NATIVE_CONTROL parms 0 Native parameters af parms frameFormat 0 parms include2833 0 parms vadFlag OF parms nsPayload 0 parms mode ADI NATIVE parms rec encoding ADI ENCODE EDTX MU LAW parms payloadID 0 ret adiSetNativeInfo ctahd cg6xxx_board
210. n Asynchronous adiStartSendingFSK Asynchronous Initiates sending frequency shift key data adiStopSendingFSK Asynchronous Stops the sending function adiStartReceivingFSK Asynchronous Receives frequency shift key data adiStopReceivingFSK Asynchronous Stops the receive function FSK modems are the low level building blocks for analog display services interface ADSI The ADI service does not provide an ADSI programming interface but you can use the FSK functions to implement ADSI applications 76 NMS Communications ADI Service Developer s Reference Manual Function summary Low level call control functions The following functions provide low level access to the line interface This access is typically needed only when using the NOCC no call control protocol These functions are used when the application is directly controlling the line interface or when a CAS protocol is not needed Use these functions carefully especially if you are running a telephony protocol The following ADI functions provide low level call control Function Synchronous Description Asynchronous adiAssertSignal Synchronous Asserts an out of band signaling pattern adiAssertSignal returns before the pattern is actually asserted adiStartPulse Asynchronous Pulses an out of band signaling pattern for a duration adiStartSignalDetector Asynchronous Starts detection of out of band signaling bits adiStopSignalDetector Asynchronous Stops detection
211. n Loss ay WORD ERLE Echo Return Loss Enhancement if WORD sndLevel Level of the sent signal my WORD rcvLevel Level of the received signal WORD refPoint Reflection point location ml ADI ECHOCANCEL STATUS INFO The ADI ECHOCANCEL STATUS INFO structure contains the following fields Field status ERL ERLE sndLevel rcvLevel refPoint Description Echo canceller status flags See the status flag descriptions in the following table Echo return loss ratio ERL is the ratio of rcvLevel to sndLevel Compute the ERL in dBm as follows 10 x log 1 ERL Echo return loss enhancement Compute the ERLE in dBm as follows ERLEgem 10 x log rcvLevel rcvLevel ERLE Power of the sent signal Compute the sndLevel in dBm as follows sndLevelaes 10 x log sndLevel 0x3D29 where 0x3D29 is the 0 dBm reference value Power of the received signal Compute the rcvLevel in dBm as follows rcvLevelgsm 10 x log rcvLevel 0x3D29 where 0x3D29 is the 0 dBm reference value The position of the maximum value in the H register in 8 kHz sample increments If the returned value of refPoint is 120 the reflection point is 15 ms and a minimum tail length of 20 ms is required NMS Communications 125 Function reference ADI Service Developer s Reference Manual The following table describes the status flags Flag Values Status bits 0 0 Normal 1 Send status one time 1 0 Normal 1 S
212. n a call is released Recording The ADI_RECORD_PARMS structure contains the record function parameters Initiating record The ADI service provides three functions to initiate voice record The function used depends upon the data transfer method Use this function When adiRecordToMemory The application submits a single buffer to the ADI service adiStartRecording The ADI service invokes an application specified callback function when a buffer is full The application must store the data before returning Note Applications running in client server mode do not support adiStartRecording adiRecordAsync The ADI service generates a buffer full event when each buffer is full The application asynchronously stores the data and submits empty buffers in response The ADI service returns SUCCESS if the recording function successfully started Terminating record The record function terminates when the ADI service delivers ADIEVN_RECORD_DONE regardless of the transfer method The event value field contains one of the following termination reasons If Then play ends with The call was released by either party CTA_REASON_RELEASED A DTMF digit specified in the abort mask was entered by the remote party 5 DIGIT application aborted recording with adiStopRecording CTA_REASON_STOPPED The remote party never spoke see the no voice illustration CTA_REASON_NO_VOICE The remote party stopped speaking for t
213. ndw2 DWORD 40 Hz Not applicable dial tonefreq1 DWORD 350 Hz Not applicable dial tonefreq2 DWORD 440 Hz Not applicable dial tonequalampl INT32 28 dBm Not applicable dial tonequaltime DWORD 50 ms Not applicable dial tonereflevel DWORD 0xB000 IDU Not applicable dtmfdet columnfour Flag that indicates whether to detect the A B C and D DTMF digits Set this value to 1 to detect these digits or 0 to ignore them dtmfdet offqualampl Minimum signal required to maintain recognition of a DTMF signal once recognition starts Valid AG board CG board and PacketMedia HMP range is 51 through 15 Not used for QX boards Minimum duration of absence of a recognized DTMF signal before an end of digit event is emitted Valid AG board CG board and PacketMedia HMP range is 5 through 32767 Valid QX board range is 0 through 32766 dtmfdet offqualtime dtmfdet offthreshold DWORD 0x92E0 IDU Do not modify Not used for QX 2000 boards dtmfdet onqualampl dBm Minimum signal level recognized as a DTMF signal Valid AG board CG board and PacketMedia HMP range is 51 through 15 Not used for QX boards dtmfdet onqualtime Minimum duration of a recognized DTMF signal before a digit event is emitted Valid AG board CG board and PacketMedia HMP range is 22 through 32767 Valid QX board range is 30 through 32766 dtmfdet onthreshold DWORD OxCABO IDU Do not modify Not used for QX 2000 boards NMS Communica
214. ne detector 4 terminated Precise tone detector 5 terminated Precise tone detector 6 terminated NMS Communications ADI Service Developer s Reference Manual Function reference Details Use adiStopToneDetector to deactivate a precise tone detector When the detector stops the ADI service generates a DONE event with the value field set to CTA_REASON_STOPPED A specific DONE event is defined for each of six precise tone detectors You can restart the tone detector specified by the toneid when you receive the DONE event For more information refer to Detecting tones on page 50 Example int myStopToneDetector CTAHD ctahd stop detector 2 CTA_EVENT event if adiStopToneDetector ctahd 2 SUCCESS return MYFAILURE while 1 myGetEvent amp event see ctaWaitEvent example switch event id case ADIEVN 2 DETECT DONE if event value CTA REASON RELEASED return MYDISCONNECT call has been terminated return MYFAILURE BPI error else return SUCCESS stopped normally break might include cases to handle disconnect DTMFs etc NMS Communications 223 Function reference ADI Service Developer s Reference Manual adiStopTones Stops generating tones Supported board types e PacketMedia process Prototype DWORD adiStopTones CTAHD ctahd Argument Description
215. ne that was detected See Details for information NMS Communications 85 Function reference ADI Service Developer s Reference Manual DSP files The following DSP file must be loaded to the board to enable echo canceller tone detection For these boards Add this DSP file echo_v4 m54 echo_v4 f54 Refer to the board installation and developer s manual for information about MIPS usage Details The echo canceller must be started before adiCommandEchoCanceller will work For information see Controlling echo on page 57 This function sends three commands to the tone detector Command A Use the first command to start or stop the echo canceller tone detector configure all options and initialize all parameters Word Description Valid Typical range values Word 1 Configures the echo canceller tone detector Set bits as N A 0001 follows Bit 0 0 stop 1 start e Bit 1 0 phase reversal requested e Bit 2 0 amplitude modulation detection requested e Bit 3 0 send receive switching required e Bit 4 0 send path always if bit 3 1 1 receive path always if bit 3 1 e Bit 5 0 send all events to host e Bit 6 0 take direct control of echo canceller s NLP e Bit 7 0 take direct control of echo canceller s bypass e Bit 8 0 take direct control of echo canceller s reactivation after silence detection e Bit 9 0 silence detection locks the send receive path when silence detected
216. nothing detected give up case CTA_REASON_RELEASED The call was terminated case CTA_REASON_STOPPED default return MYDISCONNECT NMS Communications 157 Function reference ADI Service Developer s Reference Manual adiStartDial Starts the dialing function for applications that are not using protocol independent call control Supported board types e PacketMedia process Prototype DWORD adiStartDial CTAHD ctahd char digitstr ADI_DIAL_PARMS parms m Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext digitstr Pointer to string of digits to be dialed ADI_MAX_DIGITS parms Pointer to dialing parameters stored in ADI_DIAL_PARMS structure as follows NULL designates default values typedef struct WORD size size of this structure ay DWORD method default dialing method 0 DTMF 1 pulse 2 DWORD breaktime duration of pulse digit break ms DWORD maketime duration of pulse digit make ms ay DWORD interpulse interdigit delay between pulsed digits ms S DWORD flashtime duration of the flash hook ms S DWORD shortpause duration of the comma in dialing string ms DWORD longpause duration of the dot in dialing string ms 5 INT32 dtmfampll first dtmf amplitude dBm INT32 dtmfampl2 second dtmf amplitude dBm DWORD dtmfontime ON duration of DTMFs ms
217. nt to the application for ASR processing host processing resources can be conserved The voice activity detector provides the following features Feature Description Voice activity Detects audio energy and triggers data transmission only when speech is present detection Pre speech When the voice activity detector detects speech the board runtime immediately buffering sends the previously filled buffer to the host reducing the problem of clipped speech Voice event Sends SPEECH_BEGIN and SPEECH_END messages and noise and signal energy to signaling the host application Recorded Pauses and resumes sending recorded data to the runtime while keeping the voice stream control activity detector algorithm active on the DSP The voice activity detector enables host application control of voice activity detection features including e Start with new or default parameters and stop voice activity detection e Update voice activity detection parameters on the fly e Enable and disable voice activity detection signaling e Pause and resume the recorded stream from the board to the host The voice activity detector has a fixed delta threshold that allows it to adapt to the background noise level When the voice level is higher than the background noise level by a specified delta the detector sends a SPEECH_BEGIN event to the application When the voice level falls below the background noise level the detector sends a SPEECH_END event
218. ntil one of the terminating conditions described in Terminating play on page 26 occurs The ADI service sends events and the application submits buffers while in this state as described e The ADI service generates ADIEVN_PLAY_BUFFER_REQ whenever the board starts a new buffer more play data is needed e In response to the ADI service the application invokes adiSubmitPlayBuffer to continue playing The application can terminate the play function by setting the ADI_LASTBUFFER_SUBMITTED flag The ADI service generates ADIEVN_PLAY_DONE when the data already submitted has been played The application cannot invoke adiSubmitPlayBuffer unless the ADI service has given it ADIEVN_PLAY_BUFFER_REQ The ADI service returns ADIERR_TOO_MANY_BUFFERS when adiSubmitPlayBuffer is invoked without first receiving a buffer request event Stopping The application can abort play by invoking adiStopPlaying The ADI service does not accept more play commands from the application while in the stopping state Any play functions invoked by the application prompt the ADI service to return CTAERR_INVALID_SEQUENCE When ADIEVN_PLAY_DONE is delivered to the application the play state returns to idle 28 NMS Communications ADI Service Developer s Reference Manual Developing applications Controlling gain during play Adjust the play volume at play initiation by changing the default value of the play gain parameter stored in ADI_PLAY_PARMS on page 261 You can also
219. nts Event Description ADIEVN_COLLECTION_DONE Generated when collection completes The event buffer field points to the same buffer passed to adiCollectDigits The size field contains the number of characters collected plus one to account for the null terminator The value field contains one of the following termination reasons Or an error code CTA_REASON_DIGIT Terminating digit received CTA_REASON_FINISHED Expected number of digits collected CTA_REASON_RELEASED Call terminated CTA_REASON_STOPPED Terminated by adiStopCollection CTA_REASON_TIMEOUT Timed out waiting for a digit Details Use adiCollectDigits to start the asynchronous collection of DTMF digits Any digits received before collection is started are included unless they were discarded by calling adiFlushDigitQueue Any digit not included in the validDTMFs mask is discarded Collection terminates and ADIEVN_COLLECTION_DONE is generated when one of the following occurs e The maximum number of digits maxdigits is collected e The initial firsttimeout or interdigit intertimeout timeout expires terminating terminators digit is received e adiStopCollection is issued e The call is released Note If a digit is in both the terminators mask and in the validDTMFs mask it is included as the last digit in the collected string If the string contains maxdigits digits the termination reason is REASON FINISHED NMS Communications 83
220. o 16 24 or 32 kbit s or it is stored as uncompressed mu law or A law 64 kbit s This file is required to play or record with encoding values of ADI ENCODE 5 16 ADI ENCODE NMS 24 ADI ENCODE NMS 32 or ADI ENCODE NMS 64 Substitute these files for voice dsp to apply speed up to NMS Communications ADPCM encoded speech Contains play and record functions for PCM speech in formats commonly used in WAVE files including 8 and 16 bit 11 kilo samples per second sampling 271 Index A ADI_BOARD_INFO 97 ADI_CALLCTL_PARMS 174 ADI_CALLPROG_PARMS 154 254 ADI_CLEARDOWN_PARMS 174 ADI_COLLECT_PARMS 82 256 ADI_CONTEXT_INFO 106 ADI_DIAL_PARMS 158 257 ADI_DTMF_PARMS 161 259 ADI_DTMFDETECT_PARMS 163 174 260 ADI_ECHOCANCEL_PARMS 123 174 ADI_ECHOCANCEL_STATUS_INFO 123 ADI_EEPROM_DATA 111 ADI_ENERGY_PARMS 165 260 ADI_FSKRECEIVE_PARMS 179 261 ADI_FSKSEND_PARMS 186 261 ADI_PLAY_PARMS 261 adiPlayAsync 132 adiPlayFromMemory 136 adiStartPlaying 170 ADI_PLAY_STATUS 115 ADI_RECORD_PARMS 262 adiRecordAsync 141 adiRecordToMemory 145 adiStartRecording 182 ADI_RECORD_STATUS 117 ADI_START_PARMS 174 264 ADI_TIMESLOT 100 ADI_TIMESLOT32 103 ADI_TONE_PARMS 198 267 ADI_TONEDETECT_PARMS 194 268 adiapi lib 12 adiAssertSignal 80 NMS Communications adiCollectDigits 82 adiCommandEchoCanceller 85 adiCommandRecord 91 adidef h 82 85 113 189 ADIERR_XXX_XXX 237 239 ADIEVN_CP_TDD 48 154 ADIEVN_XXX_XXX 243 245 a
221. o improve its performance The better the estimation of the echo path the smaller the energy of the error signal The attenuation of the signal at the output of the subtractor in relation to the Sin signal is denoted as echo returned loss enhancement ERLE The adaptation logic updates the FIR filter coefficients using the error signal A modified least mean square LMS algorithm is used to modify the coefficients in an iterative fashion The application can freeze or stop this adaptation or reset the value of the coefficients to restart convergence The double talk detector detects when both callers speak at the same time IP telephony application or when DTMF is input to the system at the same time as audio playback IVR In the presence of double talk this detector sends a command to the adaptation logic to stop or slow the adaptation of the coefficients Detecting the double talk situation is critical for correct operation of the echo canceller If adaptation continues during double talk the adaptive filter modifies its coefficients based on the information contained in the Sin signal In this case this is the sum of the echo of Rout signal and the signal produced by the near end talker The adaptation would therefore be erroneous The non linear processor is a device with a defined suppression threshold level in which signals having a level detected e Below the threshold are suppressed e Above the threshold are passed although th
222. o the time connected to the right path For example if silence duration is set to 400 ms 800 ms might pass before silence is detected See also adiModifyEchoCanceller NMS Communications 89 Function reference ADI Service Developer s Reference Manual Example 90 NMS Communications ADI Service Developer s Reference Manual Function reference adiCommandRecord Sends a data array containing raw commands to an actively running recording function Use adicommandRecord to enable and configure voice activity detection Supported board types e PacketMedia process Prototype DWORD adiCommandRecord CTAHD ctahd WORD data 7 DWORD nwords m Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext data Pointer to an array of 16 bit data containing the commands nwords Number of 16 bit data words Return values Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE ADI service recording function was not started before calling adiCommandRecord E CTAERR INVALID SEQUENCE adiStopRecording has already been invoked NMS Communications 91 Function reference ADI Service Developer s Reference Manual Events Description ADIEVN_RECORD_EVENT Contains information sent by the custom recording function The event value field may contain one of the following reason codes also defined
223. oCanceller For these boards Load this DSP file echo m54 echo_v3 m54 or echo_v4 m54 echo f54 echo_v3 f54 or echo_v4 f54 QX 2000 The standard QX DSP file Refer to DSP file summary on page 269 for DSP file descriptions Refer to the board installation and developer s manual for MIPS usage Use this function to modify echo cancellation parameters The echo canceller must be started for adiModifyEchoCanceller to work For more information see Controlling echo on page 57 Echo canceller operation can be enabled or disabled by setting the proper bits in the mode parameter You can also change the gain applied to the near end input and the predelay applied to the far end input You cannot change the filterlength and adapttime parameters You must always pass a pointer to the ADI ECHOCANCEL PARMS structure in the call to adiModifyEchoCanceller because the parameters for this function do not have default values The echo cancel parameters are in the NCC X ADI_START echocancel structure You must copy the individual fields to the ADI ECHOCANCEL PARMS structure that you pass to adiModifyEchoCanceller For more information about the adiModifyEchoCanceller parameter fields refer to ADI START PARMS on page 264 124 NMS Communications ADI Service Developer s Reference Manual Function reference ADI_ECHOCANCEL_STATUS_INFO structure typedef struct WORD status Echo canceller status flags WORD ERL Echo Retur
224. oard CG board and PacketMedia HMP range is 54 through 3 Valid board range is 90 through First or only frequency of the generated tone Valid range is 200 through 3600 Second frequency of the generated tone or 0 if the tone is a single frequency If not 0 valid range is 200 through 3600 Number of times to repeat the alternating tone and silence period A count of 1 means repeat forever Otherwise the valid range is 1 through 32767 Duration of silence between tones Specify 0 for no off time Valid AG board CG board and PacketMedia HMP range is 0 through 65535 Valid QX board range is 0 through 8000 Duration of the tone Valid AG board CG board and PacketMedia HMP range is 1 through 65535 Valid QX board range is 0 through 8000 267 Parameters ADI Service Developer s Reference Manual ADI_TONEDETECT_PARMS Dependent function adiStartToneDetector Field Type Default Units Description name qualampl INT32 28 dBm Minimum signal level that is detected Valid AG board CG board and PacketMedia HMP range is 40 through 0 Valid QX board range is 48 through 0 qualtime DWORD 500 ms Minimum duration of a detected tone before an event is emitted Also specifies the minimum duration of the absence of detected tone before a tone ended event is emitted The valid range is 0 through 32767 reflevel DWORD 0 000 IDU Do not modify reserved DWORD 0 internal Do not modify
225. oid buffer buffer pointer Bi DWORD value Event status or event specific data y DWORD objHd service client side object handle ml CTA EVENT This structure returned by ctaWaitEvent informs the application which event occurred on which context and includes additional information specific to the event The CTA EVENT structure contains the following fields Field Description id ADI event code defined in the adidef h header file All ADI events are prefixed with ADIEVN for example ADIEVN SOMETHING HAPPENED ctahd Context handle the same as the one returned from ctaCreateContext timestamp Time when the event was created in milliseconds Use ctaGetTimeStamp to interpret the value The resolution for AG board events is 10 milliseconds For CG board and PacketMedia HMP process events the resolution is 1 millisecond userid User supplied value to ctaCreateContext This field is unaltered by the ADI service and facilitates asynchronous programming Its purpose is to correlate a port with an application object or context when events occur size Size bytes of the area pointed to by buffer If the buffer is NULL this field can hold an event specific value buffer Pointer to data returned with the event The field contains an application process address and the event s size field contains the actual size of the buffer value Event specific value objHd Service object handle for the client side NMS Co
226. oke mspCreateEndpoint to create an audio DSO endpoint mspCreateEndpoint returns an endpoint handle amp dsOephd mspCreateEndpoint msphd mspaddrstruct mspparmstruct amp ds0ephd Invoke mspCreateChannel to create a full duplex or voice decoding channel mspCreateChannel msphd chnladdr chnlparms amp chanhd Invoke mspConnect to connect the DSO and RTP endpoints with the voice channel mspConnect dsOephd chanhd rtpephd Invoke mspEnableChannel to enable the record channel to process data mspEnableChannel msphd Invoke swiMakeConnection with the swihd returned by swiOpenSwitch to connect the MSPP DSO output to the ADI audio channel input and vice versa When using swiMakeConnection the application specifies the stream and timeslot used to create the ADI port and the stream and timeslot used to create the DSO endpoint swiMakeConnection swihd adi ds0 dsOephd 2 Invoke mspGetFilterHandle to retrieve the filter identifier fIEID associated with the MSPP record channel mspGetFilterHandle chanhd MSP FILTER JITTER amp fltID Invoke adiSetNativeInfo to set NMS native record parameters Specify both the context handle of the ADI port and the returned by mspGetFilterHandle adiSetNativeInfo ctahd fltID NULL natpr parms Invoke ctaGetParms to return parameter values for the ADI RECORD PARMS structure ctaGetParms ctahd parmid buffer size Invoke adiRecordToMemory to begin recording a message ad
227. one function can drive the output of the telephone line the following functions are mutually exclusive e Tone generation e Voice playback e Voice record when beep is enabled 52 NMS Communications ADI Service Developer s Reference Manual Developing applications Collecting digits The ADI service provides both synchronous and asynchronous digit collection functions Call control must be in the connected state to activate the digit collection functions and the application must leave the DTMF detector enabled DTMF detection parameters are loaded when the protocol is started In general digit collection operates as follows e When caller depresses a digit on the handset the board sends ADIEVN_DIGIT_BEGIN to the application and the digit becomes available e When the caller releases the key the board sends ADIEVN_DIGIT_END to the application e Each event s value field contains an ASCII value indicating the key pressed or released The valid values are through 9 asterisk number sign and A through D This topic presents e Synchronous digit collection e Asynchronous digit collection e Modifying DTMF detection e Terminating DTMF detection e Improving DTMF using echo cancellation Synchronous digit collection The ADI service maintains an internal DTMF digit queue to store digits entered by the remote party If the application is not actively collecting digits using adiCollectDigits DTMFs entered by the r
228. one is detected without waiting for stuttered dial tone to end If set to a non zero value the value represents the total qualification time for dial tone and the following occurs e Only precise dialtone detection is used e If dialtone disappears requalify until dialtonewait expires e If dialtone lasts for totaltime proceed with dialing NMS Communications ADI Service Developer s Reference Manual ADI_DTMF_PARMS Parameters Dependent function adiStartDTMF Field Type Default Units name ampli INT32 6 dBm ampl2 INT32 4 dBm longpause DWORD 5000 ms offtime DWORD 80 ms ontime DWORD 80 ms l shortpause DWORD 2000 ms NMS Communications Description Amplitude of the low frequency component of the DTMF pair Valid AG board CG board and PacketMedia HMP range is 54 through 3 Valid QX board range is 90 through 0 Amplitude of the high frequency component of the DTMF pair Valid AG board CG board and PacketMedia HMP range is 54 through 3 Valid QX board range is 90 through 0 Amount of delay associated with the period character Valid range is 0 through 65535 Duration of the silence time between each DTMF digit Valid AG board CG board and PacketMedia HMP range is 0 through 65534 Valid QX board range is 0 through 2047 Note In some instances the silence time increases by 20 ms Duration of each DTMF digit Valid AG board CG board and PacketMedia HMP range i
229. ong DWORD voicemedium DWORD voicetoneratio DWORD NMS Communications Default 60 80 60 60 7 9000 6000 3000 0x30000 Units ms ms ms ms count dBm ms mask ms ms ms ms IDU Parameters Description Do not modify Do not modify Do not modify Do not modify Number of ring tones that must occur before NO ANSWER is reported Valid range is 1 through 32767 Maximum signal level that is considered to be silence Valid AG board and CG board range is 46 through 34 Valid board range is 45 through 0 Minimum length of a silent period after voice is detected before call progress reports a voice ended event Mask to control which events cause call progress to stop A value can be formed by using the OR operation with any of the following values e 0x0001 ring tone e 0x0002 ring end e 0x0004 voice begin e 0 0008 medium voice duration e 0x0010 long voice duration e 0x0020 extended voice duration 0x0040 voice end Maximum time that can elapse with no stimulus from the network before call progress stops with reason of timeout Valid range is 1 through 65535 If the value is set to zero the timer is disabled Minimum length of time voice must be detected before call progress reports an extended voice event Minimum length of time voice must be detected before call progress reports a long voice event Minimum length of time voice must be de
230. ontext queuehd amp ctahd 3 Invoke ctaOpenServices to open the ADI service on the context When using ctaOpenServices the application must specify the following e Set the svclist mvipaddr mode parameter to ADI VOICE DUPLEX to allocate DSP resources for the channel on the CG board e Set the svclist mvipaddr stream parameter to 0 and the svclist mvipaddr timeslot parameter to a unique and valid entry For more information refer to the Natural Access Developer s Reference Manual ctaOpenServices ctahd svclist nsvcs 4 Invoke adiStartProtocol to start the nocc protocol on the audio channel and enable silence detection on the audio channel adiStartProtocol ctahd nocc NMS Communications 39 Developing applications ADI Service Developer s Reference Manual 5 10 11 12 13 14 15 16 17 18 40 Step Action Invoke swiOpenSwitch to open a switching device for the context swiOpenSwitch returns switch handle swihd swiOpenSwitch ctahd cg6ksw board 0x0 amp swihd Invoke ctaCreateContext to create a Natural Access context for the MSPP channel ctaCreateContext queuehd amp msphd Invoke ctaOpenServices to open the MSPP service on the context ctaOpenServices msphd svclist nsvcs Invoke mspCreateEndpoint to create an audio RTP endpoint mspCreateEndpoint returns an endpoint handle amp rtpephd mspCreateEndpoint msphd mspaddrstruct mspparmstruct amp rtpephd Inv
231. ore information refer to Voice encoding formats on page 13 When recording or playing speech files on CG boards a specific DSP file must be loaded for each encoding type except when using the native play and record feature The native play and record feature combines an ADI port with an MSPP endpoint and plays or records speech data directly to or from an IP endpoint with no transcoding For information about the native play and record feature refer to Performing NMS native play and record on page 31 For more information see Encoding formats and DSP files on page 134 The table lists the DSP files that must be loaded on the AG and CG boards It also lists the valid encoding types that QX boards and PacketMedia HMP processes support Refer to the board installation and developer s manual for MIPS usage Use adiStartRecording to start a recording operation adiStartRecording uses a callback routine access to deliver data The ADI service allocates buffers and initiates recording When a buffer fills with voice data the ADI service invokes access passing it the buffer address and size The application must copy the buffer to a storage medium before returning from access access is invoked from ctaWaitEvent The prototype for the access function is int NMSSTDCALL access void userarg void buffer unsigned size where Argument Description userarg Pointer to value previously passed in adiStartRecording buffer Pointer to memory a
232. ormats on page 13 for a complete list maxmsec Maximum duration for recording milliseconds When voice activity detection is enabled maxmsec is the maximum duration of speech recording excluding silences lt buffer Pointer to buffer to receive recorded data bufsize Number of bytes available at buffer bufsize must be set to an exact multiple of the framesize for the selected encoding parms Pointer to record parameters according to the following structure NULL uses default values typedef struct WORD size size of this structure um DWORD DTMFabort mask that specifies DTMF tones to abort INT32 gain recording gain in dB SLC parms used if silence det DWORD novoicetime length of initial silence to stop recording ms use 0 to deactivate initial silence detection a DWORD silencetime length of silence to stop recording after 24 voice has been detected use 0 to deactivate NT32 silenceampl qualif level for silence dBm 0 DWORD silencedeglitch deglitch while qualifying silence f Lec EOI ce i DWORD beepfreqg beep frequency Hz NT32 beepampl beep amplitude dBm A DWORD beeptime beep time ms O no beep yf f ASO parna aM DWORD AGCenable enable AGC use 1 to activate NT32 AGCtargetampl target AGC level dBm af NT32 AGCsilenceampl silence level dBm WORD AGCattacktime attack time ms 7 DWORD A
233. outine int NMSSTDCALL readAccess void userarg void puffer unsigned size unsigned rsize FILE userarg rsize fread buffer 1 size fp OEE SERO return 1 abit dejen return ADI PLAY LAST BUFFER return SUCCESS int myPlayFile CTAHD ctahd unsigned encoding char filename CTA EVENT event FILE fp note binary open if fp fopen filename rb NULL return MYFAILURE if adiStartPlaying ctahd encoding readAccess fp NULL SUCCESS return MYFAILURE do myGetEvent amp event see ctaWaitEvent example while event id ADIEVN PLAY DONE Nee if event value CTA_REASON_RELEASED return MYDISCONNECT call has been terminated rf oue aus return MYFAILURE API error else return SUCCESS stopped normally NMS Communications 173 Function reference ADI Service Developer s Reference Manual adiStartProtocol Starts the NOCC protocol on a specified context Supported board types e PacketMedia process Prototype DWORD adiStartProtocol CTAHD ctahd char protoname WORD protoparms ADI_START_PARMS parms Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext protoname Name of the protocol trunk control program TCP The valid value is NOCC protoparms Valid value is NULL
234. p a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Description ADIEVN_COLLECTION_DONE After digit collection terminates the ADI service generates a DONE event with the value field set to CTA_REASON_STOPPED Details Use adiStopCollection to stop digit collection started with adiCollectDigits When digit collection stops ADIEVN COLLECTION DONE is generated Any digits already collected are included in the event s buffer See also adiFlushDigitQueue adiGetDigit NMS Communications 203 Function reference ADI Service Developer s Reference Manual adiStopDial Stops the dial operation Supported board types e PacketMedia process Prototype DWORD adiStopDial CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values ee Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_SEQUENCE Attempt made to stop a function that is already being stopped CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Description ADIEVN_DIAL_DONE
235. parms EP DSO media MSP VOICE mspCreateEndpoint ipHd amp dsOQaddr amp dsOparms 68450 ephd alae ACU WaitForSpecificEvent MSPEVN_CREATE_ENDPOINT_DONE amp Event 5000 printf Failed waiting for MSPEVN CREATE ENDPOINT DONE DS0 return FAILURE create mspp Channel MSP CHANNEL ADDR chanaddr 0 MSP CHANNEL PARAMETER chan_params 0 chanaddr nBoard Board chanaddr channelType G711FullDuplex chanaddr FilterAttribs MSP_FCN_ATTRIB_RFC2833 chan_params size sizeof MSP CHANNEL PARAMETER chan params channelType G711FullDuplex chan params ChannelParms VoiceParms size sizeof MSP VOICE CHANNEL PARMS Create channel mspCreateChannel ipHd amp chanaddr amp chan params amp msphd CTA EVENT CtaEvent WaitForSpecificEvent MSPEVN_CREATE_CHANNEL_DONE amp Event 5000 printf Failed waiting for MSPEVN CREATE CHANNEL DONE return FAILURE connect mspp endpoints ret 450 ephd msphd rtp if WaitForSpecificEvent MSPEVN_CONNECT_DONE amp Event 5000 printf Failed waiting for MSPEVN CONNECT DONE return FAILURE connect mspp enable channel mspEnableChannel msphd alae el WaitForSpecificEvent MSPEVN ENABLE CHANNEL DONE amp Event 5000 printf Failed waiting for MSPEVN ENABLE CHANNEL DONE return FAILURE connect Fusion and ADI timeslots to allow Silence and DTMF d
236. physical buffer size for the board on the specified context for the given encoding format The board s physical buffer size varies depending upon the board type and configured software The size returned here is rounded to a multiple of the frame size For information specific to QX boards refer to the QX 2000 Installation and Developer s Manual You can pass NULL for any of the function arguments that are pointers to returned values See also adiPlayAsync adiPlayFromMemory adiRecordAsync adiRecordToMemory adiStartPlaying adiStartRecording Example void myShowEncodingInfo CTAHD ctahd unsigned encoding unsigned framesize datarate maxbufsize if adiGetEncodingInfo ctahd encoding amp framesize amp datarate amp maxbufsize SUCCESS printf Frame size d bytes n framesize prine wate ca bytes secin datarate printf Max buf size d bytes n maxbufsize 114 NMS Communications ADI Service Developer s Reference Manual adiGetPlayStatus Function reference Retrieves status for the active or most recently executed play operation Supported board types e PacketMedia process Prototype DWORD adiGetPlayStatus CTAHD ctahd ADI_PLAY_STATUS info unsigned size Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext __ info Pointer to the ADI_PLAY_STATUS structure as shown t
237. pically uses DTMF keys to make option selections Since the user calling into the IVR system does not always wait for the whole message to be played an echo canceller is needed to cancel the local and near end echo of the prompt played by the application Canceling the echo enables the local DTMF detector to recognize a received tone during the time the message is played The echo canceller improves the signal to noise ratio as seen by the DTMF detector on the NMS Communications board The useful signal is the received DTMF signal and the noise is the echo of the message prompt played by the board NMS Communications 57 Developing applications ADI Service Developer s Reference Manual Similar to the example of DTMF cut through the echo canceller also helps in improving cleardown tone detection The following illustration shows echo cancellation for DTMF cut through ec x N Echo path DTMF a Echo canceller a Host based ASR example This application is similar to the DTMF cut through example with the automatic speech recognition ASR system replacing or augmenting the DTMF detector for control of the IVR session ASR algorithms require a high performance echo canceller A prompt is played out on the board The user commands the application by saying a keyword for example a number or a name to make a selection The person s response is processed by the software th
238. ption 5 5 conditions or an error code ADI_REASON_DROP_IN_DATA Stopped due to drop in data ADI_REASON_BAD_STOP_BIT CTA_REASON_FINISHED Data was received successfully CTA_REASON_RELEASED Call terminated CTA_REASON_STOPPED Stopped by application request Details The following DSP file must be loaded to the board before running adiStartReceivingFSK Load this DSP file Bellcore 1200 2200 Hz AG adsir m54 CG adsir f54 QX The standard QX DSP file For these boards V 23 1300 2100 Hz adsir_j m54 adsir_j f54 The standard DSP file ADIEVN_FSK_RECEIVE_DONE Generated by the ADI service when the receive function terminates The event value field contains one of the following termination Stopped due to data framing error The stop bit at the end of data was space not mark See DSP file summary on page 269 for DSP file descriptions Refer to the board installation and developer s manual for a table of MIPS usage for all functions Use this function to receive frequency shift key FSK data The function can be stopped using adiStopReceivingFSK When the function completes ADIEVN_FSK_RECEIVE_DONE is generated If the event value field contains CTA_REASON_FINISHED or CTA_REASON_STOPPED the size field of the event structure contains the number of bytes received The received buffer is in the buffer field If erro
239. r Supplies an empty buffer to an asynchronous record operation that was initiated using adiRecordAsync Supported board types CG e PacketMedia process Prototype DWORD adiSubmitRecordBuffer CTAHD ctahd void buffer unsigned size Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext buffer Pointer into process memory where recorded voice data will be written size Size of the buffer bytes Return values Return value Description SUCCESS ADIERR TOO MANY BUFFERS More than two buffers were submitted A maximum of two buffers can be submitted to a record operation at any given time CTAERR BAD ARGUMENT buffer is NULL CTAERR BAD SIZE size is zero c CTAERR_FUNCTION_NOT_ACTIVE Either not recording or the recording operation was not initiated by calling adiRecordAsync CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_SEQUENCE adiStopRecording was already invoked CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error 228 NMS Communications ADI Service Developer s Reference Manual Function reference Events Event Description ADIEVN_RECORD_BUFFER_FULL Generated by the ADI service when a buffer is filled with recorded voice data The event contains the following fields buffer Pointer to a previously submitted user buffer size Number
240. r of the digit O through 9 A through D asterisk or number sign in the event value field The DTMF detector must be enabled for the digit collection functions for example adiCollectDigits or adiGetDigit 164 NMS Communications ADI Service Developer s Reference Manual Function reference adiStartEnergyDetector Starts the energy detector Note Do not use the energy detector if you are using voice activity detection Supported board types e PacketMedia process Prototype DWORD adiStartEnergyDetector CTAHD ctahd unsigned energyqual unsigned silencequal ADI_ENERGY_PARMS parms Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext energyqual Qualification time for energy in milliseconds silencequal Qualification time for silence in milliseconds parms Pointer to energy detector parameters according to the following structure NULL designates default values typedef struct parameters for energy detection DWORD size size of this structure E INT32 thresholdampl silence level dBm e DWORD deglitch ms deglitch during transitions DWORD autostop on detection l autostop 0 don t ADI ENERGY PARMS Refer to ADI ENERGY PARMS on page 260 for field descriptions Return values Return value Description SUCCESS CTAERR INVALID CTAHD Context handle is invalid CTAERR RESOURCE CONFLICT Sil
241. ram NMS Communications 229 6 Demonstration programs Summary of the demonstration programs Each demonstration program is shipped as an executable program with its source files and make files Note The and outcta programs demonstrate placing inbound and outbound calls Refer to the Natural Access Developer s Reference Manual for information about these demonstration programs The following demonstration programs are provided with Natural Access and the ADI service Program Demonstrates hostp2p A live voice connection between two ports using play and record functions playrec Playing and recording using asynchronous and callback methods threads A simple multi threaded answering machine Before you start the demonstration programs ensure that e Natural Access is properly installed e The board is executing e Switching is correctly configured Refer to the board installation and developer s manual for details on installing the board ctademo c and ctademo h All of the demonstration programs use a common set of high level functions contained in ctademo c and ctademo h This demonstration code provides functions for initializing Natural Access opening and closing ports waiting for calls placing calls answering calls performing record and playback operations and collecting digits Use these functions as base code for developing your applications with Natural Access This library of functions is for de
242. rds support the following encoding formats NMS Communications ADPCM 16 24 32 kbit s and PCM framed 64 kbit s G 726 compliant ADPCM G 723 1 5 3 kbit s and 6 3 kbit s CG boards only G 729A 8 kbit s CG boards only OKI ADPCM 24 and 32 kbit s A law and mu law PCM 8 bit and 16 bit linear PCM at 11 kilo samples per second 16 bit linear PCM at 8 kilo samples per second IMA ADPCM 24 and 32 kbit s Microsoft GSM full rate QX boards support the following encoding formats NMS Communications ADPCM 16 24 32 kbit s and PCM framed 64 kbit s G 726 16 24 32 and 40 kbit s OKI ADPCM 24 and 32 kbit s A law and mu law PCM 8 bit and 16 bit linear PCM at 11 kilo samples per second 16 bit linear PCM at 8 kilo samples per second IMA ADPCM 24 and 32 kbit s VOX ADPCM 32 kbit s The PacketMedia HMP process supports the following encoding formats NMS Communications ADPCM 16 24 32 kbit s and PCM framed 64 kbit s G 726 compliant ADPCM 32 kbit s OKI ADPCM 32 kbit s IMA ADPCM 32 kbit s A law and mu law PCM 16 bit linear PCM at 8 kilo samples per second The encodings refer to the data going to and from the host typically stored voice file With the exception of ADI ENCODE NMS 64 host encoding is independent of line encoding which is always either mu law or A law depending on how the board is configured when it is initialized 14 NMS Communications ADI Service Developer s Reference Manual The following
243. record feature enables applications to use the ADI service to play and record voice data directly to and from RTP endpoints associated with MSPP service connections For information about the native play and record feature refer to Performing NMS native play and record on page 31 To enable the native play and record feature in the ADI_NATIVE_CONTROL structure set the mode to ADI_NATIVE Also set the encoding type so that it matches the encoding type specified in the associated ADI play or record function calls The specified encoding type must be one of the ADI ENCODE EDTX formats For information about encoding formats refer to Recording and playing on page 13 Subsequent play calls specifying an encoding type with the same base codec type use the native path to play directly to the MSPP filter The egress handle in this function specifies the MSPP filter For example if the ADI ENCODE EDTX G723 is specified in the call subsequent play or record calls specifying ADI ENCODE G723 6 ADI ENCODE G723 5 ADI ENCODE EDTX G723 ADI ENCODE EDTX G723 6 or ADI ENCODE EDTX 6723 5 use the native play path Subsequent record calls specifying an ADI ENCODE EDTX encoding type with the same base codec type use the native path to record from the MSPP filters The ingress handle in this function specifies the MSPP filters For example if the ADI ENCODE EDTX G723 is specified in the call subsequent play or record calls specifying ADI ENCODE
244. recording or playing speech files on AG boards a specific DSP file must be loaded for each encoding type For QX boards the standard DSP file supports the valid encoding types For more information refer to Voice encoding formats on page 13 When recording or playing speech files on CG boards a specific DSP file must be loaded for each encoding type except when using the native play and record feature The native play and record feature combines an ADI port with an MSPP endpoint and plays or records speech data directly to or from an IP endpoint with no transcoding For information on the native play and record feature refer to Performing NMS native play and record on page 31 The following table lists the DSP files that must be loaded on the AG and CG boards It also lists the valid encoding types that QX boards and PacketMedia HMP processes support Encoding type AG DSP file CG DSP file Qx PacketMedia HMP support support ADI_ENCODE_ALAW rvoice m54 or rvoice f54 or Y Y rvoice_vad m54 rvoice_vad f54 ADI_ENCODE_G723_5 0723 154 ADI_ENCODE_G723_6 0723 154 ADI_ENCODE_G726 g726 m54 g726 f54 Y Y ADI ENCODE 6726 16 y N ADI ENCODE 6726 24 y N ADI ENCODE 6726 32 y N ADI ENCODE 6726 40 y N ADI ENCODE G729A g729 f54 N N ADI ENCODE GSM gsm ms mb54 gsm ms f54 N N ADI ENCODE IMA 24 ima m54 ima f54 Y N ADI ENCODE IMA 32 ima m54 ima f54 Y Y ADI ENCODE 5 16 voice m54 voice f54 Y Y ADI ENCODE 5 24 voice m54 voice f54 Y
245. requires one or more of the following DSP files to be loaded depending on the digitstr and related parameters CG boards AG boards Use tone f54 tone m54 Generating DTMF and MF tones None signal m54 Generating pulse digits AG 2000 AG 2000C and AG 2000 BRI only ptf f54 ptf m54 Precise dial tone detection For QX boards this function is supported in the standard DSP file Refer to the QX 2000 Installation and Developer s Manual for a table of MIPS usage for all functions Use this function to start dialing for NOCC users adiStartDial is similar to adiStartDTMF but also allows access to pulse dialing flashing and precise dial tone detection Note The DTMF detector is disabled while adiStartDial is active NMS Communications 159 Function reference ADI Service Developer s Reference Manual digitstr can contain the following embedded escape characters that control the dialing sequence Character Description semicolon Wait for precise dial tone period Insert long pause in dialing j comma Insert short pause in dialing Flash hook P Switch to pulse dialing T Switch to DTMF dialing M Switch to MF dialing The following table lists the mapping to the United States MF digits for MF dialing United States MF name Specific digit address MF ST3P MF KP2 MF ST2P NOCC users can start a call progress analysis operation adiStartCallProgress after receiving the DONE event After ca
246. retrieved with adiGetEncodingInfo The ADI service employs a double buffering scheme when recording and playing voice files When the board finishes processing a buffer the application must already have allocated and submitted the subsequent buffer to the ADI service NMS Communications 17 Developing applications ADI Service Developer s Reference Manual On heavily loaded systems the throughput requirements between the host and the board can cause gaps in the voice record or playback This is called an underrun condition Failure to maintain pace with the board can also cause underruns in the voice record or playback Greater file compression may be necessary to eliminate the problem The ADI service counts the number of underruns that occur but not the duration Call adiGetRecordStatus and adiGetPlayStatus to retrieve the underrun count Note Do not submit small buffers buffers that hold less than one second of data Small buffers can also cause underruns Derive the data throughput for a given encoding method from the adiGetEncodingInfo return values Data transfer methods The ADI service provides three methods by which the application can transfer speech data to and from the board Method Description Single memory The application submits a single data buffer to the ADI service transaction Asynchronous transfer The application serially submits multiple buffers by exchanging commands and events with the ADI service
247. returned by ctaCreateContext or ctaAttachContext initial Mask indicating the expected incoming line state refer to mask for possible values mask Mask indicating the bits to monitor For example by setting this mask to ADI_A_BIT all transitions of the A bit are reported and transitions of the other bits are ignored The following constants are in adidef h and can be combined using the OR operation to monitor any group of bits ADI_A_BIT ADI_B_BIT ADI_C_BIT ADI_D_BIT timeon Deglitching debounce time in milliseconds for the ON state of the masked bits The bit transition to HIGH is not reported unless it exceeds timeon timeoff Deglitching debounce time in milliseconds for the OFF state of the masked bits The bit transition to LOW is not reported unless it exceeds timeoff Return values Return value Description SUCCESS ADIERR_INVALID_CALL_STATE Function not valid in the current call state CTAERR_FUNCTION_ACTIVE Function already active CTAERR_FUNCTION_NOT_AVAIL Necessary dsp file was not downloaded to the board CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state CTAERR_SVR_COMM Server communication error NMS Communications 189 Function reference ADI Service Developer s Reference Manual Events Event Description ADIEVN_SIGNALBIT_CHANGED After the detector is started if a bit transition is detected the ADI ser
248. rms Pointer to an array of tones defined by the following structure NULL designates default values typedef struct DWORD size size of this structure i4 DWORD freql E TIERS Wiese uence ami INT32 ampll level of first tone dBm DWORD freq2 second frequency Hz INT32 ampl2 level of second tone dBm 5 DWORD ontime on duration of DTMF tone ms 5 DWORD offtime off duration of DTMF tone ms Sy INT32 iterations times to repeat above 1 forever ADI TONE PARMS Refer to ADI TONE PARMS on page 267 for field descriptions Return values Return value Description SUCCESS ADIERR INVALID CALL STATE Function not available in the current call state CTAERR FUNCTION ACTIVE Function already active CTAERR INVALID CTAHD Context handle is invalid CTAERR INVALID STATE Function not available in the current port state CTAERR OUTPUT ACTIVE Function failed because there is another active output function CTAERR SVR COMM Server communication error 198 NMS Communications ADI Service Developer s Reference Manual Function reference Events Event Description ADIEVN_TONES_DONE The value field contains any of the following reasons CTAERR_xxx or ADIERR_xxx Tone generation failed CTA_REASON_FINISHED Tones generated CTA_REASON_STOPPED Tone generation stopped by adiStopTones Details The following DSP file must be loaded to the board before running adiStart
249. rre bra t Ea ex a E e YR AGE VAR E E E 50 Stopping tone 1 66 REDE REESE nnn 51 Generating LOM GS MT 52 Playing TONGS ew re ca rd ae 52 Terminating tone generation een 52 SVSESITI EGSECICEIOTIS tae Ea M M IEEE 52 Collecting digits retten rye m EY XR EY 53 Synchronous digit collection memes 53 Asynchronous digit 2 55 Modifying DTMF 0500 56 Terminating DTMF 10 56 Improving using echo 112 56 Controlling CCH tad 57 Echo cancellation EEE EEE EE EEE EEE EEE EE EEE 57 Echo canceller 5 2 1 1 eese sese mene 59 Specifying echo canceller parameters 4 nnns 61 NMS Communications 3 Table of Contents ADI Service Developer s Reference Manual Configuring boards for echo cancellation 61 Recommendations for controlling 1 64
250. rs occur the receive operation is terminated and the event value field contains either ADI_REASON_DROP_IN_DATA or ADI_REASON_BAD_STOP_BIT For more information refer to Sending and receiving FSK data on page 69 180 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 181 Function reference adiStartRecording ADI Service Developer s Reference Manual Starts a recording operation using a callback routine to deliver data This function is not supported when Natural Access is running in client server mode Supported board types e PacketMedia process Prototype DWORD adiStartRecording CTAHD ctahd unsigned encoding unsigned maxtime ADIRECORD_ACCESS access void userarg ADI RECORD PARMS parms Argument ctahd encoding maxtime access _ userarg parms 182 Description Context handle returned by ctaCreateContext or ctaAttachContext Encoding type See Voice encoding formats on page 13 for a complete list Maximum recording time in milliseconds Use zero for no time limit When voice activity detection is enabled maxtime is the maximum duration of speech recording excluding silences Pointer to a function to receive recorded data See the prototype in the Details section An arbitrary pointer the value of which is passed to the callback function access on every invoc
251. rtEnergyDetector After this function is called energy and silence transitions are not reported You can restart the energy detector after you receive the DONE event For more information refer to Detecting energy on page 66 208 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 209 Function reference ADI Service Developer s Reference Manual adiStopMFDetector Stops the MF detector Supported board types Prototype DWORD adiStopMFDetector CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values S Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_SEQUENCE Attempt was made to stop a function that is already being stopped CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Description ADIEVN_MF_DETECT_DONE After the detector stops the ADI service generates a DONE event with the value field set to REASON STOPPED Details Use adiStopMFDetector to disable detection of MFs After this function is called MF events are not reported When the DONE event is received restart the MF detector with adiStartMFDetector 21
252. rted board types e PacketMedia process Prototype DWORD adiStopProtocol CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Description ADIEVN_STOPPROTOCOL_DONE When the protocol stops the ADI service generates a DONE event with the value field set to CTA_REASON_FINISHED Details Use adiStopProtocol to stop a protocol previously started with adiStartProtocol You can stop the running protocol from any state If the protocol is in the middle of a call the call is aborted abnormally the outgoing line signaling is set to ADI_CC_STATE_IDLE and the incoming signaling is ignored All functions executing on the context that require being in the connected state are automatically terminated with CTA_REASON_RELEASED When the DONE event is returned you can start a new protocol NMS Communications 213 Function reference ADI Service Developer s Reference Manual Example 214 NMS Communications ADI Service Developer s Reference Manual Function reference adiStopReceivingFSK Stops receiving frequency shift
253. rvice Developer s Reference Manual Developing applications DSP files When recording or playing speech files on AG boards a specific DSP file must be loaded for each encoding type When recording or playing speech files on CG boards a specific DSP file must be loaded for each encoding type except when using the native play and record feature The native play and record feature combines an ADI port with an MSPP endpoint and plays or records speech data directly to or from an IP endpoint with no transcoding Native play and record supports e Playing media files recorded from streams that contain SID frames silence RFC 2833 frames and lost frame markers e Silence and DTMF detection and reporting while recording RTP streams For information on the native play and record feature refer to Performing NMS native play and record on page 31 The previous table lists the ADI_ENCODE_EDTX encoding formats to use for native recording For native playing use either the ADI ENCODE EDTX or ADI_ENCODE encoding formats adiSetNativeInfo sets play and record parameters For QX boards the standard DSP file supports the valid encoding types For more information see Encoding formats and DSP files on page 134 The table lists the DSP files that must be loaded on the AG and CG boards It also lists the valid encoding types that QX boards and PacketMedia HMP processes support Buffer sizes Except for buffers that contain speech data recorded in one
254. ry adiSetNativeInfo adiStartRecording adiStopRecording Example Refer to the playrec demonstration program 144 NMS Communications ADI Service Developer s Reference Manual adiRecordToMemory Function reference Initiates recording of an RTP stream into a single memory resident buffer Supported board types e PacketMedia HMP process Prototype DWORD adiRecordToMemory CTAHD ctahd unsigned encoding void buffer unsigned bufsize ADI RECORD PARMS parms m Argument Y ctahd cc encoding buffer L bufsize parms Description Context handle returned by ctaCreateContext or ctaAttachContext Encoding type See Voice encoding formats on page 13 for a complete list Pointer into process memory to receive encoded data Number of bytes pointed by buffer bufsize can be arbitrarily large and is truncated to a multiple of the framesize for the selected encoding If recording a channel using the native record feature and silence compression is enabled refer to the expandsilence parameter in ADI NATIVE PARMS this buffer size does not imply a specific time limit If the application requires a specific time limit use adiStartRecording or adiRecordAsync to set the maximum record time parameter Pointer to record parameters according to the following structure NULL designates default values typedef struct DWO DWO RD RD INT32 DWO DWO RD
255. ry of 74 managing call progress 43 detecting voice activity 67 91 DONE events 241 driver only mode 12 DSP files 134 269 DTMF 76 collecting digits 53 digit collection functions 75 DTMFabort mask 19 echo cancellation examples 57 DTMFabort 19 NMS Communications Index E echo cancellation 57 encoding formats 13 adiGetEncodingInfo 113 adiPlayAsync 132 errors 237 239 events 243 245 categories 247 data structure 241 F fax 64 FSK data 76 adiStartReceivingFSK 179 adiStartSendingFSK 186 adiStopReceivingFSK 215 adiStopSendingFSK 217 sending and receiving 69 functions 79 call progress 74 configuration information 78 digit collection 75 DTMF and MF detection 76 FSK data 76 low level call control 77 on board timers 77 play 73 record 73 telephony protocol 73 tone detection 74 tone generation 75 G gain 29 generating tones 52 adiStartDTMF 161 adiStartTones 198 adiStopTones 224 functions summary of 75 275 Index H hostp2p demonstration program 232 I IP telephony gateways 57 L libadiapi so 12 low level call control 77 adiAssertSignal 80 adiQuerySignalState 139 adiStartDial 158 adiStartPulse 177 adiStartSignalDetector 189 adiStopDial 204 adiStopSignalDetector 218 performing 71 M MF 76 modems 64 N native play and record 31 adiSetNativeInfo 150 buffer sizes 17 DSP files 17 encoding formats 13 Natural Call Control service 9 nccGetLineStatusInfo 106 nccStartProtocol 61 NOCC 139
256. s 1 1 nnn 73 Terminating record and play 73 Using buffer management 0 02 4 73 Using status and modification functions 74 Call progress FUNCHONS 74 Tone detection FUNCTIONS e De Fe ait e nb Ge nein a 74 Tone generation functions aa aa aa 75 Digit Collection 2 4 1 66 anaes 75 Echo cancellation functions iier ente rh ACE he en n nae x ARE Rd genes 75 DTMF and MF detection 11 76 Frequency shift key data 6 6 nnn 76 Low level call control 4 4 4 1 1 1 1 nee 77 On board timer 2 44 4 42 2 2 2 11 4 nnn nnn 77 Configuration information 0 78 Chapter 5 Function reference 79 Using the f nction reference einer Ha Ix ERR EE ER E BE DER ERE
257. s x E FEE 18 D TMFabort sivas AE Ent 19 Recording teet LR OR RUE ORI AUREOS 20 MEE E 25 Systerrn restrictions o 30 Using simultaneous play and record 30 Performing NMS native play and record 2 6 nnns 31 NMS native play and record 31 Implementing NMS native play and record 32 METRUM 33 Native record without inband silence and DTMF 35 Native record with inband silence and DTMF detection 38 Managing call progreSS icc ees eere edet saa rera ka ed pee EXE eames 43 Tone detection eiae i e eio HE aya eae waar va x e Ra betes 43 Call progress tone events i ee e RENI OO ACCRUE MER RAO ORAT caer 48 Call progress voice events 010 011 memes seen 48 Call progress termination 1 12 44 49 System reStIcHONS sissen en inis venbesms nU NU EI s INO VE MURIS D ERI 49 Detecting icc TITTEN 50 Starting tone detection iecore e
258. s e ADIEVN_CP_DIALTONE e ADIEVN_CP_BUSYTONE e ADIEVN_CP_RORDTONE e ADIEVN_CP_SIT e ADIEVN_CP_NOANSWER e ADIEVN_CP_CED e ADIEVN_CP_TDD 156 NMS Communications ADI Service Developer s Reference Manual Function reference You can configure the ADI_CALLPROG_PARMS stopmask parameter to stop when any of the following events occur e ADIEVN_CP_RINGTONE e ADIEVN_CP_RINGQUIT e ADIEVN_CP_VOICE_BEGIN e ADIEVN_CP_VOICE_MEDIUM e ADIEVN_CP_VOICE_LONG e ADIEVN_CP_VOICE_EXTENDED e ADIEVN_CP_VOICE_END See also adiStopCallProgress Example Wait for voice detection or any network tone Returns SUCCESS if voice is detected within 30 seconds else DISCONNECT int waitforvoice CTAHD ctahd ADI_CALLPROG_PARMS parms CTA_EVENT event DWORD last Go evene 0 ctaGetParms ctahd ADI_CALLPROG_PARMID amp parms sizeof parms parms stopmask ADI_CPSTOP_ON_VOICE_BEGIN parms timeout 30000 Increase timeout from default 10 seconds if adiStartCallProgress ctahd amp parms SUCCESS return MYFAILURE do myGetEvent amp event see ctaWaitEvent example if ADIEVN CP VOICE lt event id amp amp event id lt ADIEVN CP CED last Go event while event id ADIEVN CP DONE Switch event value case CTA_REASON_FINISHED ti lacie eis ADUAN CS VOTCIT return SUCCESS else return MYDISCONNECT hang up tone detected case CTA_REASON_TIMEOUT
259. s 0 through 65534 Valid QX board range is 0 through 2047 Amount of delay associated with the comma character Valid range is 0 through 65535 259 Parameters ADI_DTMFDETECT_PARMS ADI Service Developer s Reference Manual Dependent function adiStartDTMFDetector Field name columnfour offqualampl offqualtime offthreshold onqualampl onqualtime onthreshold Type DWORD INT32 DWORD DWORD INT32 DWORD DWORD Default Units 1 mask 45 dBm 40 ms 0 92 0 IDU 39 dBm 50 ms OxCABO IDU ADI_ENERGY_PARMS Description Flag that indicates whether to detect the A B and D DTMF digits Set this value to 1 to detect these digits or 0 to ignore them Minimum signal required to maintain recognition of a DTMF signal once recognition has started Valid AG board CG board and PacketMedia HMP range is 51 through 15 Not used for QX boards Minimum duration of absence of a recognized DTMF signal before an end of digit event will be emitted Valid AG board CG board and PacketMedia HMP range is 5 through 32767 Valid QX board range is 30 through 32766 Do not modify Not used for QX 2000 boards Minimum signal level recognized as a DTMF signal Valid AG board CG board and PacketMedia HMP range is 51 through 15 Not used for QX boards Minimum duration of a recognized DTMF signal before a digit event is emitted Valid AG board CG board and PacketMedi
260. s of IP telephony applications must reduce the number of routers and the amount of packet jitter so that any residual uncanceled echo does not unnecessarily degrade the quality of the telephone connection Non voice terminals FAX and modem pass through For IP telephony applications it is desirable to handle non voice communication devices such as modems Modem transport can be handled by setting up a full duplex G 711 MSPP channel Disable the echo canceller since it impairs both FDM frequency division multiplexing and EC echo cancelling modem transmission For T 30 FAX T 38 can be used as a packet transport or the MSPP channel can be set to G 711 In either case disable the echo canceller Automatic speech recognition Speech control of an IVR application can present special echo control challenges Consider the following recommendations to improve the ability of the speaker to cut through a voice prompt to control the application e The echo suppressor should be disabled e echo canceller with the fastest adaptation time should be used Depending on which board you use you may be able to select an echo canceller that has faster convergence reduces echoes more quickly For example the CG 6000C echo canceller can be configured for a 100 percent adaptation rate fast With a 20 ms echo coverage this canceller requires 5 40 MIPS Minimization of two wire switching Hybrids in telephony circuits convert two wire transm
261. s of the echo canceller are Component Predelay buffer Finite impulse response FIR filter Subtractor Adaptation logic Double talk detector Non linear processor echo suppressor Input gain Bypass 60 Description Signals sent into the echo path enter a predelay buffer prior to being operated on by the FIR filter Depending on the board the predelay can be set from 0 toa maximum of 20 ms delay This predelay is introduced to compensate for the pure delay in the echo path The echo canceller FIR filter tries to mimic the echo path The coefficients or taps of the FIR filter determined by the adaptation logic determine the FIR filter response The FIR filter converges to mimic the echo channel when the coefficients of this filter equal the impulse response of the echo path The length of the FIR filter determines how much of an echo is covered by the echo canceller The FIR filter and the adaptation logic can be referred to as an adaptive filter The subtractor subtracts the output of the FIR filter from the signal in the send path If the adaptation performs well for example the echo path has been exactly identified Si is equal to the adaptive filter output echo estimate and the difference is zero Because the adaptive filter can never match the echo path exactly the difference between Sj and the echo estimate is never zero This difference is called the error signal and is used by the adaptive filter t
262. s or 32 kbit s Contains precise tone filters On AG boards loop start protocols use ptf xxx for the cleardown detector On AG and CG boards use ptf xxx for adiStartToneDetector and adiStartCallProgress Contains PCM play and record functions rvoice xxx is required to play or record with an encoding of ADI ENCODE MULAW ADI ENCODE ALAW ADI ENCODE PCM8M16 Contains PCM play and record functions Record functions can enable voice activity detection rvoice vad xxx is required to play or record with an encoding of ADI ENCODE MULAW ADI ENCODE ALAW or ADI ENCODE PCM8M16 Contains signaling ring detector and pulse functions These are out of band functions that typically operate on the MVIP signaling stream Required for any trunk protocol except NOCC Also required for adiStartSignalDetector adiQuerySignalState and adiStartPulse NMS Communications ADI Service Developer s Reference Manual AG boards tone m54 voice m54 None wave m54 NMS Communications CG boards tone fxx voice fxx None wave fxx DSP files Description Contains the tone generation function Required for all trunk protocols except NOCC Also required for adiStartTones adiStartDTMF and adiStartDial and for any record function to generate the beep Contains NMS Communications ADPCM play and record functions The compressed speech is in a framed format with 20 milliseconds of data per frame Speech is compressed t
263. slot ADI_VOICE_DUPLEX Receives and transmits in band data on the given timeslot Typically used with the NOCC protocol and allows media for example voice and fax reception and transmission ADI_FULL_DUPLEX This is both ADI SIGNAL DUPLEX and ADI VOICE DUPLEX The port receives and transmits both in band media and out of band signaling Use the demonstration program ctatest to verify that the ADI service is properly installed Refer to the Natural Access Developer s Reference Manual for more information about ctatest When you open the ADI service specify a DSP address A DSP address is specified as a timeslot Bus and stream fields are zero The following table shows valid timeslot values for NMS Communications boards Board Timeslot CG 6000 C 0 127 CG 6100C 0 599 CG 6500C 6565 C 0 511 CG 6060 PacketMedia HMP 0 maximum determined by license agreement AG 4000 C AG 4040 C 0 127 AG 2000 AG 2000 BRI 0 7 AG 2000C 0 23 QX 2000 0 3 NMS Communications 11 Overview of the ADI service ADI Service Developer s Reference Manual When the ADI service manager is attached to an event queue it opens the board driver and associates the muxable wait object returned by the driver open command with the event queue When this wait object is signaled on receipt of events from the board ctaWaitEvent processes the events through the ADI service and passes any event generated back to the calling fun
264. so provides detailed descriptions of the ADI functions Use this reference manual with the Natural Access Developer s Reference Manual This document is intended for developers of telephony and voice applications who are using Natural Access This document defines telephony terms where applicable but assumes that you are familiar with telephony concepts and the C programming language NMS Communications 7 2 Overview of the ADI service ADI service definition The ADI service is a C function library component of Natural Access that enables application programs to execute multiple telephony functions on NMS Communications AG boards CG boards QX boards and PacketMedia HMP software The ADI service provides the following functionality e Play record e Tone detection e Tone generation e DTMF collection e Echo cancellation e Auxiliary functions such as energy detection voice activity detection FSK data transmission and reception low level call control on board timers and board functions e Call progress Using ADI with the Natural Call Control service The Natural Call Control NCC service is the standard call control for NMS Communications products The NCC service replaces all call control functions that the ADI service formerly provided For more information about the NCC service refer to the Natural Call Control Service Developer s Reference Manual ADI terminology A port is the object on which te
265. stamp to a count of the seconds elapsed since January 1 1970 Sets the time on an AG board CG board or PacketMedia HMP process Sets parameters that enable applications to play and record media to and from RTP streams In addition this function enables applications to play media recorded from an RTP stream to a PSTN port and vise versa Board functions communicate only with the board s driver and not directly with the board When opening the ADI service to use these functions you do not specify an MVIP address The board number parameter in the mvipaddr structure can be set to ADI DRIVER ONLY 78 NMS Communications Function reference Using the function reference This section provides an alphabetical reference to the ADI service functions A prototype of each function is shown with the function description details of all arguments and return values Function information typically includes Supported Each function supports one or more of the following board types board types boards e AG boards e CG boards e PacketMedia HMP process Prototype The prototype is followed by a list of the function arguments NMS Communications data types include e WORD 16 bit unsigned DWORD 32 bit unsigned INT16 16 bit signed INT32 32 bit signed BYTE 8 bit unsigned If a function argument is a data structure the complete data structure is defined Return values The return value for a
266. stems Inc in the United States and or other countries All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International Inc in the United States and or other countries Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems Inc Linux is a registered trademark of Linus Torvalds Red Hat is a registered trademark of Red Hat Inc All other marks referenced herein are trademarks or service marks of the respective owner s of such marks All other products used as components within this product are the trademarks service marks registered trademarks or registered service marks of their respective owners Every effort has been made to ensure the accuracy of this manual However due to the ongoing improvements and revisions to our products NMS Communications cannot guarantee the accuracy of the printed material after the date of publication or accept responsibility for errors or omissions Revised manuals and update sheets may be published when deemed necessary by NMS Communications P N 9000 62162 18 Revision history Revision Release date Notes 1 0 May 2002 MCM combined 6424 20 and 6341 24 for Natural Access 2002 1 1 1 April 2003 MCM Natural Access 2003 1 1 2 December 2003 SRR Natural Access 2004 1 Beta 1 3 April 2004 MCM Natural Access 2004 1 1 4 November 2004 SRR Natural Access 2005 1 Beta 1 5 March 2005 SRR Natural Access 2005 1
267. stored in the internal digit queue None of these functions can be invoked if the application is actively collecting digits with adiCollectDigits 54 NMS Communications ADI Service Developer s Reference Manual Developing applications Asynchronous digit collection The ADI service enables applications to collect DTMF digit strings asynchronously into their own buffers adiCollectDigits initiates digit collection into a user specified buffer rather than into the ADI service digit queue Digits are appended to the user specified buffer until a terminating event occurs The following illustration represents asynchronous digit collection i i ADI Application NUM adiColle 42 8 User buffer ADI service digit queue ADIEVN_DIGIT_BEGIN 8 a ADIEVN_DIGIT_END 8 ADIEVN_DIGIT_BEGIN 3 ADIEVN_DIGIT_END 3 mm ADIEVN DIGIT BEGIN 7 ADIEVN COLLECTION DONE ADIEVN DIGIT END 7 gTr Time Time Because they perform read and write operations on the internal digit queue an application cannot call adiGetDigit and adiFlushDigitQueue while actively collecting digits The ADI service returns an error if an application attempts to modify the internal digit queue while digit collection is active You can modify the collection function s default behavior by redefining the parameters in ADI_COLL
268. synchronous adiCommandEchoCanceller Asynchronous Sends commands to the echo canceller tone disabler adiModifyEchoCanceller Asynchronous Modifies the echo canceller parameters after echo cancellation is started NMS Communications 75 Function summary ADI Service Developer s Reference Manual DTMF and MF detection functions The ADI service provides functions for enabling and disabling DTMF and MF detection By default DTMF detection is enabled when a call is established The following functions enable and disable DTMF and MF tone detection Function Synchronous Description Asynchronous adiStartDTMFDetector Asynchronous Starts DTMF detection default is on adiStopDTMFDetector Asynchronous Stops DTMF detection adiStartMFDetector Asynchronous Starts the MF tone detector adiStopMFDetector Asynchronous Stops the MF tone detector Frequency shift key data functions NMS boards are capable of sending and receiving frequency shift key FSK data The transmit function is an implementation of the modem portion of Bellcore advisory TA NWT 000030 The basic modulation is continuous phase binary FSK at 1200 baud between 1200 Hz mark and 2200 Hz space The only supported baud rate is 1200 Alternatively the implementation is based on ITU V 23 FSK at 1200 baud between 1300 Hz mark and 2100 Hz space The following functions are used to send or receive frequency shift key data Function Synchronous Descriptio
269. t valid in the current port state CTAERR_SVR_COMM Server communication error Details Use adiModifyPlaySpeed to alter the speed faster or slower applied to voice data as it is being transmitted The speed remains set only for the current play operation instance Values specified out of range are limited by the range the valid AG and CG board range is 100 to 200 percent Refer to the board installation and developer s manual for a table of MIPS usage for all functions Note The PacketMedia HMP process and QX 2000 boards do not support this function If this function is called using a QX 2000 board CTAERR_FUNCTION_NOT_AVAIL is returned If this function is called using PacketMedia HMP it has no effect on the speed and does not return an error message See also adiModifyPlayGain adiPlayAsync adiPlayFromMemory adiStartPlaying adiStopPlaying 130 NMS Communications ADI Service Developer s Reference Manual Function reference adiPeekDigit Reads the first digit in the ADI service internal digit queue without removing it Supported board types e PacketMedia process Prototype DWORD adiPeekDigit CTAHD ctahd char digit Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext I digit Pointer to a character to store the digit copied from the digit queue Return values Return value Description SUCCESS CTAERR_BAD_ARGUMENT di
270. table lists the ADI encoding formats Encoding format ADI_ENCODE_NMS_16 ADI_ENCODE_NMS_24 ADI_ENCODE_NMS_32 ADI_ENCODE_NMS_64 ADI_ENCODE_MULAW ADI_ENCODE_ALAW ADI_ENCODE_EDTX_MULAW ADI_ENCODE_EDTX_ALAW ADI_ENCODE_PCM8M16 ADI_ENCODE_OKI_24 ADI_ENCODE_OKI_32 ADI_ENCODE_PCM11M8 ADI_ENCODE_PCM11M16 ADI_ENCODE_G723_5 ADI_ENCODE_G723_6 ADI_ENCODE_EDTX_G723_5 NMS Communications Description NMS Communications ADPCM 16 kbit s NMS Communications ADPCM 24 kbit s NMS Communications ADPCM 32 kbit s Framed PCM 64 kbit s mu law 64 kbit s A law 64 kbit s mu law 64 kbit s with EDTX headers A law 64 kbit s with EDTX headers PCM 8 kss 16 bit mono WAVE OKI ADPCM 24 kbit s OKI ADPCM 32 kbit s PCM 11 kss 8 bit mono WAVE PCM 11 kss 16 bit mono WAVE ITU G 723 1 5 3 kbit s ITU G 723 1 6 3 kbit s ITU G 723 1 5 3 kbit s with EDTX headers Sample Sample size bits 2 16 N A N A N A rate Hz 8000 8000 8000 8000 8000 8000 8000 8000 8000 6000 8000 11000 11000 8000 8000 8000 Frame size bytes 42 62 82 162 80 80 82 82 160 30 40 110 220 20 24 22 Developing applications Frame time ms 20 20 20 20 10 10 10 10 10 10 10 10 10 30 30 30 Data rate bytes sec 2100 3100
271. tected before call progress reports a medium voice event Do not modify 255 Parameters ADI_COLLECT_PARMS ADI Service Developer s Reference Manual Dependent function adiCollectDigits Field name Type Default firsttimeout DWORD 10000 intertimeout DWORD 5000 terminators DWORD 0 0 validDTMFs DWORD 0x07FF waitendtone DWORD 0 Valid DTMF values A value that combines all of the valid DTMF values can be formed by using ADI DIGIT ALL OxFFFF Values can also be formed by using the OR operation with any of the following values Digit 256 Name ADI DIGIT 0 ADI DIGIT 1 ADI DIGIT 2 ADI DIGIT 3 ADI DIGIT 4 ADI DIGIT 5 ADI DIGIT 6 ADI DIGIT 7 ADI DIGIT 8 ADI DIGIT 9 ADI DIGIT STAR Units ms ms mask mask mask Value 0x0001 0x0002 0x0004 0x0008 0x0010 0x0020 0x0040 0x0080 0x0100 0x0200 0x0400 Description Maximum time to wait for the first digit Use 0 to wait forever Otherwise the valid range is 1 through 2147483647 Maximum time to wait for any digit after the first digit Use 0 to wait forever Otherwise the valid range is 1 through 2147483647 Mask that specifies which digits cause collection to terminate A value can be formed by using the OR operation with any of the values for the validDTMFs field Use 0 to indicate no terminators Mask that specifies the digits to collect only specified digits are adde
272. the PSTN the echo canceller cancels the near end echo or in some cases no echo at all For a near end echo the requirements are the same as in the previous case Without proper echo control in an IP telephony application annoying echo can be heard by both speakers in a duplex voice conversation The longer the delay through the IP network the more unpleasant the effects of any residual or uncancelled echo Echo canceller components The following illustration shows the structure of the echo canceller Mode gt Rin Rout Predelay Windowing Flterlength Predelay buffer FIR filter s S o 1 Adapt 2 5 Double talk Adaptation detector logic Adapttime Y Y K N Bypass NLP Subtractor y mux gt lt lt Sin Sout U Bypass Enable Gain Disable Echo cancellers are four port devices two ports facing the near end and two ports facing the far end The four ports are Rin Sn and Sout R stands for receive if the port is situated in the receive path S stands for send if the port is situated in the send path The subscripts n and define the input and output ports of the echo canceller on the corresponding path NMS Communications 59 Developing applications ADI Service Developer s Reference Manual The main component
273. the interdigit timeout value in ADI COLLECT PARMS is exceeded Modifying DTMF detection You can modify the DTMF detector s default behavior when invoking adiStartProtocol or adiStartDTMFDetector The DTMF detector parameters are stored in the ADI DTMFDETECT PARMS structure The following illustration shows the effect of these parameters Signal onqualtime amplitude offqualtime onqualampl ee offqualampl pes aE Note Do not modify onthreshold offthreshold These parameters apply to the DSP algorithms and are provided for diagnostic purposes when working with NMS Technical Services Terminating DTMF detection adiStopDTMFDetector immediately terminates DTMF detection The ADI service generates ADIEVN_DTMFDETECT_DONE with the value set to CTA_REASON_STOPPED The ADI service can also generate ADIEVN_DTMFDETECT_DONE with an error code ADIERR_xxx or CTAERR_xxx if the function is incorrectly started Improving DTMF using echo cancellation Echo cancellation improves the ability of the DTMF detector to recognize digits during play a capability referred to as DTMF cut through performance Using echo cancellation with the DTMF detector allows the use of a more selective DTMF detector which improves resistance to talk off the false detection of digits in a speaker s voice 56 NMS Communications ADI Service Developer s Reference Manual Developing applications
274. tion can be used when digits arrive from either DTMF detection or from an out of band indication such as RFC2833 packets The DTMF digits are automatically added to the queue whereas you must call this function to add the out of band digits The digit queue holds 62 characters If the digit queue is full the oldest character is discarded without an error indication If the digit is in the abort mask of an active play or record operation the play or record operation terminates immediately If any digit in the queue is in the abort mask subsequent play or record operations terminate immediately after being started Use adiFlushDigitQueue adiGetDigit or adiCollectDigits to remove digits from the queue For more information refer to Collecting digits on page 53 NMS Communications 121 Function reference ADI Service Developer s Reference Manual See also adiPeekDigit Example 122 NMS Communications ADI Service Developer s Reference Manual Function reference adiModifyEchoCanceller Modifies echo cancellation parameters after echo cancellation is started Supported board types CG Prototype DWORD adiModifyEchoCanceller ctahd ADI_ECHOCANCEL_PARMS parms m Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext parms Pointer to echo cancellation parameters as shown typedef struct parameters for echo cancellation WORD size
275. tions 265 Parameters ADI Service Developer s Reference Manual Field name Type Default Units Description echocancel adapttime Echo canceller adaptation time for echocancel mode 2 The valid AG board and CG board range is 100 through 1000 Lower values require more DSP processing power Not used for QX boards echocancel filterlength Filter length of echo canceller for echocancel mode 2 Set this value to 0 to omit echo cancelling Valid range is 0 through 20 Higher values require more DSP processing power echocancel gain Amount of amplification applied to echo cancelled output Valid AG board and CG board range is 54 through 24 Done by the automatic gain control AGC module for QX boards Bit field echocancel mode Controls echo canceller operation Set the mode to one of the following e 0 No echo cancellation 1 Use internal defaults for filter length and adaptation time based on board type e 2 Use specified values e 3 Ignore specified filterlength and adapttime values for adiModifyEchoCanceller only Additional values can be formed by using the OR operation See echocancel mode valid values on page 267 echocancel predelay ms Output sample delay Valid range is 0 through 9 For AG boards and CG boards valid range is 0 through 20 For boards the default value is 0 callctl mediamask valid values A value can be formed by using the OR operation with any of the following val
276. trol protocols upon transition to the ADI CC STATE CONNECTED state After this function is called DTMF events are not reported After the DONE event is received restart the detector with adiStartDTMFDetector adiCollectDigits does not work if you disable DTMF detection No digits are collected and no events are generated 206 NMS Communications ADI Service Developer s Reference Manual Function reference Example NMS Communications 207 Function reference ADI Service Developer s Reference Manual adiStopEnergyDetector Stops the energy detector Supported board types e PacketMedia process Prototype DWORD adiStopEnergyDetector CTAHD ctahd Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext Return values a Return value Description SUCCESS CTAERR_FUNCTION_NOT_ACTIVE Attempt made to stop a function that was not running CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_SEQUENCE Attempt made to stop a function that is already being stopped CTAERR_INVALID_STATE Function not available in the current port state CTAERR_SVR_COMM Server communication error Events Description ADIEVN_ENERGY_DETECT_DONE After the detector stops the ADI service generates a DONE event with the value field set to CTA_REASON_STOPPED Details Use adiStopEnergyDetector to stop the low level energy detector started by adiSta
277. ts ID Value field Size field ADIEVN_PLAY_BUFFER_REQ 1 started 2 underrun ADIEVN_PLAY_DONE ADI_REASON_xxx Bytes played ADIEVN_RECORD_BUFFER_FULL 1 buffer requested Buffer size 2 underrun 3 both ADIEVN_RECORD_DONE ADI_REASON_xxx Bytes recorded ADIEVN_RECORD_EVENT ADIEVN_RECORD_STARTED 0 zero or ADI RECORD BUFFER REQ Note The CTA_EVENT buffer field for ADIEVN RECORD BUFFER FULL contains a data pointer DTMF events ID Value field Size field ADIEVN COLLECTION DONE ADI REASON xxx String length 1 ADIEVN DIGIT BEGIN 0 through 9 A through D asterisk number sign ADIEVN DIGIT END 0 through 9 A through D asterisk number sign ADIEVN DTMF DETECT DONE ADI REASON xxx Note The CTA EVENT buffer field for ADIEVN COLLECTION DONE contains a data pointer MF events Size field is not applicable Value field ADIEVN MF DETECT DONE ADI REASON xxx ADIEVN DIGIT BEGIN 0 through 9 B through F ADIEVN DIGIT END 0 through 9 B through F Note See adiStartMFDetector for translation of MF events 248 NMS Communications ADI Service Developer s Reference Manual Events Call progress events Size field is not applicable ID Value field ADIEVN CP BUSYTONE ADIEVN CP CED ADIEVN CP DIALTONE ADIEVN CP DONE ADI REASON xxx ADIEVN NOANSWER ADIEVN CP RINGQUIT ADIEVN CP RINGTONE Number of rings ADIEVN CP REORDERTONE ADIEVN CP SIT ADIE
278. tural Access application that shares a context with the first application 1 Initialize the Natural Access application 2 Create event queues 3 Attach the application to the existing context Initializing Natural Access Initialize Natural Access by calling ctaInitialize and specifying the service and service manager names Service managers are dynamic link libraries DLLs in Windows and shared libraries in UNIX Only the services initialized in the call to ctaInitialize can be opened by the application Use one of the following service managers in your call to ctaInitialize Board family Manager ADIMGR ADIMGR QDIMGR Note The PacketMedia HMP process is a member of the CG board family Creating event queues and contexts After initializing Natural Access create the event queues and contexts Create one or more event queues by calling ctaCreateQueue and specifying the service managers to attach to each queue The ADI service manager is ADIMGR or QDIMGR When you attach a service manager to a queue you make that service manager available to the queue Create a context by calling ctaCreateContext and providing the queue handle ctaqueuehd that was returned from ctaCreateQueue All events for services on the context are received in the specified event queue ctaCreateContext returns a context handle ctahd which the application supplies when invoking ADI service functions Events communicated back to the app
279. udio streams and specifies the desired behavior for native play operations e Starts and stops playing audio data from a native audio stream The following illustration shows an overview of the native play mechanism ADI service ADI port Audio data RTP endpoint Sample procedure When implementing native play functionality applications use functions from the following resources e Natural Access functions to set up event queues and contexts and to open services on the contexts e ADI service functions to start a protocol set native play settings and play out audio data e MSPP functions to create an RTP endpoint and retrieve the unique filter ID for the endpoint NMS Communications 33 Developing applications ADI Service Developer s Reference Manual The following procedure shows functions used to implement a typical native play operation Step Action 1 Invoke ctaCreateQueue to create a Natural Access event queue ctaCreateQueue amp queuehd 2 Invoke ctaCreateContext to create a Natural Access context for the audio channel ctaCreateContext queuehd amp ctahd 3 Invoke ctaOpenServices to open the ADI and MSPP services on the context ctaOpenServices ctahd svclist nsvcs 4 Invoke adiStartProtocol to start the nocc protocol on the ADI port adiStartProtocol ctahd nocc NULL startparms 5 Invoke mspCreateEndpoint to create an audio MSPP service RTP endpoint mspCreateEndpoint r
280. ued in the driver Error returned by the driver in sending a message to the board Occurs if the board was reset Driver does not support the requested function Internal error occurred in the Natural Access library Attempt made to start an asynchronous function that is already started Also returned if an attempt was made to get a digit or flush the digit queue while collecting digits Attempt made to stop or modify a function that was not running Also occurs when a function call is made to ADI call control when the NCC service is active e Necessary dsp or tcp file was not downloaded to the board e Requested function required a service that is reserved for use by call control Specified board number was not successfully configured Context handle is invalid e Attempt was made to stop a function that is already being stopped e Play or record buffer was submitted when it was not expected NMS Communications ADI Service Developer s Reference Manual Numerical error summary Errors Error name Hex Decimal Description CTAERR_INVALID_STATE 0 0000000 12 Function is not valid in the current port state For example most functions require the port to be in ADI_STATE_STARTED which is entered after starting a trunk protocol CTAERR_LOCK_TIMEOUT 0x0000001D 29 Thread lock timed out CTAERR NOT FOUND 0x0000000A 10 Specified parameter does not exist CTAERR NOT IMPLEMENTED 0x00000009 9 Fun
281. uencies otherwise zero bandw2 Bandwidth of the second frequency parms Pointer to tone detection parameters as shown NULL designates default values typedef struct DWORD size size of this structure ay INT32 qualampl broadband qual level in dBm 5 DWORD qualtime qualification time in ms iu DWORD reflevel qual thresh output of filter IDUs DWORD reserved reserved must be 0 a7 ADI TONEDETECT PARMS Refer to ADI PARMS on page 268 for field descriptions 194 NMS Communications ADI Service Developer s Reference Manual Function reference Return values Return value SUCCESS ADIERR_INVALID_CALL_STATE CTAERR_BAD_ARGUMENT CTAERR_FUNCTION_ACTIVE CTAERR_FUNCTION_NOT_AVAIL CTAERR_INVALID_CTAHD CTAERR_INVALID_STATE CTAERR_SVR_COMM Events Event ADIEVN_TONE_1_BEGIN ADIEVN_CP_CED ADIEVN_CP_DIALTONE ADIEVN_CP_DONE ADIEVN_TONE_1_END ADIEVN_TONE_2_BEGIN ADIEVN_TONE_2_END ADIEVN_TONE_3_BEGIN ADIEVN_TONE_3_END ADIEVN_TONE_4_BEGIN ADIEVN_TONE_4_END ADIEVN_TONE_5_BEGIN ADIEVN_TONE_5_END ADIEVN_TONE_6_BEGIN ADIEVN_TONE_6_END ADIEVN_TONE_1_DETECT_DONE ADIEVN_TONE_2_DETECT_DONE ADIEVN_TONE_3_DETECT_DONE ADIEVN_TONE_4_DETECT_DONE ADIEVN_TONE_5_DETECT_DONE ADIEVN_TONE_6_DETECT_DONE NMS Communications Description Function not available in the current call state Function argument had an invalid value or a required pointer argument was NULL Function
282. ues Value Description 0x0001 Reserve DTMF detector Not used for QX boards 0x0002 Reserve silence detector Not used for QX boards 0x0004 Reserve cleardown detector Not used for QX boards 0x0008 Start DTMF detector 0x0010 Start echo canceller 266 NMS Communications ADI Service Developer s Reference Manual echocancel mode valid values Value 0x0004 0x0008 0x0010 0x0020 0x0040 0x0080 0x0100 0x0200 ADI_TONE_PARMS Description Parameters Enable dynamic windowing QX boards only Enable echo suppressor Do not reset echo canceller Disable filter taps adaptation Bypass echo cancellation AG boards and CG boards only Request status of echo canceller AG boards and CG boards only Enable auto status event generation when status of echo canceller changes AG boards and CG boards only Enable comfort noise generation AG boards and CG boards only Dependent function adiStartTones Field name ampli ampl2 fregi freq2 iterations offtime ontime Type INT32 INT32 DWORD DWORD INT32 DWORD DWORD NMS Communications Default Units 20 1000 200 dBm dBm Hz Hz integer ms ms Description Amplitude of the first or only frequency component Valid AG board CG board and PacketMedia HMP range is 54 through 3 Valid board range is 90 through Amplitude of the second frequency component if any Valid AG b
283. ult 1 VAD disable See also adiPlayAsync adiPlayFromMemory adiRecordAsync adiRecordToMemory adiStartPlaying adiStartRecording Example void mySetNativeInfo CTAHD ctahd DWORD ingresshd DWORD egresshd int encoding int payloadID ADI_NATIVE_CONTROL np np rec_encoding encoding np play_encoding encoding np frameformat 0 np include2833 0 np mode ADI_NATIVE np nsPayload 0 np payloadID payloadID np vadFlag 1 if ret adiSetNativeInfo ctahd ingresshd egresshd amp np SUCCESS printf Set Native Control Successful for handle x n ctahd else printf Set Native Control Failed x for handle x n ret ctahd return NMS Communications 153 Function reference ADI Service Developer s Reference Manual adiStartCallProgress Starts monitoring call progress analysis data Supported board types Prototype DWORD adiStartCallProgress CTAHD ctahd ADI_CALLPROG_PARMS parms Argument Description ctahd Context handle returned by ctaCreateContext or ctaAttachContext _ parms Pointer to call progress analysis parameters stored the ADI_CALLPROG_PARMS as follows NULL designates default values typedef struct DWORD size Size of this structure DWORD timeout If tone voice detected done via timeout ms DWORD busycount Number of busy cycles until report and quit busycount ignored if pre
284. unction reference ADI Service Developer s Reference Manual For more information see Encoding formats and DSP files on page 134 The table lists the DSP files that must be loaded on AG and CG boards It also lists the valid encoding types that QX boards and PacketMedia HMP processes support Refer to the board installation and developer s manual for MIPS usage For QX boards and the PacketMedia HMP process the maxspeed and speed parameters are not used The ADI service allocates a buffer and invokes the access function provided by the programmer The buffer and size are passed to the callback function and the application must fill the buffer with voice data for example read data from a file before returning access is invoked from within adiStartPlaying for the first buffer and subsequently invoked from within ctaWaitEvent The prototype for the callback function is int NMSSTDCALL access void userarg void buffer unsigned size unsigned rsize EE Argument Description userarg Pointer to value previously passed to adiStartPlaying lt buffer Pointer to memory to be filled with voice data size Size bytes of the buffer rsize Returned number of bytes of voice data put into the buffer by the callback routine This value is returned to the ADI service access has the following return values Return value Description SUCCESS Play continues as normal The ADI service invokes access again
285. up refer to the NMS OAM System User s Manual NMS Communications 29 Developing applications ADI Service Developer s Reference Manual System restrictions Consider the following system restrictions when using voice record and playback e Only one function can drive the output to the telephone line therefore the following functions are mutually exclusive e Voice recording with beep enabled since the record beep prompt drives the output e Voice play e Tone generation e FSK sending e If the DTMF detector is disabled voice functions cannot terminate when digits are entered e The following functions are typically configured to share the same group of task processors e Call progress e Voice record e Voice play e Tone generation e MF detection For the typical configuration DSP capacity is allotted under the assumption that every context is running no more than one of these functions at any given time There is nothing preventing the application from concurrently executing some combinations of these functions on some contexts If however multiple contexts concurrently execute a combination of these functions the DSP capacity may be exhausted Delays in data processing NMS Communications boards support DSP functions using a variety of data block sizes As a consequence the delays in data processing depend on the data block size of the specific DSP function In addition command and event processing to and from
286. uring the receive process errors can occur that cause the function to terminate prematurely If errors occur ADIEVN_FSK_RECEIVE_DONE is sent with one of the following reasons Reason Description ADI_REASON_DROP_IN_DATA Stopped because of drop in data The noseizureflag signal dropped to silence during data not during stop mark period ADI_REASON_BAD_STOP_BIT Stopped because of data framing error The stop bit at the end of data was a space not a mark Parameters for receiving FSK data adiStartReceivingFSK requires the following parameters defined in the ADI_FSKRECEIVE_PARMS structure Field Description Default value minlevel Required minimum receive level 35 dBm minmark Required minimum initial mark and seizure time in milliseconds 10 mindrop Minimum dropout to silence before a packet is considered terminated in 5 milliseconds baudrate Transmission baud rate 1200 Terminating FSK data reception Use adiStopReceivingFSK to stop the receive function The event value field contains CTA_REASON_STOPPED The size of the partial buffer received is stored in the size field of the event structure 70 NMS Communications ADI Service Developer s Reference Manual Developing applications Performing low level call control The ADI service includes functions that enable applications to perform call control from the host These functions are typically used with the NOCC no call control protocol Their use is restr
287. user defined tones adiStartDTMF Asynchronous Starts playing a sequence of DTMF tones MF tones can also be generated adiStopTones Asynchronous Terminates playing tones Digit collection functions The ADI service provides the following synchronous and asynchronous digit collection functions Function Synchronous Description Asynchronous adiGetDigit Synchronous Retrieves a single digit from the internal digit collection queue adiInsertDigit Synchronous Inserts a digit at the end of the ADI service internal digit queue adiPeekDigit Synchronous Reads the first digit from the internal digit collection queue without removing it adiFlushDigitQueue Synchronous Flushes the internal digit collection queue adiCollectDigits Asynchronous Starts asynchronous digit collection adiStopCollection Asynchronous Terminates digit collection Echo cancellation functions Echo cancellation improves DTMF tone detection and speech recognition performance during playing by canceling any leakage of the playback audio from the receive signal path It also improves peer to peer human communications in an IP telephony gateway application by eliminating talker echo Echo cancellation is configured as part of starting a protocol with adiStartProtocol The echo canceller automatically starts when a call enters the conversation state The following functions modify echo cancellation parameters Function Synchronous Description A
288. ver communication error 97 Function reference ADI Service Developer s Reference Manual Details Use adiGetBoardInfo to retrieve hardware configuration data for the specified board The board argument identifies a particular board This identifier must correlate to a board ID in the board keyword file Refer to the board installation and developer s manual for more information Note If an analog board is populated with a mixture of line interface types the type of the lowest numbered interface is reported AG 4040 and AG 4040C boards are software compatible with AG 4000 and AG 4000C boards When retrieving board information on AG 4040 or AG 4040C boards adiGetBoardInfo reports the ADI board type as one of the AG 4000 or AG 4000C board types for example ADI BOARDTYPE AG4000 4T The AG 4040 or AG 4040C trunk type either T1 or E1 is configured in the board keyword file If the trunk type is not specified adiGetBoardInfo reports the ADI board type as one of the T1 variants The ctahd argument is used to access the context on which the ADI service was opened The ADI service can be opened in driver only mode if desired In this case no actual board resources are reserved Set the board field in the MVIP_ADDR structure passed to ctaOpenServices to ADI AG DRIVER ONLY This function also works with a context that has the ADI service opened on actual MVIP streams and timeslots The size argument indicates how much memory to write at board
289. vice generates ADIEVN_SIGNALBIT_CHANGED with the value field set to the bit change and the size field set to the current state of the signaling bits The change is defined as follows OxA1 A bit went HI OxB1 B bit went HI OxC1 C bit went HI OxD1 D bit went HI OxAO A bit went LO OxBO B bit went LO OxCO C bit went LO OxDO D bit went LO The current state is a mask of the bits ADI ADI B ADI C BIT and ADI D These messages are serialized with the transitions You receive one event for each bit change ADIEVN SIGNAL DETECT DONE The value field can be set to any of the following CTAERR xxx or ADIERR Signal detector function failed CTA REASON STOPPED Function stopped as a result of calling adiStopSignalDetector Details AG 2000 AG 2000C and AG 2000 BRI boards require signal m54 to be loaded Use adiStartSignalDetector to enable detection of incoming out of band signaling bits After this function is called transitions of masked bits are reported as events along with the current state of all bits If the line state does not match the value set in initial an event is generated after qualification time timeon or timeoff Note This function is incompatible with standard call control Contexts running a standard protocol other than NOCC are usually excluded from using this function Protocols usually use out of band signaling bits for call setup detection of in
290. y allows the application to control and monitor the placement of outbound calls when not using call control for example when using the NOCC protocol Call progress analysis can also be used at any time after a call is connected For example when receiving an inbound call an application can start up a call progress analysis operation to detect modem tones fax terminal tones or voice The following ADI functions start and stop call progress analysis Function Synchronous Description Asynchronous adiStartCallProgress Asynchronous Starts call progress analysis adiStopCallProgress Asynchronous Stops call progress analysis Tone detection functions The following functions enable and disable detectors of precise tones raw energy and silence Function Synchronous Description Asynchronous adiStartToneDetector Asynchronous Starts a precise tone detector adiStopToneDetector Asynchronous Stops a precise tone detector adiStartEnergyDetector Asynchronous Starts the energy detector energy versus silence adiStopEnergyDetector Asynchronous Stops the energy detector energy versus silence 74 NMS Communications ADI Service Developer s Reference Manual Function summary Tone generation functions NMS boards generate single and dual frequency tones The following ADI functions control tone generation Function Synchronous Description Asynchronous adiStartTones Asynchronous Plays a sequence of
291. ypedef struct DWORD size returned size GetPlayStatus DWORD reason reason last play ended A DWORD buffercount counter of buffers submitted DWORD framecount number of frames submitted DWORD totalbytes total bytes submitted af void buffer last buffer pointer submitted DWORD bytecount size of last buffer submitted DWORD bytesplayed total bytes actually played oe DWORD timestarted actual time started ms units DWORD underrun counts out of frame events 5 ADI PLAY STATUS Refer to the Details section for field descriptions Amount of memory available at info to receive the ADI_PLAY_STATUS Return values SUCCESS CTAERR_BAD_SIZE CTAERR_SVR_COMM NMS Communications Return value Description CTAERR_BAD_ARGUMENT info is NULL size is smaller than the size of DWORD CTAERR_INVALID_CTAHD Context handle is invalid CTAERR_INVALID_STATE Function not valid in the current port state Server communication error 115 Function reference ADI Service Developer s Reference Manual Details Use adiGetPlayStatus to retrieve status information about the active or most recently completed voice play operation for the specified context Up to size bytes of the ADI_PLAY_STATUS structure are copied to the address pointed to by info If size is greater than or equal to the size of ADI_PLAY_STATUS the complete structure is copied The number of bytes copied is returne

ADI Service Developer`s Reference Manual

Contents

Download Pdf Manuals

Related Search

Related Contents