Meucci Manual Do Program Ad Or

Guia do Programador

Sistema de Desenvolvimento para placas Digivoice.

MAN0048 - Verso: 4.3.0.0Copyright 2010 Digivoice Eletrnica

Contedo

Introduo Recursos para o Desenvolvedor Primeiros Passos14. 14. 16. 19. 20. 20. 22. 23. 25. 26.Windows 32/64 bits Instalao no Windows Testando a placa instalada Linux Instalao no Linux Preparando o ambiente Mdulos do kernel Compilando a VoicerLib Exemplo em linguagem C

Guia de Programao28. 32. 33. 41. 44. 45. 46. 47. 48. 60. 61. 63.Conceitos Bsicos - API Conceitos Bsicos - ActiveX Guia de Migrao de Verses Anteriores Instrues de instalao de placas Inicializando os Servios Finalizando os Servios Detectando Ring Atendendo e Desligando Superviso de Linha Deteco de Silncio Deteco de Tons Deteco de Dgitos

Digivoice VoicerLib 4Copyright 2010 Digivoice Eletrnica

2

Contedo

67. 68. 71. 77. 79. 81. 84. 91. 92. 93. 97. 98. 99. 101. 101. 102. 102. 104. 105. 107. 109. 110. 110. 111. 114. 115. 116. 117. 117. 118. 120. 121. 122.

Identificao de Chamadas Portas Virtuais Gravando uma Conversa Reproduzindo Mensagens Conferncia entre portas Streaming de udio Utilizando a placa VB0404GSM Gravao em Paralelo Placas FXO Placas E1 Programao das Placas E1 Configuraes de Sincronismo Alarmes Protocolo CAS Customizado Introduo CAS Customizado Protocolo ISDN PRI Inicializao Protocolo ISDN PRI Funes de Controle da Thread ISDN PRI Efetuando Chamadas Recebendo Chamadas Finalizando Chamadas Protocolo R2D MFC Inicializao Protocolo R2D MFC Efetuando Chamadas Recebendo Chamadas Funes de Controle da Thread R2 Depurando aplicativos para placas E1 com R2MFC Funes Especiais Introduo Funes Especiais Funes de Idle Funes de Prompt Funes de Menu Funes de Discagem e Transferncia


3

Contedo

125. 126. 127. 128. 129. 133.

Reproduzindo Data Reproduzindo Nmeros Cardinais Reproduzindo Nmeros Dgito a Dgito Reproduzindo Valores por Extenso Reproduzindo Lista de Mensagens Distribuindo uma Aplicao

Guia de Referncia134. 140. 141. 142. 143. 144. 145. 146. 148. 149. 150. 151. 152. 157. 160. 163. 165. 167. 169. 170. 172. 174. 176. 177. 179. 181. 183.Mensagens de Erro Funes/Mtodos AbortCall AudioMonitor (dg_AudioMonitor) CancelGetDigits (dg_CancelGetDigits) ChatAddPort (dg_ChatAddPort) ChatDisablePort (dg_ChatDisablePort) ChatEnablePort (dg_ChatEnablePort) ChatRemovePort (dg_ChatRemovePort) CheckCode (dg_CheckCode) ClearDigits (dg_ClearDigits) ConnectAudioChannels (dg_ConnectAudioChannels) ConfigCallProgress (dg_ConfigCallProgress) ConfigCustomCAS (dg_ConfigCustomCAS) ConfigE1Thread (dg_ConfigE1Thread) ConfigGSMThread (dg_ConfigGSMThread) ConfigISDNThread (dg_ConfigISDNThread) CreateCallProgress (dg_CreateCallProgress) CreateChatRoom (dg_CreateChatRoom) CreateCustomCAS (dg_CreateCustomCAS) CreateE1Thread (dg_CreateE1Thread) CreateGSMThread (dg_CreateGSMThread) CreateISDNThread (dg_CreateISDNThread) CreateLoggerControl (dg_CreateLoggerControl) CreateLoggerCCS (dg_CreateLoggerCCS) DefinePortResource (dg_DefinePortResource) DestroyCallProgress (dg_DestroyCallProgress)


4

Contedo

184. 185. 186. 187. 188. 189. 190. 191. 192. 194. 195. 197. 198. 199. 200. 201. 202. 203. 204. 205. 206. 207. 208. 209. 210. 211. 213. 215. 216. 218. 219. 221. 222. 223. 225. 226. 228.

DestroyChatRoom (dg_DestroyChatRoom) DestroyCustomCAS (dg_DestroyCustomCAS) DestroyE1Thread (dgDestroyE1Thread) DestroyGSMThread (dg_DestroyGSMThread) DestroyISDNThread (dg_DestroyISDNThread) DestroyLoggerControl (dg_DestroyLoggerControl) DestroyLoggerCCS (dg_DestroyLoggerCCS) dg_SetEventCallback Dial (dg_Dial) DisableAGC (dg_DisableAGC) DisableAnswerDetection (dg_DisableAnswerDetection) DisableAutoFramers (dg_DisableAutoFramers) DisableCallProgress (dg_DisableCallProgress) DisableDebug (dg_DisableDebug) DisableDTMFFilter (dg_DisableDTMFFilter) DisableE1Thread (dg_DisableE1Thread) DisableEchoCancelation (dg_DisableEchoCancelation) DisableGSMThread (dg_DisableGSMThread) DisableInputBuffer (dg_DisableInputBuffer) DisableISDNThread (dg_DisableISDNThread) DisableMailBoxDetection (dg_DisableMailBoxDetection) DisablePulseDetection (dg_DisablePulseDetection) DisableSilenceDetection (dg_DisableSilenceDetection) DisconnectAudioChannels (dg_DisconnectAudioChannels) EnableAGC (dg_EnableAGC) EnableAnswerDetection (dg_EnableAnswerDetection) EnableCallProgress (dg_EnableCallProgress) EnableDebug (dg_EnableDebug) EnableDTMFFilter (dg_EnableDTMFFilter) EnableE1Thread (dg_EnableE1Thread) EnableEchoCancelation (dg_EnableEchoCancelation) EnableFSKDetection (dg_EnableFSKDetection) EnableGSMThread (dg_EnableGSMThread) EnableInputBuffer (dg_EnableInputBuffer) EnableISDNThread (dg_EnableISDNThread) EnableMailBoxDetection (dg_EnableMailBoxDetection) EnablePulseDetection (dg_EnablePulseDetection)


5

Contedo

230. 232. 234. 235. 237. 238. 239. 243. 245. 246. 247. 248. 249. 250. 251. 252. 253. 255. 256. 258. 259. 260. 261. 262. 264. 265. 267. 268. 269. 270. 271. 272. 273. 274. 277. 278. 279.

EnableSilenceDetection (dg_EnableSilenceDetection) Flash (dg_Flash) ForceSingleSpan (dg_ForceSingleSpan) GenerateMF (dg_GenerateMF) GetAbsolutePortNumber (dg_GetAbsolutePortNumber) GetAlarmStatus (dg_GetAlarmStatus) GetBusyCause (dg_GetBusyCause) GetCallerID (dg_GetCallerID) GetCardBus (dg_GetCardBus) GetCardInfo (dg_GetCardInfo) GetCardInterface (dg_GetCardInterface) GetCardNumber (dg_GetCardNumber) GetCardPortsCount (dg_GetCardPortsCount) GetCardsCount (dg_GetCardsCount) GetCardSlot (dg_GetCardSlot) GetCardType (dg_GetCardType) GetDigits (dg_GetDigits) GetDriverEnabled (dg_GetDriverEnabled) GetE1Number (dg_GetE1Number) GetE1ThreadStatus (dg_GetE1ThreadStatus) GetISDNThreadStatus (dg_GetISDNThreadStatus) GetLibVersion (dg_GetLibVersion) GetLoggerCallType (dg_GetLoggerCallType) GetNameID (dg_GetNameID) GetPlayFormat (dg_GetPlayFormat) GetPortCardType (dg_GetPortCardType) GetPortInterface (dg_GetPortInterface) GetPortsCount (dg_GetPortsCount) GetPortStatus (dg_GetPortStatus) GetRecordFormat (dg_GetRecordFormat) GetRelativeChannelNumber (dg_getRelativeChannelNumber) GetText (dg_GetText) GetVersion (dg_GetVersion) GSMCallControl (dg_GSMCallControl) GSMCheckSignalQuality (dg_GSMCheckSignalQuality ) GSMClearAllSMS (dg_GSMClearAllSMS) GSMDeleteSMS (dg_GSMDeleteSMS)


6

Contedo

280. 281. 282. 283. 284. 285. 286. 287. 288. 289. 290. 291. 292. 294. 296. 297. 298. 299. 300. 301. 303. 304. 305. 306. 307. 308. 309. 310. 311. 312. 314. 315. 317. 319. 320. 321. 322.

GSMGetIndexList (dg_GSMGetIndexList) GSMGetLastCommand (dg_GSMGetLastCommand) GSMGetMemory (dg_GSMGetMemory) GSMGetMessage (dg_GSMGetMessage) GSMGetSignalQuality (dg_GSMGetSignalQuality) GSMGetSMS (dg_GSMGetSMS) GSMGetSMSConfirmation (dg_GSMGetSMSConfirmation) GSMListSMS (dg_GSMListSMS) GsmRawToWave (dg_GsmRawToWave) GsmRawToWave49 (dg_GsmRawToWave49) GSMReadAndDeleteSMS (dg_GSMReadAndDeleteSMS) GSMRestartPort (dg_GSMRestartPort) GSMSendCommand (dg_GSMSendCommand) GSMSendSMS (dg_GSMSendSMS) GSMSetPinNumber (dg_GSMSetPinNumber) GsmToWave (dg_GsmToWave) GsmToWave49 (dg_GsmToWave49) HangUp (dg_HangUp) IdleAbort (dg_IdleAbort) IdleSettings (dg_IdleSettings) IdleStart (dg_IdleStart) IsCallInProgress IsPlaying (dg_IsPlaying) IsRecording (dg_IsRecording) LocalBridgeConnect (dg_LocalBridgeConnect) LocalBridgeDisconnect (dg_LocalBridgeDisconnect) MakeCall MenuAbort MenuErrorSettings MenuStart PauseInputBuffer (dg_PauseInputBuffer) PickUp (dg_PickUp) PlayBuffer (dg_PlayBuffer) PlayCardinal PlayCurrency PlayDate PlayFile (dg_PlayFile)


7

Contedo

324. 325. 326. 327. 328. 329. 330. 331. 332. 333. 335. 336. 337. 338. 339. 341. 342. 344. 345. 346. 347. 348. 350. 352. 354. 355. 357. 358. 359. 360. 361. 363. 365. 366. 367. 368. 369.

PlayList PlayListAdd PlayListClear PlayListGetCount PlayListRemoveItem PlayNumber PlayTime PromptAbort PromptSettings PromptStart R2AskForGroupII (dg_R2AskForGroupII) R2AskForID (dg_R2AskForId) R2SendGroupB (dg_SendGroupB) ReadDigits (dg_ReadDigits) RecordFile (dg_RecordFile) RecordPause (dg_RecordPause) ResetError (dg_ResetError) ResetPortResource (dg_ResetPortResource) ReturnCodeGSMToString (dg_ReturnCodeGSMToString) ReturnCodeToString (dg_ReturnCodeToString) ReturnCodeToStringCauseBusy (dg_ReturnCodeToStringCauseBus SendISDNCommand (dg_SendISDNCommand) SendR2Command (dg_SendR2Command) SetAlarmMode (dg_SetAlarmMode) SetAudioInputCallback (dg_SetAudioInputCallback) SetBearerCapability (dg_SetBearerCapability) SetCallAfterAnswer SetCallAfterPickup SetCallBusyPhrase SetCallBusyReturnFlash SetCalledNumber (dg_SetCalledNumber) SetCallingNumber (dg_SetCallingNumber) SetCallFlashTime SetCallNoAnswerPhrase SetCallNoAnswerReturnFlash SetCallNoAnswerRingCount SetCallPauseBeforeAnalysis


8

Contedo

370. 371. 372. 374. 376. 378. 380. 382. 384. 385. 386. 388. 390. 392. 394. 395. 396. 398. 400. 401. 403. 405. 407. 409. 410. 412. 413. 414. 416. 418. 419. 421. 422. 424. 425. 426. 427.

SetCallStartFlash SetCallWaitForDialTone SetCardDetections (dg_SetCardDetections) SetCardSyncMode (dg_SetCardSyncMode) SetDetectionType (dg_SetDetectionType) SetDialDelays (dg_SetDialDelays) SetDigitFrequency(dg_SetDigitFrequency) SetDigitGain(dg_SetDigitGain) SetDTMFConfig (dg_SetDTMFConfig) SetE1CRC4Option (dg_SetE1CRC4Option) SetFastDetection (dg_SetFastDetection) SetFaxFrequencies (dg_SetFaxFrequencies) SetFramerLoop (dg_SetFramerLoop) SetFrequency (dg_SetFrequency) SetFXCardType (dg_SetFXCardType) SetGSMMode (dg_SetGSMMode) SetHangUpCause (dg_SetHangUpCause) SetLoggerSilenceThreshold (dg_SetLoggerSilenceThreshold) SetNameID (dg_SetNameID) SetNextE1RxCount (dg_SetNextE1RxCount) SetPlayFormat (dg_SetPlayFormat) SetPortChatLog(dg_SetPortChatLog) SetPortGain (dg_SetPortGain) SetPortID (dg_SetPortID) SetRecordFormat (dg_SetRecordFormat) SetReverseCharging (dg_SetReverseCharging) SetRecordGain (dg_SetRecordGain) SetSilenceThreshold (dg_SetSilenceThreshold) SetStartE1RxCount (dg_SetStartE1RxCount) SetText (dg_SetText) SetTwist (dg_SetTwist) ShutdownVoicerLib (dg_ShutdownVoicerLib) StartVoicerLib (dg_StartVoicerLib) StopPlayBuffer (dg_StopPlayBuffer) StopPlayFile (dg_StopPlayFile) StopRecordFile (dg_StopRecordFile) TxRxMixEnable (dg_TxRxMixEnable)


9

Contedo

428. 429. 430. 431. 432. 433. 434. 435. 436. 437. 438. 439. 440. 441. 442. 443. 444. 445. 446. 447. 448. 449. 450. 451. 453. 454. 455. 456. 457. 458. 459. 460. 461. 462. 463. 464.

Wave49ToGsm (dg_Wave49ToGsm) Wave49ToGsmRaw (dg_Wave49ToGsmRaw) WaveToGsm (dg_WaveToGsm) WaveToGsmRaw (dg_WaveToGsmRaw) WriteCode (dg_WriteCode) Eventos OnAfterDial (EV_AFTERDIAL) OnAfterFlash (EV_AFTERFLASH) OnAfterMakeCall OnAfterPickUp (EV_AFTERPICKUP) OnAnswerDetected (EV_ANSWERED) OnAudioSignalDetected (EV_AUDIO_SIGNAL) OnBusyDetected (EV_BUSY) OnCallerID (EV_CALLERID) OnCalling (EV_CALLING) OnCallStateChange OnChannel (EV_CHANNEL) OnDialToneDetected (EV_DIALTONE) OnDigitDetected (EV_DTMF) OnDigitsReceived (EV_DIGITSRECEIVED) OnE1Alarm (EV_E1_ALARM) OnE1FramerResponse (EV_FRAMER) OnE1GroupB (EV_GROUP_B) OnE1StateChange (EV_E1CHANGESTATUS) OnErrorDetected (EV_ERRORDETECTED) OnErrorNodeConfig (EV_ERROR_NODE_CONFIG) OnFaxDetected (EV_FAX) OnGSMSMSConfirmation (EV_GSMSMSCONFIRMATION) OnGSMError (EV_GSMERROR) OnGSMMemory (EV_GSMMEMORY) OnGSMMemoryFull (EV_GSMMEMORYFULL) OnGSMMessage (EV_GSMMESSAGE) OnGSMOtherCall (EV_GSMOTHERCALL) OnGSMReady (EV_GSMREADY) OnGSMReturnOK (EV_GSMRETURNOK) OnGSMSIM (EV_GSMSIM)


10

Contedo

465. 466. 467. 468. 469. 470. 471. 472. 473. 474. 475. 476. 477. 478. 479. 480. 481. 482. 483. 484. 485. 486. 486. 487.

OnGSMSignalQuality (EV_GSMSIGNALQUALITY) OnGSMSMSReceived (EV_GSMSMSRECEIVED) OnGSMSMSSent (EV_GSMSMSSENT) OnGSMTimeout (EV_GSMTIMEOUT) OnLineOff (EV_LINEOFF) OnLineReady (EV_LINEREADY) OnLoggerEvent (EV_LOGGEREVENT) OnMailBoxDetected(EV_MBDETECTED) OnMenu OnNameID (EV_NAMEID) OnPlayStart (EV_PLAYSTART) OnPlayStop (EV_PLAYSTOP) OnPrompt OnR2Received (EV_R2) OnRecording (EV_RECORDING) OnRecordStart (EV_RECORDSTART) OnRecordStop (EV_RECORDSTOP) OnReverseCharging (EV_REVERSECHARGING) OnRingDetected (EV_RINGS) OnSilenceDetected (EV_SILENCE) OnText (EV_TEXT) Propriedades exclusivas do ActiveX ConfigPath StockSigPath


11

Introduo

Bem vindo ao Guia do Programador da VoicerLib 4! A VoicerLib 4 a verso da VoicerLib para a famlia de placas DigiVoice tanto para Windows como para Linux. As placas suportadas so: Todos os modelos de placas digitais E1 Placa FXO de 4 ou 8 canais Placa GSM 2 ou 4 canais Placa FXS

As placas VoicerBox PCI/1 e VoicerPhone PCI/4 no so suportadas por esta verso da VoicerLib. Para estes modelos deve ser utilizada a VoicerLib 2.x para Windows e a VoicerLib 3.1.x para Linux.


12

Recursos para o Desenvolvedor

Ao adquirir as placas DigiVoice e a VoicerLib, o desenvolvedor pode fazer download de uma coleo de exemplos prontos em nosso site www.digivoice.com.br com o objetivo de explicar o funcionamento das diversas funes da VoicerLib. Alm disso, o desenvolvedor tem disponvel a rea de suporte do site da DigiVoice na internet, atravs do endereo http://www.digivoice.com.br/suporte. L, esto disponveis o Frum de Discusses, Arquivos para Download (exemplos atualizados, instaladores, manuais etc..), Documentos Tcnicos e uma seo de Perguntas Frequentes para ajudar o desenvolvedor nas dvidas mais comuns. muito importante tambm ler com ateno toda a seo Guia de Programao deste manual pois contm toda a base necessria para programar com as placas DigiVoice, importante para novatos ou para desenvolvedores que j trabalharam com outros hardwares.


13

Primeiros Passos

Neste captulo ser discutido os passos necessrios para instalar a VoicerLib e executar os primeiros procedimentos para verificar se tudo est funcionando corretamente.

Windows32/64 bits

Utilizando a VoicerLib em Windows 32 bits e 64 bits O sistema operacional Windows oferecido em verses para 32 e 64 bits, a VoicerLib, a partir da verso 4.3.0.0, est disponvel para rodar em 32 bits e 64 bits. Apesar do Windows permitir que aplicaes de 32 bits rodem em sistemas operacionais de 64 bits a VoicerLib no tem esta opo porque a VoicerLib interage diretamente com o hardware atravs dos drivers das placas e a comunicao tem que ser de 64 bits para 64 bits, ou seja, para um Windows de 64 bits s ser instalada a verso de 64 bits. Compatibilidade A partir da verso 4.3.0.0 da VoicerLib, muitas alteraes internas foram feitas no sentido de adapt-la ao Windows 64 bits e a otimizaes visando maior desempenho, mas o desenvolvimento de aplicativos manteve-se totalmente compatvel com as verses anteriores. Programas de teste A VoicerLib fornecida com alguns programas de teste para suas placas FXO, FXS, E1 e GSM. Estes programas foram compilados para 32 bits e 64 bits. Como estes programas foram desenvolvidos com uma ferramenta Microsoft que utiliza a


14

Primeiros PassosWindowstecnologia .NET, necessrio que um pacote Microsoft .NET Framework esteja instalado no computador onde a VoicerLib for instalada para que os programas de testes rodem. No setup de instalao da VoicerLib (no final da instalao) h a opo de instalar o Microsoft .NET Framework v.2.0. Se o computador j possuir um framework instalado, no necessrio instalar o framework do setup da VoicerLib. A VoicerLib no depende do Microsoft .NET Framework para ser utilizada, somente os programas de teste. Visual Studio Por enquanto, o Visual Studio da Microsoft (2008 e 2010), como a maioria dos programas atuais, uma aplicao de 32 bits que permite o desenvolvimento de aplicaes de 64 bits. Isto tem uma implicao na importao de componentes OCX como a VoicerLib e desenvolvimento de aplicativos de 64 bits. Quando uma aplicao de 32 bits roda no Windows de 64 bits, o sistema operacional roda a aplicao utilizando a interface WOW64, que "Windows on Windows 64", ou se for instalado um componente ou dll 32 bits no Windows 64, estes componente sero instalados na pasta "sysWOW64" ao invs da pasta "system32" (padro do Windows). Mesmo sendo meio confuso, a Microsoft optou por manter o nome system32 para a pasta de instalao dos componentes ou dll de 64 bits em um Windows de 64 bits. Ao se desenvolver uma aplicao que exija um componente OCX de 64 bits, como a VoicerLib, ser necessrio instalar uma OCX de 32 bits para o desenvolvimento de aplicativos, mesmo com a opo de compilao para gerar executveis de 64 bits. Ao ser instalada, a Voicerlib coloca uma OCX de 32 bits na pasta "sysWOW64" e uma de 64 bits na pasta "system32", mas o componente a ser importado no Visual Studio tem que ser o de 32 bits da pasta "sysWOW64".


15

Primeiros PassosWindows Instalao no WindowsRequisitos mnimos de instalao: Windows XP/2000/2003 Processador Core 2 Duo 1 GB de memria Sistemas Operacionais suportados (32 bits e 64 bits): Windows Windows Windows Windows Windows XP Professional SP1/SP2/SP3 2003 Server Vista Business 2008 Server 7

Quantidade mxima de placas por computador : 10 placas Programa de instalao da VoicerLib4: setup_vlib.exe - Programa de instalao para o desenvolvedor, contendo os drivers e a documentao. A instalao fsica das placas DigiVoice explicada pelo manual Kit Integrador que fornecido impresso acompanhando o hardware. Quanto instalao do software leia os tpicos a seguir deste manual. Se voc j instalou fisicamente a placa, o Windows a reconhecer na primeira inicializao. Se voc no instalou o software ainda, simplesmente cancele a tela que o Windows mostrar. Em seguida, localize e execute o arquivo de instalao da voicerib chamado setup_vlib.exe (que est no CD adquirido ou no site da Digivoice). Aps seguir os passos indicados, reinicie o computador quando isso for solicitado pelo programa de instalao. Ao reiniciar, o Windows mostrar novamente que detectou um novo hardware (Controlador Multimedia). Desta vez, siga os


16

Primeiros PassosWindowspassos para instalao do hardware. O Windows perguntar se voc quer instalar automaticamente ou a partir de um caminho especfico. Escolha a segunda opo, apontando para o diretrio escolhido na instalao, o caminho padro \%PROGRAM FILES%\VoicerLib4. Isto dever ser suficiente para que o Windows reconhea a placa, como por exemplo "Digivoice VB3030PCIE". Se tudo estiver correto, a placa estar pronta para ser utilizada. Caso tenha alguma dvida, acesse o Gerenciador de Dispositivos do Windows, que dever apresentar um novo item Digivoice:

Gerenciador de dispositivos - Dispositivos por tipo

O programa de instalao criar o grupo de programas em seu menu Iniciar, com o nome Digivoice VoicerLib4 contendo: Configurador da placa E1 - Programa de configurao e testes Programa para placa GSM - Exemplo de funcionalidade da placa


17

Primeiros PassosWindowsGSM Programa de diagnsticos Vlib_Diag 0408 - Programa de testes para a placa VB0408 Programa de diagnsticos Vlib_Diag 0404FX - Programa de testes para a placa VB0404FX Monitor de Sinalizao R2MFC (E1) Manual do Kit Integrador Link para o site da DigiVoice Atalho para remover a instalao

Em nosso site www.digivoice.com.br esto disponveis diversos exemplos e o manual do programador.

Caso a instalao seja feita em um computador de sistema operacional Vista/W2008/W7 ou superior, e por algum motivo esta placa sejam reinstalada em uma mquina XP/2000/2003, necessrio executar um arquivo chamado VlibUpdateRetro.exe, que est no diretrio: \%PROGRAM FILES%\VoicerLib4\VlibUpdateRetro\. Execute o arquivo e se ocorrer algum erro, aparecer na tela e ser necessrio apertar alguma tecla para continuar, nesse caso, entre em contato com a Digivoice e nos informe a mensagem de erro, caso execute com sucesso apenas uma tela de atualizao aparecer rapidamente, obrigatrio a reinicializao do computador.


18

Primeiros PassosWindows Testando a placa instaladaNesse tpico iremos mostrar o teste passo a passo de uma placa E1. Placa E1 Para verificar se a placa E1 foi corretamente instalada e est operacional, execute o programa Configurador da placa E1 que est no menu Iniciar do Windows, sob o grupo Digivoice VoicerLib4. A seguinte tela aparecer:

Tela do configurador E1

A primeira ao a fazer clicar sobre a opo Detectar Placas, no menu apresentado na parte inferior esquerda da janela. O Configurador iniciar a deteco e inicializao das placas.


19

Primeiros PassosWindowsCom isso, possvel ter certeza que as placas foram corretamente instaladas e esto operacionais.

LinuxInstalao no LinuxRequisitos mnimos de instalao: Celeron 1 Ghz com 256Mb de memria Distribuio Linux com kernel verso 2.4.x. ou 2.6.x Quantidade mxima de placas por computador : 7 placas O arquivo que contm todo o material necessrio chama-se voicerlib-4.x.x.tar.gz (4.x.x ser a verso corrente) sendo que para descompact-lo, utilize o comando: tar xvzf voicerlib-4.x.x.x.tar.gz Com isso, o diretrio voicerlib-4.x.x.x ser criado contendo os fontes da voicerlib e do device driver.

- voicerlib-4.x.x.x Contm os arquivos relativos API | |___/driver/linux | |__ Device driver para as placas DigiVoice. | |___/firmware | |__ Arquivos dos firmwares das placas e outros de configurao (CallProgress, etc...) | |___/samples/dll_so | |__ c - programa exemplo/teste desenvolvido em ANSI C | |___/src_common


20

Primeiros PassosLinux| |__ Cdigo-fonte da VoicerLib - arquivos comuns (multiplataforma) | ||___/src_linux | |__ Cdigo-fonte da VoicerLib (shared object) para Linux |

Para trabalhar com o Asterisk, necessrio tambm baixar e instalar o dgvchannel - channel driver para Asterisk. Acesse o site http://www.digivoice.com.br.


21

Primeiros PassosLinux Preparando o ambientePara estar apto a compilar a VoicerLib no seu ambiente ser necessrio que esteja disponvel um sistema de desenvolvimento (gcc, make, etc...) bem como os fontes do kernel. Todos estes arquivos normalmente encontram-se disponveis no CD original de sua distribuio. A VoicerLib foi desenvolvida e testada em verses 2.4 e 2.6 do kernel, utilizando o compilador gcc verso 3.0.1 ou superior (a verso 2.95 do gcc causar diversos erros de compilao). O gcc 4 tambm tem sido utilizado sem problemas. Para compilar o exemplo em C, ser necessrio a biblioteca ncurses-devel verso 5.3 ou superior. A maioria dos passos necessrios para colocao da VoicerLib e aplicativos para funcionar precisam ser executados com o usurio root, portanto todo o cuidado necessrio para no danificar o seu sistema. Lembramos que, em ambiente de produo, no necessrio que o usurio tenha direitos de administrador (alis o contrrio e recomendado). A partir da verso 4.0.5, possvel compilar e instalar todos as bibliotecas, drivers e aplicativos atravs do comando: make; make install; make config a partir do diretrio raiz.

Aps a execuo destes comandos, o ambiente j estar pronto para operar. Um teste de verificao til a execuo do programa vlib_diag que encontra-se no diretorio ../samples/dll_so. Nos prximos itens deste captulo ser explicado a compilao e instalao de cada mdulo separadamente, porm a sua execuo s ser necessria caso haja algum problema no passo que acabou de ser explicado.


22

Primeiros PassosLinux Mdulos do kernelOs mdulos ou device drivers so os responsveis em criar e gerenciar a troca de dados entre o hardware e os aplicativos. Caso eles no estejam funcionando corretamente, nada mais funcionar. No sub-diretrio ../driver/linux encontram-se todos os arquivos necessrios para compilar e instalar os mdulos. O mesmo device driver responsvel por gerenciar todos os modelos de placas. Para compilar o mdulo desejado, voc precisa executar os seguintes comandos: make: compila o mdulo make install: instala o mdulo no diretrio correto e carreg-lo na memria make config: instala o mdulo na inicializao do sistema testado em Debian, Suse, RedHat e derivaes.

Aps a compilao (make) dever ser gerado o arquivo vlibd.o ou vlibd.ko Para carregar o mdulo na memria manualmente depois de reiniciar (se no tiver sido executado o make config), execute novamente o make install. Para verificar se o mdulo foi instalado corretamente, digite em linha de comando 'dmesg'. Este programa exibe informaes dos device drivers instalados. Se tudo estiver correto, voc ver uma mensagem como a apresentada a seguir: vlibd: VoicerLib Device Driver was loaded successfully! Se a mensagem exibida for diferente, aparentando algum tipo de erro, verifique e repita os passos anteriores ou mesmo se a placa


23

Primeiros PassosLinuxest fisicamente instalada.

Usurios RED HAT 3.2 AS/ES ou CentOS-3, para compilar o mdulo executem: make RH3=1. Os outros procedimentos no so alterados.


24

Primeiros PassosLinux Compilando a VoicerLibComo a VoicerLib multiplataforma, existem diretrios especficos para plataforma Linux e Windows. Para compilar a VoicerLib para Linux, v para o diretrio ../src_linux e execute os seguintes comandos: make make install

O comando make install copiar o arquivo resultante (libdigivoice.so.4.x.x.x) para o diretrio /usr/lib e o tornar disponvel para todas as ferramentas de desenvolvimento como uma shared object. Tambm copia os headers (*.h) para o diretrio padro /usr/include/voicerlib permitindo o uso da voicerlib por outros aplicativos. Os arquivos de configurao e firmware so instalados em /var/lib/voicerlib. Todos os aplicativos de teste iro buscar os arquivos de firmware neste diretrio como padro. O funcionamento da VoicerLib ser tratado no captulo Guia de Programao e seus comandos esto listados no captulo Guia de Referncia.


25

Primeiros PassosLinux Exemplo em linguagem CO programa no diretrio ../samples/dll_so/c chama-se vlib_diag. Trata-se de um programa em modo caracter (console) que permite interagir com as placas DigiVoice. a melhor forma de testar o funcionamento da placa bem como estudar o funcionamento da API. Este projeto necessita da biblioteca ncurses-devel com verso maior ou igual a 5.3. Para compilar, digite make. Ao executar ./vlib_diag voc poder efetuar diversos testes com as placas E1, FXO, FXS e GSM.


26

Guia de Programao

A VoicerLib 4 pode ser utilizada tanto no ambiente Windows como no Linux, sendo que existem semelhanas e algumas diferenas no modo de funcionamento da biblioteca nas duas plataformas. Semelhanas A VoicerLib tem uma camada de funes primitivas que foram implementadas na forma de uma API em C. Em Linux, utiliza-se Shared Objects e em Windows DLLs para interfacear com as aplicaes. Desta forma, apesar de ter sido construda em C, a VoicerLib API permite sua utilizao em qualquer ferramenta de desenvolvimento que tenha acesso DLLs ou SOs. Para isso, necessrio que os headers da VoicerLib API sejam traduzidos de C para a linguagem desejada. Na camada de API, a VoicerLib fornece todos os mtodos primitivos de acesso aos recursos da placa. Entenda por mtodos primitivos, todas as funes que no se enquadram na classe de funes especiais, discutidas mais adiante.

Diferenas A DigiVoice fornece, somente para ambiente Windows, um ActiveX chamado VoicerLib.OCX, que tem por objetivo facilitar a programao. Nesse conjunto, esto includas todas as funes primitivas e especiais (MakeCall, PlayList, etc...). A seguir sero mostrados os conceitos especficos de cada modo de programao. Mais a frente no manual, os conceitos diversos sero explicados independente do uso da API ou do ActiveX, sempre sendo feito meno dos mtodos e/ou funes utilizadas em cada modo. Se voc programa em Linux ou pretende programar em C para Windows acessando as funes primitivas, leia somente as descries de Conceitos Bsicos - API. Caso a plataforma utilizada seja Visual Basic, Delphi, etc... recomenda-se a utilizao do ActiveX, por isso leia as descries de Conceitos Bsicos - ActiveX.


27

Guia de Programao

Para facilitar a documentao, as explicaes das funes API e ActiveX so feitas conjuntamente, sempre colocando a funo API e o mtodo ActiveX entre parnteses, salvo situaes em que as diferenas so explcitas.

Conceitos Bsicos - APIPara os desenvolvedores acostumados com a VoicerLib em Windows, os conceitos predominantes so as propriedades, eventos e mtodos, comuns linguagem orientada a eventos como o Visual Basic. Como a VoicerLib API foi desenvolvida para ser um Shared Object (Linux) e uma DLL (Windows), o funcionamento um pouco diferente. Numa traduo simplificada, as propriedades e mtodos sero acessados atravs de funes comuns com nome e parametrizao similar verso em Windows (ex.: o mtodo PickUp tornou-se a funo dg_pickup). Todas as funes da VoicerLib API comeam com "dg_" para evitar conflitos de nomes com outras bibliotecas dinmicas que por ventura existam no ambiente. Os eventos existentes no ActiveX em Windows so chamados pela VoicerLib de forma transparente, bastando ao programador associar uma funo a um determinado evento (ex.: OnRingDetected -> TrataRing). Em um shared-object os eventos continuam existindo, porm, a rotina que associa determinado evento (ou mensagem) a um bloco de cdigo (ou funo) passa a ser de responsabilidade do programador. Na prtica, necessrio criar uma funo que receba todos os eventos da placa. Esta funo ser chamada de Gerenciador de Eventos. Um "esqueleto" dessa funo mostrado a seguir:


28

Guia de ProgramaoConceitos Bsicos - APIvoid ReceiveEvents(void *context_data) { struct dg_event_data_strucuture *EventContext; /* Copy received Data */ EventContext = ((struct dg_event_data_strucuture*)context_data); switch (EventContext->command) { case EV_RING: //recebeu ring //.... case EV_DTMF: //recebeu digito //... } } Mesmo conhecendo pouco a linguagem C, fcil de perceber que o Gerenciador de Eventos recebe um parmetro chamado context_data. Neste parmetro estaro as informaes pertinentes a cada evento (porta, dgito, etc...). Caber ao programador analisar o contedo de context_data->command para saber qual evento ocorreu. A varivel context_data->port indica a porta que ocorreu o evento e a varivel context_data>data fornece um dado relativo ao evento (alguns eventos no possuem dados associados). Context_data definido como: struct dg_event_data_strucuture *context_data;

Sendo que dg_event_data_strucuture est definido no arquivo voicerlib.h conforme segue: typedef struct { unsigned short command; unsigned short data; unsigned short port; unsigned short data_aux; unsigned short card; } dg_event_data_structure;


29

Guia de ProgramaoConceitos Bsicos - APIUm primeiro conceito que j conhecido dos desenvolvedores Windows e que foi mantido na verso Linux que todo o funcionamento da VoicerLib assncrono. Isto significa que ao executar a chamada a uma determinada funo, o programa seguir seu fluxo normal. As respostas s funes so manipuladas atravs de uma funo eleita para tratar todas as mensagens, que no exemplo a ReceiveEvents. Por exemplo, quando a funo dg_GetDigits chamada, o programa continua normalmente e s aps os dgitos serem recebidos (ou der time-out) a VoicerLib chamar a funo ReceiveEvents passando no context_data a mensagem EV_DIGITSRECEIVED e o status de retorno da funo. Este tipo de funcionamento muito importante pois a biblioteca tem que gerenciar vrias portas simultaneamente. Se a aplicao ficasse presa na execuo de uma funo, no conseguiria tratar os outros eventos das outras placas, por isso o tratamento de determinada mensagem dentro do switch-case deve ser o mais rpido possvel. A funo ReceiveEvents na verdade pode ter qualquer nome mas sempre dever receber o endereo da estrutura context_data, independente da linguagem de programao utilizada. No incio do programa, antes de iniciar a placa com o mtodo dg_StartVoicerLib, obrigatrio associar a funo de tratamento de mensagens VoicerLib atravs da funo dg_SetEventCallback. Se a associao no for feita corretamente, o programa gerar falhas de execuo (Segmentation Fault). Ento, um esqueleto de programa utilizando a VoicerLib API dever ter a seguinte caracterstica: void ReceiveEvents(void *context_data) { //Tratamento de todos os eventos vindos da placa } void main() //Inicio do programa {


30

Guia de ProgramaoConceitos Bsicos - API//Primeiro associa a funo callback dg_SetEventCallback(ReceivedEvents,&event_context ); //Inicia a voicerlib dg_StartVoicerLib("../../firmware"); } void finaliza() { //Finaliza o driver dg_ShutdownVoicerlib(); } Consulte o Guia de Referncia VoicerLib API a respeito de todas as funes disponveis.

As placas E1 tm um comportamento diferente em relao vrios tpicos abordados neste captulo, porm, a DigiVoice procurou deixar a manipulao destas caractersticas da maneira mais similar s placas FXO, visando minimizar o tempo de aprendizado. A leitura do tpico Programao da Placa E1 de extrema importncia para a compreenso destas diferenas e do modo de operao a serem utilizados.


31

Guia de ProgramaoConceitos Bsicos - ActiveX

Conceitos Bsicos - ActiveXO componente VoicerLib baseado na estrutura de um looping infinito, que fica monitorando os eventos que acontecem no hardware (ring, tons, etc...) e recebendo e passando os comandos gerados a partir da aplicao (propriedades e mtodos). Devido a esta caracterstica, a maioria das funes da biblioteca so assncronas. Isto significa que ao executar a chamada a um determinado mtodo, o programa seguir seu fluxo normal. As respostas aos mtodos so manipuladas atravs de eventos especficos relativos a cada acontecimento. Por exemplo, quando o mtodo GetDigits chamado, o programa continua normalmente e s aps os dgitos serem recebidos (ou der time-out) que a resposta ao GetDigits ser tratada dentro do evento OnDigitsReceived Este tipo de funcionamento muito importante pois a biblioteca tem que gerenciar vrias portas simultaneamente. Se a aplicao ficasse presa na execuo de um mtodo, no conseguiria tratar os outros eventos das outras portas. Lembre-se que possvel que uma porta esteja reproduzindo a mensagem enquanto outra esteja recebendo um ring. Observaes importantes para reinstalar a OCX da VoicerLib Quando a verso da voicerlib for atualizada, necessrio que a aplicao seja recompilada. Em Delphi7: Apague os arquivos de nome "VoicerLib_TLB" no diretrio "\%PROGRAM FILES%\Borland\Delphi7\Imports", importe novamente a OCX no Delphi7: Component -> Import ActiveX -> Localize Digivoice VoicerLib ActiveX -> clique em Install... Em Visual Basic 6: No VB6 -> boto direito na barra lateral


32

Guia de ProgramaoConceitos Bsicos - ActiveXGeneral->Components->Controls-> Selecione Digivoice->Browse -> \windows\system32\voicerlib.ocx -> Aplicar ->OK .

Guia de Migrao de Verses AnterioresApesar de ter como objetivo manter a biblioteca o mais compatvel possvel com as verses anteriores, algumas alteraes nos fontes sero necessrias para atualizar aplicaes para a nova verso, principalmente devido s novas tecnologias empregadas nas placas FXO e E1. Essas alteraes fizeram com que novos mtodos fossem criados, outros fossem excludos e alguns outros tiveram alteraes nos parmetros que recebem e enviam. Recomendamos a leitura deste captulo antes de efetuar a adaptao de sistemas desenvolvidos com verses anteriores da VoicerLib.

1. Mtodos/Propriedades removidas SetAnswerSensitivity Agora um parmetro do mtodo ConfigCallProgress (Maiores detalhes no captulo Superviso de Linha). SetAnswerThreshold - Esse tipo de configurao no mais necessria (veja tambm SetSilenceThreshold). SetVolume - Sem funo nas novas placas - exclusivo para placa de 1 canal com headset. SetImpedance - Sem funo nas novas placas - exclusivo para placa de 1 canal com headset. SetDTMFAttenuatingHigh/Low - A configurao de ganho de dgitos mais ampla e feita pelo mtodo SetDigitGain. SetDTMFTwist/SetToneTwist - Devido aos novos algortmos no mais necessria a configurao de twists. Propriedade CardType - Como agora permitida a mistura de placas diferentes, no possvel utilizar uma propriedade para atribuir ou ler o tipo de placa.


33

Guia de ProgramaoGuia de Migrao de Verses Anteriores SetFrequencyTime - Agora um parmetro do mtodo ConfigCallProgress (Maiores detalhes no tpico Superviso de Linha). AutoClearDigits - A propriedade foi retirada por causar certa confuso no funcionamento dos mtodos que detectavam dgito. Agora o programador dever sempre apagar explicitamente os dgitos com o mtodo ClearDigits, sempre que for necessrio. Formato ffSig - Est sendo removido gradualmente por ser idntico em tamanho ao ffWaveULaw ou ffWaveALaw. Para manter a compatibilidade, ao escolher este formato, ser utilizado no lugar o ffWaveULaw. Propriedades DelayDot, DelayComma e DelaySemicolon Foram removidas, agora necessrio utilizar o mtodo SetDialDelays. ReadEEPROM - Foi removida e ao invs dela, foi criado um mtodo CheckCode.

2. Mudanas de nome e/ou parmetros SetFastDetection - Agora para setar o modo rpido, preciso chamar este mtodo (o parmetro enable pode receber os valores DG_ENABLE /DG_DISABLE). EnableDetections - Mudou para SetDetectionType, agora a voicerlib no detecta nenhum tipo como padro. O programador deve chamar explicitamente este mtodo sempre quando for necessrio. Os mtodos de deteco mudaram bastante portanto leia atentamente o guia de referncia sobre este mtodo. Evento OnAswerDetected - Recebe um novo parmetro chamado AnswerType, indicando se o atendimento foi por deteco de udio (AUDIO_DETECTED) ou timeout (TIMEOUT_DETECTED). SetCardSyncMode para placas E1 - Para setar o sincronismo deve ser chamado o SetCardSyncMode passando como parmetros a placa e o tipo de sincronismo SYNC_INTERNAL, SYNC_LINE_A, SYNC_LINE_B. dg_StartVoicerLib - Na DLL e no SO s tem o path como parmetro (Isso no aplicado ao ActiveX) e agora retorna DG_EXIT_SUCCESS (0) no caso de sucesso e no mais 99.


34

Guia de ProgramaoGuia de Migrao de Verses Anteriores PlayBuffer - Parmetro remaining_size incluso no Active X. WriteEEPROM - Foi renomeada para WriteCode. ConfigGSMThread - O segundo parmetro possui mais possibilidades de configurao: GSMCFG_USSD_ENABLE, GSMCFG_CALL_WAITING_ENABLE, GSMCFG_RETRY_TIMEOUT e GSMCFG_ANSWER_TIMEOUT. Consulte o mtodo ConfigGSMThread. GSMClearAllGSM - Incluso segundo parmetro que indica se todas as mensagens do mdulo sero ou no apagadas. Consulte o mtodo GSMClearAllSMS. ALARM_RESERVED - A constante foi renomeada para ALARM_CRC4SYNC. Verifique em OnE1Alarm. EnableMailBoxDetection - Incluso novo parmetro silencetime. OnE1Alarm - Quando o protocolo for ISDN PRI, h mais um tipo de alarme ALARM_LINK (OnE1Alarm).

3. Novas funes/eventos Evento OnAudioSignal - Indicando para a aplicao o tipo de udio detectado. til para anlises de tipos de tom e suas cadncias. Funes de canais virtuais - Permitindo utilizar a numerao de portas independentemente da posio fsica da porta na placa. DefinePortResource Associa uma determinada porta (lgica) a uma placa/porta fsica. ResetPortResource Reseta a configurao, assumindo o padro de inicializao das funes de callprogress - O CallProgress agora mais completo e verstil. Leia atentamente o captulo de Superviso de Linha - Funes relacionadas: CreateCallProgress, ConfigCallProgress, DestroyCallProgress e EnableCallProgress. EnableAnswerDetection/DisableAnswerDetection O mtodo para habilitar deve ser chamado explicitamente aps a chamada do EnableCallProgress, para que a thread de controle de callprogress gere o evento de atendimento. EnableInputBuffer/DisableInputBuffer Agora para efetuar a gravao de portas na voicerlib, necessrio habilitar o envio


35

Guia de ProgramaoGuia de Migrao de Verses Anterioresde amostras da placa atravs do mtodo EnableInputBuffer. Isso deve ser feito antes de chamar o RecordFile. Esta alterao foi feita para suportar streaming de udio das placas para as aplicaes diretamente. PlayBuffer / StopPlayBuffer - Envia amostras diretamente para a placa reproduzir. til para aplicaes VoIP. SetGSMMode - Pode assumir GSM_DIGIVOICE ou GSM_RAW (padro). Ambos os formatos tm a mesma codificao sendo que, no padro Digivoice inserido um cabealho no arquivo. GetPortCardType - Devolve o tipo de placa a partir da porta informada. Implementada funcionalidade de deteco de silncio, atravs dos mtodos EnableSilenceDetection/DisableSilenceDetection e do evento OnSilenceDetected. GsmToWave - Converte arquivo de udio do formato GSM para o formato Wave. GsmToWave49 - Converte arquivo de udio do formato GSM para o formato Wave (GSM 6.10 modificado). GsmRawToWave - Converte arquivo de udio do formato GSMRaw (sem cabealho) para o formato Wave. GsmRawToWave49 - Converte arquivo de udio do formato GSMRaw (sem cabealho) para o formato Wave49 (GSM 6.10 modificado). WaveToGsm - Converte arquivo de udio do formato Wave para o formato GSM. WaveToGsmRaw - Converte arquivo de udio do formato Wave para o formato GsmRaw (sem cabealho). Wave49ToGsm - Converte arquivo de udio do formato Wave49 para o formato GSM. Wave49ToGsmRaw - Converte arquivo de udio do formato Wave49 para o formato GSMRaw (sem cabealho). SetFXCardType - Permite configurar o tipo da porta (FXS/FXO) da placa VB0404FX. ReturnCodeToString - Retorna qual a mensagem de erro, a partir do cdigo de retorno. CheckCode - Compara a string de segurana da memria da placa com a string a ser gravada. SetLoggerSilenceThreshold - Permite setar o limiar de silncio para as portas da placa VB6060 no caso de aplicaes utilizando a thread de Logger.


36

Guia de ProgramaoGuia de Migrao de Verses Anteriores GSMCheckSignalQuality - Este comando fora o mdulo GSM correspondente a porta especificada, verificar o nvel de sinal recebido na antena. GSMGetMessage - Este comando obtm a mensagem SMS recebidas pelo mdulo. Mtodo usado para fins de debug. GSMGetSignalQuality - Recupera a string com o valor da qualidade do sinal aps o recebimento do evento OnGSMSignalQuality . GSMGetSMS - Permite ler uma mensagem SMS recebida. GSMSendCommand - Envia um comando ao mdulo GSM correspondente porta especificada. GSMSendSMS - Permite o envio de mensagem SMS nas portas correspondentes. GSMSetPinNumber - Ao ser iniciada a thread GSM a VoicerLib consulta os mdulos GSM sobre a necessidade ou no do envio de PIN number ou PUK. OnGSMError - Ocorre quando um erro detectado na porta ou na troca de sinalizao nos mdulos GSM. OnGSMMessage - Ocorre quando uma mensagem detectada pela placa. OnGSMReady - Ocorre quando a thread GSM foi criada e inicializada com sucesso. OnGSMSignalQuality - Ocorre em resposta ao mtodo GSMCheckSignalQuality, informa que o valor respectivo a qualidade do sinal j est disponvel. OnGSMSMSReceived - Ocorre quando uma mensagem SMS foi recebida e est disponvel para leitura atravs do mtodo GSMGetSMS. OnGSMSMSSent - Ocorre ao trmino do envio de uma mensagem SMS na porta especificada. OnGSMTimeout - Ocorre quando um comando enviado pela Voicerlib para o mdulo GSM correspondente a porta da placa VB0404GSM no obtm uma resposta no tempo especificado no mtodo ConfigGSMThread. GSMClearAllSMS - Este comando apaga todas as mensagens SMS do mdulo GSM correspondente a porta especificada. GSMDeleteSMS - Apaga a mensagem SMS do mdulo GSM. GSMListSMS - Solicita ao mdulo GSM a lista de mensagens GSM armazenadas em sua memria. GSMGetIndexList - Recupera a lista dos ndices das


37

Guia de ProgramaoGuia de Migrao de Verses Anterioresmensagens SMS do mdulo GSM. GSMReadAndDeleteSMS - Este comando l a mensagem SMS especificada pelo ndice e em seguida apaga a mensagem do mdulo GSM. GSMRestartPort - Este comando reinicia o mdulo especificado pela porta. OnGSMReturnOK - Evento gerado aps a execuo dos mtodos GSMListSMS (status GSM_LIST) e GSMClearAllSMS (status GSM_CLEAR). GSMCallControl - Este comando executa as funes de atendimento de segunda chamada e conferncia nos mdulos. OnGSMOtherCall - Quando o mdulo GSM j atendeu uma chamada e recebe uma "outra chamada" este evento gerado. GSMGetLastCommand - Este mtodo obtm o ltimo comando enviado para o mdulo. Deve ser chamado no evento OnGSMMessage. GSMGetMemory - Esse mtodo disponibiliza ao usurio a quantidade de mensagens SMS no mdulo GSM aps o recebimento do evento OnGSMMemory. OnGSMMemory - Ocorre em resposta ao mtodo GSMClearAllSMS, informa que a quantidade de mensagens armazenadas no mdulo GSM est disponvel para ser lida com o mtodo GSMGetMemory. OnGSMMemoryFull - gerado quando o mdulo GSM atinge sua capacidade mxima de mensagem. Utilize o mtodo GSMClearAllSMS para limpar as mensagens do mdulo. EnableFSKDetetection - Habilita deteco de identificao de assinante no padro FSK. GetNameID - Recupera o nome do assinante chamador quando diponvel no sistema FSK ou quando o protocolo for ISDN PRI. GetLibVersion - Informa o nmero de verso da OCX ou da DLL. CreateLoggerCCS - Inicia o tratamento automtico de gravao em paralelo para sinalizao ISDN PRI. DestroyLoggerCCS - Finaliza o tratamento automtico de gravao em paralelo para sinalizao ISDN PRI. ConnectAudioChannels - Efetua uma conexo bi-direcional entre duas portas de qualquer placa. DisconnectAudioChannels - Efetua uma desconexo de duas portas conectadas de qualquer placa.


38

Guia de ProgramaoGuia de Migrao de Verses Anteriores EnableMailBoxDetection - Habilita deteco de caixa postal (secretria eletrnica). DisableMailBoxDetection - Desabilita deteco de caixa postal (secretria eletrnica). OnMailBoxDetected - Evento gerado quando detecta caixa postal (secretria eletrnica). GSMGetSMSConfirmation - Permite ler a string de confirmao do recebimento de uma mensagem SMS por parte do destinatrio. Este mtodo deve ser chamado no evento que confirma o recebimento de uma mensagem SMS por parte do destinatrio (OnGSMSMSConfirmation). OnGSMSMSConfirmation - Permite receber a confirmao do recebimento de uma mensagem SMS por parte do destinatrio (este recurso depende da disponibilidade da operadora). OnGSMSIM - Ocorre na insero ou retirada do SIM Card (chip) nos mdulos GSM, permitindo por exemplo que o programador reinicie a thread GSM aps a insero de um chip na placa. AudioMonitor - Monitora em tempo real o udio de uma porta especfica na sada de udio do PC. GetCardInfo - Informa dados sobre a placa. ConfigISDNThread - Configura as opes de tratamento da thread em relao ao protocolo ISDN PRI. CreateISDNThread - Inicia o tratamento do protocolo ISDN PRI de troncos digitais. DestroyISDNThread - Termina o tratamento do protocolo ISDN PRI. DisableISDNThread - Desabilita o tratamento do protocolo ISDN PRI de troncos digitais. EnableISDNThread - Habilita o tratamento do protocolo ISDN PRI. GetBusyCause - Retorna a causa do desligamento da chamada em caso de ocupado. GetISDNThreadStatus - Retorna o status da thread ISDN da placa e span especificados. GetNameID - Recupera o nome do assinante chamador quando diponvel no sistema FSK e no protocolo ISDN PRI. GetText - Retorna uma mensagem de texto recebida pela VoicerLib. ReturnCauseToStringCauseHangUp - Retorna qual a


39

Guia de ProgramaoGuia de Migrao de Verses Anterioresdescrio da causa de ocupado, a partir do cdigo de retorno. SendISDNCommand - Envia um comando ISDN referente a estabelecimento de chamadas entrantes. SetBearCapability - Configura o tipo da chamada do span. SetCalledNumber - Configura as propriedades do nmero a ser discado. SetCallingNumber - Configura as propriedades do nmero do identificador de A (BINA). SetHangUpCause - Configura a causa do desligamento da porta no protocolo ISDN PRI. SetNameID - Especifica o nome da identificao de uma porta no tronco digital quando se utiliza protocolo ISDN PRI. SetReverseCharging - Solicita a inverso de cobrana para chamada sainte. SetText - Especifica uma mensagem de texto a ser enviada pela VoicerLib por uma porta no tronco digital no protocolo ISDN PRI. OnChannel - Indica a mudana de porta de uma chamada. OnErrorNodeConfig - Ocorre quando h erro de configurao no ISDN PRI OnNameID - Ocorre quando a placa detecta a descrio do identificador da chamada (nome). OnReverseCharging - Ocorre sempre quando a chamada entrante requisitar a inverso de cobrana da chamada no protocolo ISDN PRI(Ligao a cobrar). OnText - Ocorre sempre que um texto for recebido pela aplicao (VoicerLib) no protocolo ISDN PRI.


40

Guia de ProgramaoInstrues de instalao de placas

Instrues de instalao de placasInstalao das placas Digivoice em Windows Vista e Windows 2008. Devido s exigncias dos novos sistemas operacionais da Microsoft (Windows Vista e Windows 2008) e para manter compatibilidade com produtos anteriores as placas Digivoice com barramento PCI, ao instalar as placas nos sistemas operacionais Windows Vista ou Windows 2008, necessrio fazer uma atualizao no hardware feita por uma configurao em uma memria FLASH das placas. Isto feito por programas fornecidos pela Digivoice (VlibUpdate.exe). Caso seja necessrio fazer um downgrade do sistema operacional, por exemplo de Vista para XP necessrio desfazer a alterao com o programa VlibUpdateRetro. Esta documentao se aplica s placas: VB0408PCI, VB0408PCIe, VB3030PCI, VB3030PCIe, VB6060PCI, VB6060PCIe e VB0404FX. Aps executar o setup da VoicerLib, verifique se a placa foi corretamente instalada da seguinte forma: - Em Painel de Controle - Sistema - Gerenciador de Dispositivos, a placa deve reconhecer o driver da digivoice "dgdriver" e a(s) placa(s) instalada(s). - Caso isso no ocorra, clique com o boto direito do mouse no dispositivo "Controlador de multimdia" na opo "Atualizar driver" e indique o caminho de instalao da Voicerlib. Geralmente em C:\%PROGRAM FILES%\Voicerlib4.


41

Guia de ProgramaoInstrues de instalao de placas

Gerenciador de Dispositivos - Painel de Controle

Caso 1: Computador com sistema operacional Windows XP/2000/2003. Com as placas plugadas e devidamente parafusadas no slot, o setup da Voicerlib instalado. Aps a instalao, verifique se as placas foram detectadas e instaladas corretamente. A cada placa adicionada nesse ambiente (sistema operacional continuando o mesmo) depois da instalao, a verificao e instalao no Gerenciador de Dispositivos deve ser feita. Caso 2: Computador com sistema operacional Windows Vista/2008. Com as placas plugadas e devidamente parafusadas no slot, o setup da Voicerlib instalado. Aps a instalao, verifique se as placas foram detectadas e instaladas corretamente.


42

Guia de ProgramaoInstrues de instalao de placasA cada placa adicionada nesse ambiente, aps a instalao da VoicerLib, (sistema operacional continuando o mesmo) ser necessrio executar o arquivo VlibUpdate.exe que est geralmente no diretrio "C:\%PROGRAM FILES%\VoicerLib4\VlibUpdate". Lembrando que o arquivo deve ser executado com privilgio de administrador da mquina (boto direito - executar como....administrador). O computador deve ser reiniciado e a placa instalada. Caso 3: Adicionar uma ou mais placas Digivoice em um computador com XP/2000/2003 que estavam instaladas e funcionando em um computador com Windows Vista/2008. Executar o arquivo "VlibUpdateRetro.exe" que est geralmente no diretrio: "C:\%PROGRAM FILES%\VoicerLib4\VlibUpdateRetro". O computador deve ser reiniciado e a placa instalada. Caso 4: Adicionar uma ou mais placas Digivoice em um computador com Vista/2008 que estavam instaladas e funcionando em um computador com Windows XP/2000/2003. Executar o arquivo "VlibUpdate.exe" que est geralmente no diretrio: "C:\%PROGRAM FILES%\VoicerLib4\VlibUpdate". (Ressaltando que essa ao deve ser feita com privilgio de administrador). O computador deve ser reiniciado e a placa instalada.


43

Guia de ProgramaoInicializando os Servios

Inicializando os ServiosSempre que iniciar a aplicao, antes de executar qualquer outra funo, necessrio iniciar os servios (device driver). Isto pode ser feito atravs do mtodo StartVoicerLib. A VoicerLib detecta todas as placas disponveis no computador e as inicializa na ordem de colocao dos slots do computador. Com isso possvel ter, por exemplo, uma placa E1 de 60 canais e uma placa analgica de 8 canais. Se a placa E1 for lida primeiro, receber as portas de 1 a 60 e a placa analgica de 61 a 68. A posio fsica dos slots dos computadores variam de fabricante, modelo e sistema operacional, portanto necessrio que a configurao na mquina de produo seja verstil para se adaptar a essas diferenas.

Em um mesmo computador, uma vez instaladas, as placas sempre sero reconhecidas na mesma ordem.

Exclusivo API: Como a API no gera eventos, como conhecido nos componentes visuais, necessrio criar uma funo para manipular os eventos da placa, conforme foi explicado no tpico Conceitos Bsicos. Lembre-se que a associao da Callback de eventos dever ser feita antes de inicializar o driver. Como a inicializao a primeira coisa a ser feita, recomenda-se sua colocao no incio da aplicao. No prtica recomendvel ficar inicializando e finalizando a VoicerLib diversas vezes na aplicao.


44

Guia de ProgramaoFinalizando os Servios

Finalizando os ServiosAntes de fechar a aplicao necessrio chamar o mtodo ShutdownVoicerLib, que finaliza todos os servios e reseta a placa. A no utilizao deste mtodo poder causar travamento no sistema operacional ou algum comportamento imprevisvel. possvel verificar se os servios do hardware foram finalizados corretamente atravs do retorno do mtodo ShutDownVoicerLib, que retorna DG_EXIT_SUCCESS em caso de sucesso. O melhor local para se colocar este mtodo em algum evento finalizador, que antecede o encerramento da aplicao (Unload, OnClose, FormClose etc...).


45

Guia de ProgramaoDetectando Ring

Detectando RingA VoicerLib informa quando tem uma ligao entrante chegando atravs do ring. Sempre quando o ring for detectado, a funo que atua como Gerenciador de Eventos receber na varivel context_data>command o valor EV_RINGS (evento OnRingDetected no ActiveX). Nas placas FXO e GSM, como o ring ocorre em situaes bem especficas a sua deteco est sempre habilitada no havendo mtodos para ligar ou desligar. J na placa E1, o ring um evento que ocorrer quando a thread de controle (R2D MFC ou ISDN PRI) estiver habilitada. Para maiores detalhes, veja o captulo Programao da Placa E1.


46

Guia de ProgramaoAtendendo e Desligando

Atendendo e DesligandoPara atender a ligao ou tomar uma linha para discagem, o mtodo que deve ser utilizado o Pickup . O mtodo pede 2 parmetros. O primeiro a porta de atendimento que vai de 1 a N. O segundo parmetro uma pausa aps o atendimento, em milissegundos (1000 = 1 segundo). Esta pausa til em aplicaes de atendimento automtico em instalaes com bloqueio de chamada a cobrar, etc... Ela deve ser utilizada em conjunto com o evento OnAfterPickUp. Para desligar a ligao, o mtodo utilizado o HangUp. Deve ser passado somente a porta que se deseja desligar. Ambas as funes retornam DG_EXIT_SUCCESS caso tenham sido executadas com sucesso. Um diferencial em relao aos modelos anteriores que quando a ligao atendida ou desligada os eventos OnLineReady e OnLineOff so gerados mesmo que a linha/ramal no esteja em paralelo. A placa E1 um caso especial, pois o PickUp refere-se a solicitao de ocupao de uma porta. Quando executado no contexto da thread (CreateE1Thread, CreateISDNThread), o pickup utilizado para ocupar uma porta na ligao sainte ou atender uma ligao entrante. Se a thread no estiver iniciada, o sinal de ocupao tambm enviado, porm todo o tratamento dever ser feito pela aplicao final.


47

Guia de ProgramaoSuperviso de Linha

Superviso de LinhaA superviso de linha permite ao programador identificar e tratar diversos eventos relativos a sinais enviados pela linha, a saber: Sinal de Ocupado Deteco de Fax Deteco de sinal de discagem (tom de linha) Deteco de sinal de chamada (ringback) Deteco de Atendimento

Nas placas digitais (E1) no existe propriamente um sinal de ocupado, tom de discagem ou sinal de chamada j que toda a parte de sinalizao feita pelo protocolo R2D, porm, a VoicerLib simula estes sinais e eventos para deixar a programao similiar s placas FXO. Isso s possvel se utilizar as threads de controle (ConfigE1Thread).

Acionamento das deteces nas placas FXO Na VoicerLib 4, a superviso de linha foi implementada atravs de threads de controle que so criadas atravs do mtodo CreateCallProgress. A thread de Call Progress responsvel pelo acompanhamento de chamadas, ou seja, a superviso de um tom genrico, de tons de linha, de chamar (ringback), de ocupado, de fax e o atendimento pelo assinante chamado. O mtodo CreateCallProgress cria a thread de controle e em seguida dorme portanto pode ser criado no incio da aplicao sem prejuzo de processamento, devendo ser chamada para cada porta especfica. Todos os parmetros de configurao da thread de Call Progress ficam armazenados em um arquivo texto de configurao localizado na pasta firmware (Linux) ou \%PROGRAM FILES%\VoicerLib4 (Windows). O arquivo padro o cp_default.cfg porm o desenvolvedor poder criar outros de acordo com suas necessidades, j que o nome do arquivo a ser utilizado passado no mtodo CreateCallProgress.


48

Guia de ProgramaoSuperviso de LinhaTambm possvel configurar o CallProgress sem a utilizao do arquivo. Todos os parmetros podem ser configurados atravs do mtodo ConfigCallProgress pois cada item do arquivo de configurao tem sua constante correspondente. Veja todas estas opes no Guia de Referncia, no mtodo ConfigCallProgress.

Depois da criao da thread de controle, necessrio chamar o mtodo EnableCallProgress para efetivamente monitorar a linha. O acompanhamento de chamadas foi dividido em 4 opes bsicas para agilizar sua utilizao e economizar recursos de hardware: 1 - CP_ENABLE_GENERIC_TONE - Desenvolvida para detectar a presena de um tom qualquer pr-configurado ou o atendimento de chamada, esta facilidade superviso de atendimento pode ser habilitada na VoicerLib pelo mtodo EnableAnswerDetection. 2 - CP_ENABLE_LINETONE_OR_BUSY - Desenvolvida para a deteco rpida de tom de discar (tom de linha) ou ocupado antes do incio de uma discagem ou aps um Flash. 3 - CP_ENABLE_BUSY_OR_FAX - Desenvolvida para a deteco rpida de tom de ocupado ou sinal de fax aps o atendimento de uma chamada. 4 - CP_ENABLE_ALL - Desenvolvida para a deteco de tons de discar, de chamada, de ocupado, de fax e atendimento entre uma discagem e o atendimento pelo assinante chamado. A princpio, esta opo atende qualquer situao, mas devido s restries das vrias cadncias dos tons, a discriminao de um determinado tom, pode demorar mais tempo que em uma opo especfica como a CP_LINETONE_OR_BUSY. Isso significa que o desenvolvedor poder simplificar sua aplicao sempre habilitando o callprogress utilizando esta opo, mas ter uma deteco mais rpida e eficiente se utilizar a opo especfica para cada situao.


49

Guia de ProgramaoSuperviso de LinhaEnto, como sugesto, o desenvolvedor pode utilizar a seguinte regra em uma discagem com superviso: Com a porta desligada, ao iniciar uma ligao (PickUp), chamase o EnableCallProgress passando o valor CP_ENABLE_LINETONE_OR_BUSY Ao detectar o tom de linha, efetua a discagem e aps a discagem, chama-se novamente o EnableCallProgress passando o valor CP_ENABLE_ALL. Aps a discagem, necessrio habilitar a deteco de atendimento tambm, utilizando o mtodo EnableAnswerDetection. Logo aps o atendimento, necessrio desabilitar sua deteco chamando o mtodo DisableAnswerDetection e chamar o EnableCallProgress com o valor CP_ENABLE_BUSY_OR_FAX, j que, aps o atendimento s necessrio esperar o tom de ocupado e o fax. O DisableCallProgress deve ser chamado para desabilitar qualquer tipo de superviso e o mtodo DestroyCallProgress deve ser chamado no trmino da aplicao para evitar a perda de recursos de memria (memory leak). Conforme j foi dito, todos os parmetros de configurao da thread de CallProgress ficam armazenados em um arquivo texto de configurao cp_default.cfg (padro) que contm diversos comentrios explicando cada parmetro. Por isso ele demonstrado a seguir:

[CallProgress] ;------------------------------------------------------; AnswerSensitivity refere-se a quantos "audios" deverao ser ; recebidos na sequencia para considerar atendimento ; Valor minimo = 0 ; Padrao = 1 ; NUNCA ALTERE ESTE PARAMETRO POIS PODE DIFICULTAR A ; DETECCAO DE ATENDIMENTO ;-------------------------------------------------------


50

Guia de ProgramaoSuperviso de LinhaAnswerSensitivity=1 ;------------------------------------------------------; AnswerSensitivityTime e a duracao *minima* de um ; audio para se considerar atendimento. ; Para diminuir a sensibilidade ; aumente o valor. O padrao e 200ms ;------------------------------------------------------AnswerSensitivityTime=10 ;------------------------------------------------------; GenericToneTimeout determina o tempo *minimo* que o ; sistema esperara para reconhecer o tom generico. ; Caso nao venha neste tempo, gerara o evento de ; timeout. ; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_GENERIC_TONE ;------------------------------------------------------GenericToneTimeout=15000 ;------------------------------------------------------; GenericToneTime determina o tempo *minimo* para ; que o sistema reconheca o audio como tom generico ; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_GENERIC_TONE ;------------------------------------------------------GenericToneTime=500 ;------------------------------------------------------; LineToneTimeout determina o tempo *minimo* que o ; sistema esperara para reconhecer o tom de linha. ; Caso nao venha neste tempo, o evento de timeout ; sera gerado. ; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_LINETONE_OR_BUSY ;------------------------------------------------------LineToneTimeout=15000 ;-------------------------------------------------------


51

Guia de ProgramaoSuperviso de Linha; LineToneTime determina o tempo *minimo* para que ; o sistema reconheca o audio como tom de linha ; Valor em milisegundos ; *** PRECISA SER MAIOR QUE BusyMaxTime *** ; Opcoes de Call Progress: ; CP_ENABLE_LINETONE_OR_BUSY ;------------------------------------------------------LineToneTime=750 ;------------------------------------------------------; FaxToneTimeout determina o tempo *minimo* que o ; sistema esperara para reconhecer o tom de fax. ; Caso nao venha neste tempo, gerara evento de timeout. ; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_BUSY_OR_FAX ;------------------------------------------------------FaxToneTimeout=15000 ;------------------------------------------------------; FaxToneTime determina o tempo *minimo* para que ; o sistema reconheca o audio como tom de fax ; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_BUSY_OR_FAX e CP_ENABLE_ALL ;------------------------------------------------------FaxToneTime=200 ;------------------------------------------------------; CallProgressTimeout e o tempo de espera apos ; a discagem para se considerar que houve um ; atendimento por timeout ; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_ALL ;------------------------------------------------------CallProgressTimeout=15000 ;------------------------------------------------------; BusyMinTime determina o tempo *minimo* do ; tom de ocupado ; Valor em milisegundos


52

Guia de ProgramaoSuperviso de Linha; Opcoes de Call Progress: ; CP_ENABLE_LINETONE_OR_BUSY e CP_ENABLE_BUSY_OR_FAX e ; CP_ENABLE_ALL ;------------------------------------------------------BusyMinTime=200 ;------------------------------------------------------; BusyMaxTime determina o tempo *minimo* do tom ; de ocupado ; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_LINETONE_OR_BUSY e CP_ENABLE_BUSY_OR_FAX e ; CP_ENABLE_ALL ;------------------------------------------------------BusyMaxTime=550 ;------------------------------------------------------; BusySensibility determina quantos tons de ; ocupado devem ser detectados para que seja ; gerado um evento para a aplicacao. ; O padrao 1 e este parametro e aplicado ; somente no CP_ENABLE_BUSY_OR_FAX ;------------------------------------------------------BusySensibility=5 ;------------------------------------------------------; CallingMinToneTime determina o tempo *minimo* para se ; considerar um tom de chamada (apos a discagem). Sera ; testado como intervalo junto com CallingMaxToneTime ; Valor em milisegundos ; *** PRECISA SER MAIOR QUE BusyMaxTime *** ; Opcoes de Call Progress: ; CP_ENABLE_ALL ;------------------------------------------------------CallingMinToneTime=450 ;------------------------------------------------------; CallingMaxToneTime determina o tempo *maximo* para se ; considerar um tom de chamada (apos a discagem). Sera ; testado como intervalo junto com CallingMinToneTime ; Valor em milisegundos ; No CP_ENABLE_ALL este tempo + 500ms tambem e


53

Guia de ProgramaoSuperviso de Linha; utilizado para medir o tom de discagem ; Opcoes de Call Progress: ; CP_ENABLE_ALL ;------------------------------------------------------CallingMaxToneTime=2000 ;------------------------------------------------------; CallingMinSilTime o tempo *minimo* para se ; considerar silencio. Sera testado como intervalo ; junto com CallingMaxSilTime ; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_ALL ;------------------------------------------------------CallingMinSilTime=700 ;------------------------------------------------------; CallingMaxSilTime determina o tempo *maximo* para se ; considerar silencio. Sera testado como intervalo ; junto com CallingMinSilTime ; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_ALL ;------------------------------------------------------CallingMaxSilTime=5000 ;------------------------------------------------------; ToneInterruptionMinTime determina o tempo *minimo* do ; intervalo entre cada tom de linha. A deteccao do tom ; de chamando depende tambem dos tempos do intervalo ; entre eles. ; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_ALL ;------------------------------------------------------ToneInterruptionMinTime=20 ;------------------------------------------------------; ToneInterruptionMaxTime determina o tempo *minimo* do ; intervalo entre cada tom de linha. O deteccao do tom ; de chamando depende tambem dos tempos do intervalo ; entre eles.


54

Guia de ProgramaoSuperviso de Linha; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_ALL ;------------------------------------------------------ToneInterruptionMaxTime=280 ;------------------------------------------------------; LineToneMinTime determina o tempo *minimo* para se ; considerar o tom de linha ; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_ALL ;------------------------------------------------------LineToneMinTime=2500 ;------------------------------------------------------; LineToneMaxTime determina o tempo *maximo* para se ; considerar o tom de linha ; Valor em milisegundos ; Opcoes de Call Progress: ; CP_ENABLE_ALL ;------------------------------------------------------LineToneMaxTime=2700 ;------------------------------------------------------; Aqui sao definidas as frequencias utilizadas ; nas configuracoes a seguir associadas ao ; tipo de deteccao (ocupado, chamando, etc) ;------------------------------------------------------tone1=425,0 tone2=1100,0 tone3=2100,0 tone4=0,0 tone5=0,0 tone6=0,0 tone7=0,0 tone8=0,0 ;------------------------------------------------------; Configuracao das frequencias para cada tipo de ; deteccao ; Aqui devera ser informado o indice de configuracao da ; voicerlib:


55

Guia de ProgramaoSuperviso de Linha; CP_SILENCE usar valor -> (0x20) 32 ; CP_AUDIO usar valor -> (0x21) 33 ; CP_TONE1 usar valor -> (0x22) 34 (425Hz) ; CP_TONE2 usar valor -> (0x23) 35 (1100Hz) ; CP_TONE3 usar valor -> (0x24) 36 (2100Hz) ; custom comands ; CP_TONE4 usar valor -> (0x25) 37 ; CP_TONE5 usar valor -> (0x26) 38 ; CP_TONE6 usar valor -> (0x27) 39 ; CP_TONE7 usar valor -> (0x28) 40 ; CP_TONE8 usar valor -> (0x29) 41 ;------------------------------------------------------Audio=0x21 ;default CP_AUDIO - nao mudar! Silence=0x20 ;default CP_SILENCE - nao mudar! LineToneFreq=0x22 ;default refere-se a CP_TONE1 CallingToneFreq=0x22 ;default refere-se a CP_TONE1 BusyToneFreq=0x22 ;default refere-se a CP_TONE1 Fax1ToneFreq=0x23 ;default refere-se a CP_TONE2 Fax2ToneFreq=0x24 ;default refere-se a CP_TONE3 GenericToneFreq=0x25 ;default refere-se a CP_TONE4 GenericToneFreq2=0x26 ;default refere-se a CP_TONE5 GenericToneFreq3=0x27 ;default refere-se a CP_TONE6 GenericToneFreq4=0x28 ;default refere-se a CP_TONE7 GenericToneFreq5=0x29 ;default refere-se a CP_TONE8 ;------------------------------------------------------; Terminador de Arquivo ; Mantenha o proximo item sempre como o ultimo deste ; arquivo para que a voicerlib possa detectar se o ; arquivo esta danificado ;------------------------------------------------------end=1


56

Guia de ProgramaoSuperviso de LinhaNo caso da opo CP_ENABLE_ALL, como no Brasil todos os tons tem a mesma frequncia (425Hz) a distino de chamando, ocupado e tom de discar (linha) feita pela anlise de cadncia, ou seja, durao de tons e silncio, portanto tome cuidado com os tempos anteriores respeitando a seguinte relao:(BusyMaxTime < CallingMinToneTime) e (CallingMaxToneTime < LineToneMinTime) |-----|-----| Busy Min Max |----------------|--------| Calling Min Max |-------------------------------|------|Line Min Max

Acionamento das deteces nas placas E1 Conforme foi dito anteriormente, nas placas E1 no necessrio habilitar as deteces de tom de linha, ocupado ou atendimento pois estas respostas vm automaticamente pelo protocolo. J a deteco de fax deve ser habilitada explicitamente atravs da chamada do mtodo SetDetectionType para as frequncias 1100Hz e 2100Hz. Estas frequncias j so previamente definidas atravs das constantes DETECT_TONE2 e DETECT_TONE3, as quais devero ser passadas no segundo parmetro do mtodo SetDetectionType. Consulte o Guia de Referncia para maiores detalhes.

Reconhecimento dos sinais de superviso Sinal de Ocupado: Ao ser detectado o sinal de ocupado, o evento OnBusyDetected gerado, podendo ser tratado pelo usurio da maneira como quiser.


57

Guia de ProgramaoSuperviso de LinhaPlaca FXO/FXS/GSM: O evento gerado sempre que for detectado o ocupado, portanto, caso o sinal de ocupado permanea por muito tempo sem desligar, o programa gerar vrias vezes o evento. Para evitar isso, o programador deve desabilitar a superviso de linha com o mtodo DisableCallProgress, aps o primeiro ocupado. Outro efeito que pode ocorrer muito raramente o sinal de ocupado ser detectado durante a conversao. Isto acontece com certos tons e candncias de voz. Para prever esta situao, recomendamos ao programador sempre esperar pelo menos dois sinais de ocupado antes de tomar alguma atitude. Isto reduz muito os casos de interpretao errada pois muito difcil uma voz gerar dois tons de ocupado na mesma cadncia do tom real. Exclusivo para placa E1: O evento de ocupado gerado no caso de porta bloqueada, trmino de ligao, etc. Como no se trata de um tom intermitente e sim de dado R2D, o evento OnBusyDetected s ocorrer uma vez. Por caracterstica do protocolo R2D, possvel detectar o desligamento independente de quem tenha gerado a ligao. Deteco de Fax: til principalmente em aplicaes de atendimento automtico. possvel fazer uma rotina, por exemplo, que ao perceber um sinal de fax, transfere para o ramal do aparelho de fax. O evento que gerado neste caso o OnFaxDetected. Deteco de Atendimento: A VoicerLib permite ao programador detectar quando uma ligao foi atendida do outro lado da linha. O evento OnAnswerDetected gerado sempre quando este sinal for detectado. Lembre-se que, nas placas FXO/FXS/GSM, necessrio desabilitar a deteco de atendimento logo aps a ocorrncia da primeira deteco para evitar detectar falsos atendimentos durante a conversao. Deteco de sinal de discagem: Em linhas analgicas, o sinal de discagem aquele tom contnuo que se escuta ao tirar o fone do gancho. Em alguns casos, este sinal pode demorar alguns segundos, principalmente em centrais congestionadas. Este evento controlado pelos mtodos EnableCallProgress e


58

Guia de ProgramaoSuperviso de LinhaDisableCallProgress . O evento OnDialToneDetected gerado sempre quando este sinal for detectado. J em linhas digitais (E1), no existe o tom de discagem propriamente dito. No momento de ocupar a porta, j enviado imediatamente se a porta estiver bloqueada, por exemplo. Quando a porta da placa recebe a confirmao de ocupao, significa que est pronta para discar. A VoicerLib gera o evento OnDialToneDetected quando esta confirmao recebida. Em uma situao prtica, mais correto esperar o tom de discagem para ento utilizar o mtodo Dial para discar e no atender e discar em seguida. Deteco de sinal de chamada: Ao discar para um determinado nmero, sempre ouvimos o sinal de chamada, que indica que o telefone est tocando do "outro lado" da linha. Este evento tambm controlado pelos mtodos EnableCallProgress e DisableCallProgress. Com este sinal podemos contar quantos toques so dados at a ligao ser atendida ou ainda detectar que a ligao no foi completada (no caso de o sinal no ser detectado). O evento OnCalling ocorre sempre quando o sinal for detectado, o que faz com que ele seja chamado vrias vezes at a ligao ser atendida. Nas placas E1 com a thread de controle habilitada, o evento OnCalling gerado independente de chamar Enable/DisableCallProgress e independe da chegada do tom audvel, pois funciona atravs de um timer interno da VoicerLib. Para a aplicao final, essa diferena de funcionamento no altera nenhum procedimento. O tom de controle de chamada (ringback) ou ocupado gerado localmente pela placa para que o usurio tenha conhecimento do andamento da ligao.


59

Guia de ProgramaoDeteco de Silncio

Deteco de SilncioA VoicerLib 4 permite fazer deteco de silncio atravs de um comando especfico para isso. Em muitas situaes, perceber a existncia de silncio muito importante. Um exemplo tpico de aplicao a gravao de mensagens de correio de voz onde o desenvolvedor queira interromper a gravao caso a ligao fique em silncio por N segundos. Outro exemplo na gravao de conversas telefnicas com a linha em paralelo pois permite que a gravao seja pausada ou terminada caso haja silncio por um tempo pr-determinado. O mtodo que habilita esta funcionalidade o EnableSilenceDetection que tem como parmetro a porta, o tempo mnimo para considerar silncio (silence_time) e o tempo mnimo para considerar udio (audio_time). Estes dois ltimos parmetros devem ser informados em milisegundos (1000 = 1s). O parmetro audio_time permite ainda receber o valor zero, indicando que, ao primeiro sinal de udio a aplicao ser avisada. Dependendo da aplicao e do ambiente de produo este valor pode ser aumentado para um valor maior pois assim a VoicerLib desprezar sinais de udio que tiverem durao menor que a especificada. Esse comportamento equivale a uma diminuio da sensibilidade da deteco de udio. Se no houver situaes de rudo na linha, etc, recomenda-se utilizar o valor zero nesse parmetro(audio_time). O evento OnSilenceDetected ser gerado sempre que houver uma mudana no estado, ou seja, quando for detectado o silncio, o evento ser gerado uma vez, informando no parmetro SignalCode o valor DG_SILENCE_DETECTED (1). Quando receber um sinal de udio, o evento ser gerado novamente com o parmetro SignalCode recebendo o valor DG_AUDIO_DETECTED (0). Depois disso, o evento s ser gerado de novo se for detectado um silncio e assim por diante. Para desabilitar esta deteco, necessrio chamar o mtodo DisableSilenceDetection.


60

Guia de ProgramaoDeteco de Tons

Deteco de TonsUma das maiores evolues da VoicerLib 4 em relao verso 2.x nas deteces de tons. Agora existem muito mais opes de deteces, dando ao desenvolvedor grande liberdade de trabalho mesmo em situaes incomuns. Por padro, a VoicerLib permite a deteco de at oito tipos de tons, utilizados em superviso de linha, etc. Destes 8 tipos de tons, temos pr-configurados trs: DETECT_TONE1 - Tom puro 425Hz, o padro brasileiro para tons de supervisao de linha DETECT_TONE2 - Tom de 1100Hz, utilizado para detectar FAX DETECT_TONE3 - Tom de 2100Hz, utilizado para detectar FAX Estes tons puros so suficientes para a superviso de linha padro e deteco de fax na maioria dos casos. O tpico "Superviso de Linha" aborda detalhadamente como utiliza-lo e a chamada a estas funes est embutido nas chamadas de callprogress, portanto, uma configurao manual no necessria a no ser em casos especiais. O mtodo que habilita/desabilita as deteces o SetDetectionType que tem como parmetro a porta, o comando (DETECT_TONE1, etc...) e o flag que habilita ou desabilita a deteco (DG_ENABLE/DG_DISABLE). Consulte o guia de referncia para ver todas as opes. A chamada deste mtodo tem efeito cumulativo, ou seja, fazendo uma chamada para habilitar TONE3 por exemplo, e outra chamada para habilitar TONE1 ocasionar a deteco dos dois tipos. Este mesmo mtodo habilita a deteco de dgitos, que ser abordado no tpico seguinte.


61

Guia de ProgramaoDeteco de TonsMudando a configurao padro O desenvolvedor poder reconfigurar todos os tipos de tons (TONE1 a TONE8) a serem detectados, atravs do mtodo SetCardDetections, passando como parmetro a placa, o tom a ser modificado e o par de frequncias que passar a ser monitorado. No Guia de Referncia das funes e mtodos so apresentadas todas as opes.

ATENO: importante ressaltar que a alterao das frequncias a serem detectadas s podem ser feitas na placa inteira e no por porta individualmente. Isso no constitui uma limitao j que normalmente uma alterao deste tipo afeta todo o sistema e no portas especficas.


62

Guia de ProgramaoDeteco de Dgitos

Deteco de DgitosA VoicerLib permite detectar dgitos tanto em tons multifrequenciais como em pulso nativamente. A deteco de tons multifrequenciais habilitada ou desabilitada atravs do mtodo SetDetectionType que tem como parmetro a porta, o comando (DETECT_DTMF etc...) e o flag que habilita ou desabilita a deteco de dgitos (DG_ENABLE/DG_DISABLE). Consulte o guia de referncia para ver todas as opes. O segundo parmetro, o comando pode assumir as seguintes opes: DETECT_DTMF - Deteco do DTMF, o mais comum para aplicaes com interao com o usurio DETECT_MFF e DETECT_MFT - So os sinais multifrequenciais comuns sinalizao R2D DETECT_MF - Sinal multifrequencial customizvel A deteco de pulso habilitada pelo mtodo EnablePulseDetection e desabilitada pelo mtodo DisablePulseDetection. No mtodo EnablePulseDetection passado a sensibilidade de deteco, sendo o padro zero. Esta sensibilidade pode ser alterada caso se perceba uma dificuldade ou facilidade maior nas deteces de pulso. O funcionamento das duas deteces praticamente o mesmo, exceto pelo fato que a deteco de tom pode ser feita durante a reproduo de uma mensagem e a de pulso somente no silncio aps a mensagem.

Habilitando o cancelamento de eco, possvel ter boa performance na deteco de pulsos sobre a mensagem.


63

Guia de ProgramaoDeteco de DgitosA VoicerLib permite tratar o reconhecimento de dgitos de duas maneiras diferentes. A primeira atravs do evento OnDigitDetected, que gerado sempre que um dgito qualquer for detectado pela placa. O dgito detectado ser passado atravs do parmetro Digit do evento. Este parmetro conter o cdigo ASCII do dgito. Caso o programador implemente algum tratamento neste evento, deve tomar cuidado para saber o momento em que ele ocorreu, pois pode acontecer uma deteco pelos dgitos gerados pela prpria placa. O mais aconselhvel s habilitar as deteces nos momentos que ela seja necessria, para evitar situaes de talkoff. possvel otimizar a deteco utilizando o mtodo SetTwist (consulte o Guia de Referncia para maiores detalhes). TALK-OFF: A voz humana, em uma conversa normal, pode conter a mesma frequncia dos dgitos detectados pela placa, portanto, quando o operador ou o interlocutor falar, algum dgito pode ser detectado e se o tratamento no OnDigitDetected no for adequado, o sistema pode interpretar errneamente os sinais recebidos. Uma aplicao tpica que recomendada a utilizao do evento OnDigitDetected na identificao de chamadas (BINA). Exemplo: Neste exemplo, o dgito detectado o tempo inteiro e mostrado na tela. Private Sub VoicerLibX1_OnDigitDetected(Port As Integer, Digit As Integer) lblStatus.Caption = "Detectou Digito " + Chr$(voicerlibx1.ReadDigits(Port)) End Sub A segunda maneira de detectar dgitos atravs do mtodo GetDigits.


64

Guia de ProgramaoDeteco de DgitosO mtodo GetDigits inicia a monitorao de dgitos, sendo que possvel determinar o nmero mximo de dgitos, se esperar um dgito terminador, e tempos mximos para recepo destes dgitos. Aps o incio da monitorao, o evento OnDigitsReceived pode ocorrer a qualquer momento. Este evento ocorre quando uma das condies impostas pelo mtodo GetDigits for satisfeita. O mtodo ReadDigits permite ler o contedo do buffer de dgitos da porta. Durante a monitorao possvel cancelar o andamento do GetDigits atravs do mtodo CancelGetDigits. Se esse mtodo for chamado, o GetDigits ser cancelado mas o evento OnDigitsReceived no ser gerado e o buffer de dgitos ser apagado. O mtodo CancelGetDigits dever ser chamado principalmente em situaes onde a ligao foi terminada durante o GetDigits. Uma mudana importante em relao s verses anteriores da VoicerLib que agora o buffer de dgitos deve sempre ser apagado explicitamente pelo programa, atravs do mtodo ClearDigits. Exemplo: No exemplo abaixo o GetDigits inicia esperando at 5 dgitos, ou at receber o terminador # por no mximo 10 segundos de espera total ou 5 segundos de intervalo entre cada dgito: Private Sub Espera Digito() VoicerLibX1.GetDigits Porta,5,"#",10000,5000 End Sub 'No evento OnDigitsReceived que ser tratado os digitos recebidos, ou verificado timeout Private Sub VoicerLibX1_OnDigitsReceived(Port As Integer,Status As VoicerLib.TxWaitDigit)


65

Guia de ProgramaoDeteco de DgitosSelect Case Status Case edMaxDigits: 'Alcanou o mximo de digitos, disca para o ramal Case edTermDigit: 'Recebeu um nmero com # no fim Case edDigitTimeOut: 'Timeout global de 10 segundos Case edInterDigitTimeOut: 'Ocorreu timeout entre dois dgitos End Select End Sub O evento OnDigitsReceived tambm pode ter a varivel Status com valor edDigitOverMessage. Neste caso, o evento ter sido gerado pela deteco de um dgito durante a reproduo de uma mensagem a partir dos mtodos Playxxx.


66

Guia de ProgramaoIdentificao de Chamadas

Identificao de ChamadasA identificao de chamadas (BINA) est facilmente disponvel atravs dos mtodos IdleXXX nas placas FXO e FXS e da thread de controle nas placas E1 (CreateE1Thread, CreateISDNThread). Consulte os referidos tpicos para maiores detalhes. Entretanto, o desenvolvedor tambm pode desenvolver sua prpria rotina de deteco de identificador de chamadas, normalmente fazendo uso do mtodo SetDetectionType para configurar o tipo de sinalizao e manipulando estes dgitos atravs do evento OnDigitDetected. Neste caso, toda a montagem da string com o nmero identificado manual.


67

Guia de ProgramaoPortas Virtuais

Portas VirtuaisQuando a VoicerLib inicializada, todas as placas presentes no computador so analisadas e o nmero da porta assumido na ordem em que as placas esto posicionadas no barramento PCI. Por exemplo, se houverem 2 placas FXO VB0408PCI de 8 canais cada e uma placa E1 VB6060PCI de 60 canais, as portas de 1 a 16 sero atribudas s duas placas FXO e as portas 17 a 77 sero atribudas placa E1.

Aparentemente no existe padro entre os fabricantes de motherboard quanto ordem das placas no barramento. Tambm os sistemas operacionais podem reconhecer as placas de maneiras diferentes no mesmo hardware. Entretanto, no existem alterao nessa ordem depois de tudo instalado corretamente. Essa alocao automtica de portas adequada maioria das aplicaes, porm existem situaes onde interessante o desenvolvedor determinar o nmero da porta de cada canal fsico da placa. A gravao em paralelo em placas E1 de 60 canais um exemplo tpico pois somente os primeiros 30 canais de cada placa so utilizados o que faz com que a aplicao tenha que gerenciar os canais de 1-30, 61-90, 121-150 e assim por diante. Com a utilizao dos mtodos de canais virtuais, o desenvolvedor pode, no incio da aplicao associar os canais de maneira a ficar com uma numerao de portas continua (de 1 a 90, por exemplo). Associando um canal fsico uma porta virtual O mtodo DefinePortResource permite atribuir uma numerao qualquer a um canal fsico de determinada placa, tendo a seguinte sintaxe: DefinePortResource(PortaVirtual, Placa, Canal)


68

Guia de ProgramaoPortas VirtuaisOnde PortaVirtual o nmero lgico a ser utilizado, Placa o nmero da placa (de 1 a n, na ordem do barramento PCI) e Canal o canal fsico de Placa (ex.: uma placa FXO de 8 canais tem canais de 1 a 8). A PortaVirtual dever respeitar o nmero mximo de portas reconhecida pelo sistema, ou seja, no poder ter valor maior do nmero mximo de portas, valor esse, que pode ser obtido atravs do mtodo GetPortsCount. A nica verificao que o mtodo DefinePortResource faz, com relao aos valores de placa e canal. No existe nenhum feedback se determinada porta virtual j foi alocada ou no. Este controle dever ser feito pela aplicao. Aps fazer a associao, a portavirtual passar a ser utilizada pela VoicerLib em todos os mtodos e eventos para referenciar a porta fsica da

Meucci Manual Do Program Ad Or

Documents

Transcript of Meucci Manual Do Program Ad Or