Voicer Lib 2

Digi Voice
Digivoice Tecnologia em Eletrnica
Digivoice VoicerLib2
Sistema de Desenvolvimento para placas Digivoice
Guia do Programador
MAN0024 Impresso: - Version 4.2 21/07/2005, 10:10
Copyright 2005 Digivoice Eletrnica
Contents
Contedo
Parte I Introduo Parte II Histrico de Verses Parte III Iniciando
10 12 26
1 Cabos ......................................................................... & Conectores 26 2 Descrio ......................................................................... do Produto 27 3 Instalando ......................................................................... a Biblioteca 28 4 Instalando ......................................................................... o Hardware 31 5 Preparando ......................................................................... o Ambiente 35 6 Requisitos ......................................................................... Mnimos 38
Parte IV Tpicos de Programao
42
1 Estrutura ......................................................................... Bsica de Funcionamento 42 2 Inicializando ......................................................................... os Servios 43 3 Finalizando ......................................................................... os Servios 44 4 Detectando ......................................................................... Ring 45 5 Atendendo ......................................................................... e Desligando 45 6 Superviso ......................................................................... de Linha 46 7 Deteco ......................................................................... de Dgitos 51 8 Discagem ......................................................................... 56 9 Configuraes ......................................................................... de DTMF 58 10 Controle ......................................................................... de Volume 59 11 Microfone ......................................................................... 60
II
Digivoice VoicerLib2 12 Fone ......................................................................... do Headset 61 13 Gravando ......................................................................... uma Conversa 62 14 Identificao ......................................................................... de Chamadas 64 15 Reproduzindo ......................................................................... Data 65 16 Reproduzindo ......................................................................... Hora 66 17 Reproduzindo ......................................................................... Lista de Mensagens 67 18 Reproduzindo ......................................................................... Nmeros Cardinais 71 19 Reproduzindo ......................................................................... Nmeros Dgito a Dgito 72 20 Reproduzindo ......................................................................... uma Mensagem 73 21 Reproduzindo ......................................................................... Valores por Extenso 76 22 Status ......................................................................... dos Canais 77 23 Tratamento ......................................................................... de Erros 77 24 Protegendo ......................................................................... sua Aplicao 79
Parte V Utilizando um aparelho telefnico Parte VI Funes Especiais
82 86
1 Introduo ......................................................................... 86 2 Funes ......................................................................... de Idle 87 3 Funes ......................................................................... de Prompt 89 4 Funes ......................................................................... de Menu 90 5 Funes ......................................................................... de Discagem e Transferncia 91 6 Funes ......................................................................... de Conferncia 94 7 Funes ......................................................................... para Streaming de Audio 96
Parte VII Distribuindo uma Aplicao
100
1 Introduo ......................................................................... 100 2 Preparando ......................................................................... o Ambiente 101
Contents
III
Parte VIII Aplicao Exemplo
106
1 Apresentao ......................................................................... 106 2 Atendimento ......................................................................... de uma ligao 109 3 Concluso ......................................................................... 110 4 Definindo ......................................................................... Constantes para a Aplicao 111 5 Finalizando ......................................................................... a VoicerLib 113 6 Inicializando ......................................................................... a VoicerLib 114 7 Inicializando ......................................................................... o Estado da Aplicao 114 8 Iniciando ......................................................................... o menu de atendimento 115 9 Janela ......................................................................... de Monitoramento 117 10 Transferncia ......................................................................... e Superviso 118 11 Tratamento ......................................................................... de Entrada de Dados 127 12 Tratamento ......................................................................... de Sub-Menu 137 13 Variveis ......................................................................... Globais da Aplicao 140
Parte IX Guia de Referncia
144
1 Propriedades ......................................................................... 144

AutoClearDigits ............................................................................ 144 CardsCount ............................................................................ 144 CardType ............................................................................ 145 ConfigFile ............................................................................ 146 DelayComma ............................................................................ 146 DelayDot ............................................................................ 147 DelaySemicolon ............................................................................ 148 DialType ............................................................................ 148 DriverEnabled ............................................................................ 149 DriverVersion ............................................................................ 150 FirmwareVersion ............................................................................ 150 ForcePlay ............................................................................ 150 PortsCount ............................................................................ 151 StockSigs ............................................................................ 151 Copyright 2005 Digivoice Eletrnica
IV
Digivoice VoicerLib2 2 Eventos ......................................................................... 155

OnAfterDial ............................................................................ 155 OnAfterFlash ............................................................................ 155 OnAfterMakeCall ............................................................................ 156 OnAfterPickUp ............................................................................ 157 OnAnswerDetected ............................................................................ 157 OnBusyDetected ............................................................................ 158 OnCallerID............................................................................ 159 OnCalling ............................................................................ 160 OnCallStateChange ............................................................................ 161 OnDialToneDetected ............................................................................ 162 OnDigitDetected ............................................................................ 163 OnDigitsReceived ............................................................................ 164 OnErrorDetected ............................................................................ 165 OnFaxDetected ............................................................................ 166 OnLineOff ............................................................................ 167 OnLineReady ............................................................................ 168 OnMenu ............................................................................ 169 OnPlayStart ............................................................................ 170 OnPlayStop ............................................................................ 170 OnPrompt ............................................................................ 172 OnRecording ............................................................................ 172 OnRecordStart ............................................................................ 173 OnRecordStop ............................................................................ 174 OnRingDetected ............................................................................ 175 OnSampleReceived ............................................................................ 176
3 Mtodos ......................................................................... 176

AbortCall ............................................................................ 176 ClearDigits ............................................................................ 177 ConferenceAddPort ............................................................................ 178 ConferenceDisablePort ............................................................................ 179 ConferenceEnablePort ............................................................................ 180 ConferenceGetHandle ............................................................................ 181 ConferenceRemovePort ............................................................................ 182 CreateConferenceResource ............................................................................ 183 DeleteConferenceResource ............................................................................ 184 Dial ............................................................................ 185
Contents
DisableAnswerDetection ............................................................................ 186 DisableCallProgress ............................................................................ 187 DisableEchoCancel ............................................................................ 188 DisablePulseDetection ............................................................................ 189 DisableSampleToApp ............................................................................ 190 DisableSampleToCard ............................................................................ 190 EnableAnswerDetection ............................................................................ 191 EnableCallProgress ............................................................................ 192 EnableEchoCancel ............................................................................ 193 EnablePulseDetection ............................................................................ 194 EnableSampleToApp ............................................................................ 194 EnableSampleToCard ............................................................................ 195 Flash ............................................................................ 196 GetDigits ............................................................................ 197 GetPortStatus ............................................................................ 199 GetSamples ............................................................................ 200 GsmToWave ............................................................................ 200 HangUp ............................................................................ 202 IdleAbort ............................................................................ 202 IdleSettings ............................................................................ 203 IdleStart ............................................................................ 205 IsCallInProgress ............................................................................ 205 IsPlaying ............................................................................ 206 IsRecording ............................................................................ 207 MakeCall ............................................................................ 207 MenuAbort ............................................................................ 208 MenuErrorSettings ............................................................................ 209 MenuStart ............................................................................ 210 MicOff ............................................................................ 211 MicOn ............................................................................ 212 PhoneOff ............................................................................ 213 PhoneOn ............................................................................ 214 PickUp ............................................................................ 215 PlayCardinal ............................................................................ 216 PlayCurrency ............................................................................ 217 PlayDate ............................................................................ 218 PlayFile ............................................................................ 219 PlayList ............................................................................ 221 Copyright 2005 Digivoice Eletrnica
VI
PlayListAdd ............................................................................ 222 PlayListClear ............................................................................ 223 PlayListGetCount ............................................................................ 224 PlayListRemoveItem ............................................................................ 224 PlayNumber ............................................................................ 225 PlayTime ............................................................................ 226 PromptAbort ............................................................................ 227 PromptSettings ............................................................................ 228 PromptStart ............................................................................ 229 PutSamples ............................................................................ 230 ReadDigits ............................................................................ 231 ReadSecurityWord ............................................................................ 232 RecordFile............................................................................ 233 RecordPause ............................................................................ 234 SetAnswerSensitivity ............................................................................ 235 SetAnswerThreshold ............................................................................ 235 SetCallAfterAnswer ............................................................................ 236 SetCallAfterPickup ............................................................................ 237 SetCallBusyPhrase ............................................................................ 238 SetCallBusyReturnFlash ............................................................................ 239 SetCallFlashTime ............................................................................ 240 SetCallNoAnswerPhrase ............................................................................ 241 SetCallNoAnswerReturnFlash ............................................................................ 241 SetCallNoAnswerRingCount ............................................................................ 242 SetCallPauseBeforeAnalysis ............................................................................ 243 SetCallStartFlash ............................................................................ 244 SetCallWaitForDialTone ............................................................................ 245 SetDetectionType ............................................................................ 246 SetDTMFAttenuatingHigh ............................................................................ 246 SetDTMFAttenuatingLow ............................................................................ 247 SetDTMFDuration ............................................................................ 248 SetDTMFPause ............................................................................ 249 SetDTMFTwist ............................................................................ 250 SetFirstFaxFrequency ............................................................................ 251 SetFrequency ............................................................................ 252 SetFrequencyTime ............................................................................ 253 SetImpedance ............................................................................ 254 SetPlayFormat ............................................................................ 255
Contents
VII
SetRecordFormat ............................................................................ 256 SetRecordGain ............................................................................ 258 SetSecondFaxFrequency ............................................................................ 259 SetToneTwist ............................................................................ 260 SetVolume ............................................................................ 261 ShutdownVoicerLib ............................................................................ 261 Sig2Wave ............................................................................ 262 StartVoicerLib ............................................................................ 263 StopPlayFile ............................................................................ 265 StopRecordFile ............................................................................ 265 Wave2Sig ............................................................................ 266 WaveToGsm ............................................................................ 268 WriteSecurityWord ............................................................................ 269
ndice Remissvo...................271
Parte
I
Introduo
10
Introduo
A Digivoice Tecnologia em Eletrnica disponibilizou para todos os desenvolvedores interessados em trabalhar com sua plataforma de hardware uma biblioteca de desenvolvimento. Esta biblioteca distribuda na forma de componentes ActiveX para plataforma Windows 32 bits (a partir do Windows 98SE). Recomenda-se fortemente a utilizao do Windows XP. A caracterstica aberta do ActiveX permitir ao desenvolvedor grande versatilidade, j que ser possvel utilizar os componentes em qualquer plataforma de desenvolvimento que tenha suporte a ActiveX. Eis alguns exemplos: Borland Delphi (a partir da verso 5.0) Borland C++ Builder (a partir da verso 3.0) Microsoft Visual Basic (a partir da verso 6.0) Microsoft Visual C++ (a partir da verso 5.0)
Nesta verso possvel trabalhar tanto com a placa VoicerPhone como com a VoicerBox e tambm possvel trabalhar com mais de uma placa por micro. Este manual visa dar ao desenvolvedor uma viso completa das funes da biblioteca, mostrando o modo de programao e todas as funes disponveis. Alm disso, conta com um guia de referncia de todas as propriedades, eventos e mtodos existentes.
Parte
II
Histrico de Verses
12
Histrico de Verses
Verso 2.77- 21/07/2005 Quando o MakeCall retorna o estado mkDialToneAfterDial a VoicerLib nao d mais HangUp automatico. Corrigido o problema o MenuStart/OnMenu. Na verso 2.75/76 foi introduzido um erro que fez com que se fosse passado um nome de arquivo especfico no MenuStart ao invs de lista "@", o evento OnMenu no era gerado. Gerenciamento de eventos da placa foi modificado para evitar o uso de 100% de CPU livre.
Verso 2.76- 07/07/2005 Corrigida a grafia do mtodo RemoveConferencePort Corrigido o timeout da espera de digitos aps o atendimento para as funes Idlexxx. Setup compatibilizado para mquinas Pentium 4 HT Verso 2.75- 20/04/2005 Adicionada consistencia na chamada do MakeCall no caso de as funes de Idle estiverem ativadas. Ao chamar o MakeCall, o Idle do canal temporariamente desativado, sendo reativado ao chamar o evento OnAfterMakeCall Ao executar um ReadDigits aps uma gravao que utilizava digitos terminadores, todos os eventuais digitos eram recuperados. Agora, o ReadDigits s retornar o digito que interrompeu a gravao. Problema na utilizao do SampleToApp e SampleToCard em vrias portas corrigido. Novo exemplo de Streaming em Delphi Corrigido problema de chamar o MenuStart de dentro do
Histrico de Verses
13
OnPlayStop. Ao fazer isso, o menu j entrava com uma deteo de digitos em curso. Foi criado novo estado inicial de menu para corrigir o problema. Ao ser gerado o evento OnMenu, a VoicerLib no desliga mais as deteces (CallProgress) automaticamente. No MakeCall foi adicionada a possibilidade de se configurar ZERO flashes de inicio, para os casos de retomadas que s necessitam de digitos. Aumentado timeout de tom de linha no curso de MakeCall Bloquado acesso placas ISA (Este tipo de placa s suportado at a verso 2.71) Corrigido problema de nao aparecer as propriedades DriverEnabled, DriverVersion e FirwareVersion
Verso 2.74- 28/02/2005 Nas funes PlayXXX agora a parte fracionria reconhecida pela vrgula ou pelo ponto. Funo de extenso permite falar parte fracionria com 3 dgitos
Verso 2.73- 11/01/2005 Corrigido problema da funo CancelGetDigits introduzida na verso 2.72 no aparecer nos ambientes de desenvolvimento (Delphi, VB, etc...). Criados novos mtodos EnableEchoCancel e DisableEcoCancel para habilitar ou desabilitar o cancelamento de eco nos recursos de conferncia. Criado novo algoritmo de cancelamento de eco no device driver, permitindo conferncias com melhor qualidade de audio.
Verso 2.72- 20/12/2004
14
Novo mtodo CancelGetDigits para cancelar qualquer GetDigits em curso em um determinado canal. No gera evento nenhum e no mantm o buffer de dgitos. Corrigido problema do Idle de gerar dois eventos AfterPickup . Alterado padro de timeout global do GetDigits. Agora o TimeOut referente ao tempo de chegada do primeiro dgito. Apos o primeiro dgito, o timer cancelado. Corrigido problema de se na passar nmero de flashes no digito pra retomada em caso de ocupado (MakeCall). Problema corrigido no extenso de data com formato m/d/y. Includo o evento de "Esperando tom de discagem" durante o MakeCall. Corrigido o PromptStart que apagava o buffer de dgitos caso fosse passado um arquivo wave e no uma lista de arquivos (@). Novo diretrio StockSigs regravado. Verso 2.71- 18/06/2004 O Idle agora utiliza o timeout interdigito para esperar o primeiro digito tambm. Se no chegar no tempo especificado, termina e gera o AfterPickUp. Aps o timeout interdigito, o AfterPickup gerado sempre apos 1,5 segundos. Se estourar o timeout global, despreza todos os digitos recebidos. Corrigido problema de gravao e reproduo simultanea em GSM, que poderia causar travamentos.
Verso 2.70- 04/06/2004 Corrigido problema de verso que impedia o uso da voicerlib no VC++ e no PowerBuilder. Prompt - Corrigido problema de no interromper a reproduo de mensagens quando fosse esperado apenas 1 digito.
Histrico de Verses
15
O PlayFile agora detecta automaticamente o tipo de arquivo, baseado na extenso para .sig, .gsm e se for wave, detecta se PCM ou LeiMi. Isso permite uso de diversos formatos para reproduo sem preocupao para o programador. Se for utilizado uma extenso desconhecida, fica valendo o que est especificado no SetPlayFormat. Corrigido problema no MakeCall. Em algumas situaes o MakeCall jamais gerava o AfterMakeCall, fazendo com que a aplicao ficasse eternamente no estado de Calling.
Verso 2.69- 03/02/2004 Retirado atraso para gerao do evento de ring. Firmware agora manda o evento de ring apos o ring e no no inicio do Ring. Verso inicializada com zero. Para correta exibio da verso necessrio esperar um tempo (~500ms) aps o StartVoicerLib. O PlayCardinal agora permite falar em feminino, bastando passar um F no comeo do numero. Ex: 22 fala Vinte e dois. F22 fala Vinte e duas. Reforma na funo de extenso, tornando mais fluente, retirado uns "es" a mais, etc.. O PlayList gera erro se o primeiro arquivo tiver PauseBefore igual a zero. Estou evitando isso chamando o timer independente do tempo passado. Corrigido problema de saturao no SetRecordGain. Agora o ganho pode chegar at a dez, diminuindo a diferena entre os interlocutores. O padro 2 e deve ser utilizado caso a diferena entre as vozes na gravao seja muito grande. Novo mtodo SetFrequencyTime(smallint Duration) que permite alterar o tempo mnimo para deteco do tom de discagem. O padro 1500ms que permite detectar os tons de discagem padro. S dever ser alterado em casos de sinalizaes especficas do PABX. Corrigido problema de receber um RING aps o atendimento,
16
caso este tenha sido feito "em cima" do RING.
Verso 2.68- 24/11/2003 Includas funes para tratamento de conferencia. O timer geral foi reduzido de 100ms para 80ms tornando-o mais prximo da realidade. Corrigido problema de atraso no StopRecordFile. SetRecordGain - Ganho de gravao - de 1 a 10 ganho padro 4. Deteco de fax corrigida. Correo da reproduo nos valores por extenso. Ex.: Se informa-se 5,6 o sistema entender 5,60. Na reproduo de nmero digitado no prompt dado uma pausa de 400ms antes de comear a reproduzir os numeros. MakeCall agora detecta fax no evento OnAfterMakeCall. IMPORTANTE: O OnFaxDetected no mais chamado se o fax for detectado via AfterMakeCall. Criada constante mkFaxDetected (valor 8) que passada como parmetro no AfterMakeCall Melhorada consistencia de inicializao. Se outra aplicao estiver usando a mesma placa o StartVoicerLib voltar erro 9. Reformulao das rotinas de gravao da placa PCI/4 com significativa melhora na qualidade do audio
Verso 2.67 - 29/08/2003 Correo de erro no Windows98
Verso 2.66 - 26/08/2003 Novo setup, sem alteraes no funcionamento. Aumentado buffer de gravao para evitar truncamento.
Histrico de Verses
17
Verso 2.65 - 28/07/2003 Otimizao do gerenciamento de memria quando existe apenas 1 placa instalada, resolvendo o problema de cdigo 0 em mquinas com Windows 95 e 64MB de memria. Corrigido problema de instalao no Windows 98SE.
Verso 2.64 - 16/07/2003 Corrigido o problema das funes de Menu que no apaga o buffer de dgitos no caso de digitos invlidos antes de receber a opo correta. Foi corrigido o problema introduzido pela verso 2.63 que causava "zumbidos" eventuais na reproduo de arquivos em situaes com 4 ou mais canais.
Verso 2.63 - 24/06/2003 Novo formato de gravao com compresso - ffGsm610 Este formato gera arquivos de 1,65Kb/s de gravao (o Wave gerava 8Kb/s). A constante ffGsm610 equivale ao valor 3 e deve ser utilizada na propriedade FileFormat ou nos novos mtodos SetPlayFormat e SetRecordFormat. Novos mtodos SetPlayFormat e SetRecordFormat que permite utilizar formatos de gravao e reproduo independentes por canal. Como o novo formato GSM oferece uma qualidade de udio inferior ao Wave pode ser necessrio gravar em GSM e reproduzir mensagens no formato Wave. Com estes mtodos possvel manter formatos de gravao e reproduo diferentes no mesmo canal ou em canais distintos. Novos mtodos WaveToGSM e GsmToWave permitindo a converso de arquivos Wave (ffWave ou ffWavePCM) para o GSM ou do formato GSM para o WavePCM. Foram eliminados os mtodos ReadFifoToApp e
18
WriteFifoToCard que permitiam troca de amostras de udio entre a aplicao e a placa. Estes mtodos suportavam esta troca por apenas um canal. Para a prxima verso estaremos disponibilizando uma soluo completa para este tipo de funcionalidade suportando at 24 canais. Verso 2.62 - 14/05/2003 Novo device driver chamado kpvlib.sys/vxd Suporte Windows 2000 SP3 e Windows XP Pro SP1 Limites do Twist alterado para 0 e 99 Twist1 padro alterado para 10 Twist2 padro alterado para 0 Corrigido problema do PromptAbort que no interrompia o playback Retirado atende/desliga da inicializao para evitar desligamento de ligaes em curso caso fosse necessrio reativar o software. SetAnswerThreshold agora espera valores de 1 a 30 com valor padro 4, sendo que quanto maior o nmero, maior a sensibilidade, exatamente ao contrrio do que era antes... SetAnswerSensitivity modificado para o valor 6 ser o melhor possvel. Novo programa de instalao. Exemplos em Delphi corrigidos com consistncias melhoradas, vlib_diag melhorado, abrangendo a maioria das funes novas.
Verso 2.61 - 29/01/2003 Criao do mtodo SetToneTwist que ajusta a sensibilidade da deteco de tons. Foi criado para separar este efeito do SetDTMFTwist. Verso 2.60 - 03/12/2002
Histrico de Verses
19
Colocado um delay de 2 segundos para que o evento de ring seja gerado somente depois do RING efetivamente ocorrer. Isto evita situaes onde o evento de ring gerado no meio do ring. Verso 2.59 - 12/11/2002 Novas mudanas na deteco de atendimento - fator padro 6 para PCI/4 Bug no Timeout da funo MenuStart Corrigido - podia fazer com que o menu nunca desse timeout As funes que falam nmeros, datas, etc... agora verificam se fala o arquivo wave ou sig de acordo com a propriedade FileFormat. Corrigido erro de no falar zero em cardinal Novo mtodo SetAnswerThreshold que permite alterar o limiar para deteco de atendimento. Pode variar de 0 a 8192 -> se passar -1, no firmware o valor no alterado o valor padro 440 SetDTMFTwist - novo mtodo para alterar a sensibilidade da deteco de DTMF. Pode variar de 1 a 5 nos dois parmetros. O primeiro parmetro a distncia mxima entre as duas primeiras freqencias e o segundo parmetro a distncia entre as duas e a terceira freqencia. O valor padro no firmware 5 e 2, respectivamente. Corrigido erro no GetDigits que afetava o Prompt. Quando se digitava o digito de confirmao aps a mensagem, o GetDigits eliminava o digito da String deixando-a vazia. Agora o GetDigits s retira o terminador da string se ele no for o nico digito. Corrigido problema de timeout de bina no Idlexxxx. Se chegasse uma identificao e a ligao nunca fosse atendida, o Idlexxxx no pegava mais nada. Foi criado um timer de 6 segs aps o primeiro RING. Se estourar este timer sem a ligao ser atendida, os valores do bina so resetados (tmrTimeOutBINA). Verso 2.58 - 20/09/2002
20
Criao de um novo algoritmo para deteco de atendimento, tornando esta mais eficiente. O fator de sensibilidade de atendimento passou de 9 para 8. Aumento da sensibilidade de atendimento. Desta forma, os valores atualmente utilizados devero ser reavaliados.
Verso 2.57 - 02/08/2002 Novo parmetro PauseAfterDigit do mtodo SetCallStartFlash Novo parmetro DialType do mtodo Dial para determinar discagem por pulso ou tom independente por canal. A propriedade DialType se torna obsoleta e sem efeito. O mtodo MakeCall agora aceita nmero de flashes igual a zero. Timeout entre tons de chamando aumentado para evitar falsos atendimentos durante o MakeCall Novo parmetro mkDialToneAfterDial passado no evento OnAfterMakeCall. Este valor de status indica que foi recebido um tom de linha aps a discagem que indica provvel problema no PABX/Linha.
Verso 2.56 17/07/2002 Novo sistema de help on line Erro no timer do MakeCall corrigido. No dava timeout de tom de discagem. Criado parmetro novo no SetCallAfterAnswer. O AutoHangUp indica se, aps uma discagem do tipo Flash, desliga automaticamente quando detectado o atendimento. Se for false, gera o evento OnAfterMakeCall com mkAnswered porem o HangUp tem que ser dado na aplicao. Na inicializao da biblioteca, esta prevendo a PCI de 1 canal com PLX 9050 ou 9052 para evitar erros de instalao no Win
Histrico de Verses
21
98 Criado evento OnCallStateChange que permite monitorar a evoluo de um makecall Verso 2.54 20/05/2002 Possibilidade de ligar at 6 placas PCI por computador Novo mtodo SetAnswerSensitivity que permite customizar a sensibilidade de deteco de atendimento Corrigido problema de no deteco do dgito # durante a reproduo de frases Retirado obrigatoriedade de ter digito terminador no PromptStart Retirada obrigatoriedade de ter frase inicial no PromptStart O mtodo PromptStart estava apagando o buffer de dgitos (ClearDigits) automaticamente. Este controle deve ficar especificamente com o programador. Verso 2.5 26/03/2002 Suporte nova placa VoicerPhone PCI/1 Nova propriedade ForcePlay Correo no mtodo PlayTime quando tentava reproduzir horas com minutos igual zero. Correo de problema na propriedade CardType em designtime. Ao iniciar a biblioteca a propriedade era ignorada forando a atribuir o valor do tipo da placa no cdigo. Verso 2.4 09/01/2002 Bug nos mtodos SetDTMFAttenuatingHigh e SetDTMFAttenuatingLow corrigidos A propriedade FileFormat no era alterada caso fosse setada apenas em design-time permanecendo sempre com o valor ffWave. Problema corrigido Correo do mtodo Sig2Wave que deixou de funcionar corretamente na verso anterior.
22
Correo do envio de comandos para o hardware. Desta maneira no mais necessrio utilizar o Sleep para dar uma pausa entre cada comando na inicializao. Novos mtodos MakeCallxxxx que simplifica as funes de discagem/transferncia com ou sem superviso. Novos mtodos Menuxxxx que rene as funes de menu de atendimento em poucos parmetros. Novos mtodos Promptxxxx que simplificam as funes de entrada de dados com conferncia e consistncia do que foi digitado. Novos mtodos Idlexxxxx que renem funes de atendimento automtico e deteo de dgitos antes e depois do atendimento (BINA, sinalizao do PABX,etc...) Verso 2.3 06/11/2001 Pequenas correes nos procedimentos de instalao Software de Diagnsticos corrigido Mudana internas nos procedimentos de interrupo de gravao, visando corrigir problemas de gravao quando uma gravao era interrompida e outra iniciada rapidamente. Verso 2.2 20/10/2001 Implementado o mtodo RecordPause, permitindo suspender a gravao e em seguida retom-la. Correo do parmetro TermDigits do GetDigits, PlayFile, etc... que estava sendo utilizado como Filtro de dgitos e no como digitos terminadores. Implementada a funo de falar nmero digito a digito, atravs do mtodo PlayNumber. Foi criado um mtodo chamado PlayCardinal para falar os nmeros cardinais (ex PlayNumber). No PlayListxxxx foi criado um tipo ptNumber para suportar este novo tipo. Implementado suporte a gravao de mensagens em formato wave definido pela propriedade FileFormat. Todas as placas e todos os canais devero funcionar com o mesmo formato obrigatoriamente.
Histrico de Verses
23
Verso 2.1 12/09/2001 Corrigido problema de no zerar a varivel Duration do evento evento OnRecording a cada RecordFile Corrigido problema de travamento da placa ISA no Windows 2000 em certas condies Adicionado um exemplo de atendimento automtico em VB 6.0 Adicionado os fontes de um programa para converso de arquivos Wave para SIG em lote, feito em Delphi. Adicionados arquivos SIG padro para as funes de reproduo de extenso, data, etc. Disponveis no diretrio StockSigs do CD. Corrigido problema de converso de arquivos Wave para SIG quando os waves so gerados com programas que adicionam informaes no final do arquivo (ex.: SoundForge), o que causava "estalos" no final arquivo SIG Implementados novos mtodos para falar valores por extenso, numerais cardinais, data e hora. Implementados mtodos para tratamento de listas de mensagens. Se for detectado um dgito durante a reproduo de mensagens, alm de gerar o evento OnPlayStop, tambm gerado o evento OnDigitsReceived com o parmetro edDigitOverMessage permitindo que o tratamento de entrada de dados seja feito em um lugar apenas. Verso 2.0 01/08/2001 Nova verso com suporte a placa PCI e mltiplas placas por micro
Parte
III
Iniciando
26
3
3.1
Iniciando
Cabos & Conectores
VoicerPhone ISA/PCI/1 Existem 3 conectores na placa, conforme mostrado na figura 1: Linha, Aparelho e HeadSet.
VoicerBox PCI/4
Iniciando
27
Caso a placa VoicerBox PCI/4 seja destinada a funes de atendimento automtico, URA, etc... basta conectar as linhas ou ramais diretamente em cada uma das 4 entradas disponveis. No caso de Gravao Digital da conversao, a VoicerBox PCI/4 ficar posicionada entre o trono e o destino (telefone ou PABX). Neste caso necessrio utilizar um cabo em "Y" j que a entrada e a sada da linha dar-se- pelo mesmo conector. Este cabo "Y" utilizar 4 fios, sendo dois para a entrada e dois para a sada, conforme pode ser observado no esquema abaixo:
3.2
Descrio do Produto
A VoicerLib uma biblioteca contendo um componente ActiveX. Este componente fornece um acesso de alto nvel para as placas Digivoice. Atualmente a VoicerLib suporta a placa VoicerPhone ISA ou PCI (1 canal) e a VoicerBox PCI (4 canais), sendo possvel gerenciar at 1 placa ISA ou 6 PCI em um mesmo equipamento. A partir da verso 2.5 possvel utilizar tambm a nova placa PCI/1 que vem substituir a placa ISA.
28
Sempre quando uma funo for relacionada com a placa ISA assumir que esta funo tambm funcionar na PCI/1, exceto s relativas interrupo e endereo de I/O Como principais funes podemos destacar: Atendimento e Desligamento Gravao e Reproduo de Mensagens Controle de Ganho (Volume) Deteco de Pulso e Tom Discagem por Pulso e Tom Controle de Microfone e Fone individuais, etc.
Na biblioteca foram includos exemplos de aplicao para Delphi e Visual Basic.
3.3
Instalando a Biblioteca
A VoicerLib distribuida em um CD. Ao colocar o CD na unidade, aparecer uma tela inicial mostrando as opes de instalao. Caso esta tela inicial no aparea automaticamente, execute o programa IntroCD.exe no diretrio raiz (usualmente D:\). Opes da Tela Inicial: Instalar a VoicerLib - permite instalar a biblioteca de desenvolvimento e programas exemplo na mquina onde os aplicativos sero desenvolvidos Instalar o Driver - Esta opo deve ser utilizada somente para instalar o device driver nas mquinas onde a aplicao ser utilizada. ATENO: A licena de uso da VoicerLib permite a instalao somente no ambiente de desenvolvimento
Iniciando
29
portanto instalando-a em mquinas de produo voc estar violando a licena de uso. Utilize sempre a opo Instalar o Driver nas mquinas dos clientes. Ao executar o programa de instalao aparecero as instrues. Basta seguir as telas que a VoicerLib instalar normalmente. Aps a instalao ser criado um grupo de programa Digivoice VoicerLib 2.0 com alguns atalhos que sero explicados logo adiante. Procedimentos de Instalao Instalao Nova (Em uma mquina que nunca teve verses anteriores da VoicerLib e/ou Kit Integrador.) 1. Desligar o computador, desconectando o cabo de fora da tomada 2. Conectar fisicamente a placa em um slot PCI disponvel 3. Ligar o computador. 4. Se o Windows reconhecer o novo hardware, cancele a instalao do mesmo 5. Execute o setup.exe que se encontra na pasta Driver 6. Durante a instalao podem ocorrer alguns eventos dependendo da plataforma utilizada: a. Win98/Me Durante a instalao ser pedido o Disco de Instalao Digivoice. Neste caso, aponte para a pasta c:\arquivos de programas\VoicerLib2 pois l esto todos os arquivos necessrios para a correta instalao. b. Win95 - No mais suportado pela VoicerLib. c. WinNT - No mais suportado pela VoicerLib. d. Win2000/2003/XP Todo o processo nestas verso automatizado mas durante a instalao o Windows mostrar
30
que est instalando um driver no certificado. Esta certificao um procedimento burocrtico da Microsoft, portanto basta reponder SIM cada vez que a pergunta aparecer. Caso o progresso de instalao fique parado por muito tempo, possvel que uma destas janelas tenha aparecido atrs do programa de instalao. Na dvida, d um Alt+Tab para ver se no h nada por trs. Em alguns casos pode ser pedido o disco de instalao. Caso isso ocorra, aponte para a pasta c:\arquivos de programas\VoicerLib2 pois l esto todos os arquivos necessrios para a correta instalao. Atualizao (Em uma mquina com verses anteriores da VoicerLib/Kit Integrador instaladas) 1. No Gerenciador de Dispositivos (Painel de Controle -> Sistemas) remover (desinstalar) todas as ocorrncias dos dispositivos VoicerPhone PCI/1, VoicerBox PCI/4 e Windriver. 2. Execute o setup.exe que se encontra na pasta Driver (Kit Integrador) ou na pasta Instalar (VoicerLib) 3. Durante a instalao podem ocorrer alguns eventos dependendo da plataforma utilizada: Win98/Me Durante a instalao ser pedido o Disco de Instalao Digivoice. Neste caso, aponte para a pasta c:\arquivos de programas\VoicerLib2 pois l esto todos os arquivos necessrios para a correta instalao. Win2000/2003/XP Todo o processo nestas verso automatizado mas durante a instalao o Windows mostrar que est instalando um driver no certificado. Esta certificao um procedimento burocrtico da Microsoft, portanto basta reponder SIM cada vez que a pergunta aparecer. Caso o progresso de instalao fique parado por muito tempo, possvel que uma destas janelas tenha aparecido atrs do programa de instalao. Na dvida, d um Alt+Tab para ver se
Iniciando
31
no h nada por trs. Em alguns casos pode ser pedido o disco de instalao. Caso isso ocorra, aponte para a pasta c:\arquivos de programas\VoicerLib2 pois l esto todos os arquivos necessrios para a correta instalao. Importante: O Windows 2000/XP tem a tendncia de utilizar os INFs que j esto na pasta Windows\INF ao invs dos novos fornecidos para esta verso. Para garantir que tudo esteja atualizado, v ao Gerenciador de Dispositivos onde aparece as placas Digivoice, escolha a opo Propriedades e depois na tela que aparece, a opo Atualizar/Reinstalar Driver. Neste caso aponte explicitamente para c:\arquivos de programas\VoicerLib2. Todos os dispositivos Digivoice devero aparecer com um (*) no final do seu nome. Observaes Importantes: O programa vlib_diag instalado na pasta Windows, portanto pode ser executado diretamente pelo Menu Iniciar -> Executar Se existir placas de barramento ISA, no se esquea de executar o programa GeraIni.exe para configurar a interrupo e endereo de I/O. Nunca instale ou remova uma placa com o computador conectado na rede eltrica, mesmo desligado. Para instalar o Kit Integrador sem que aparea as janelas de dilogo, execute setup.exe /silent ao invs de setup.exe /q
3.4
Instalando o Hardware
Cuidado! Certifique-se de estar habilitado para executar a instalao do Hardware. O Computador dever estar desligado. A instalao diferenciada para a verso ISA ou PCI.
32
Ignore a explicao da verso diferente da sua. VERSO ISA A placa VoicerPhone ISA exige que voc configure manualmente a Interrupo e o Endereo de I/O que ela usar para se comunicar com o computador. Sai de fbrica utilizando a Irq7 e o Endereo de I/O 2a0h. A tabela 1 mostra a posio dos jumpers na placa. Tabela 1
Figura 1 Certifique-se que a Interrupo no esteja sendo utilizada por outro dispositivo atravs do Painel de Controle Sistema Gerenciador de Dispositivos Meu Computador Propriedades.
Iniciando
33
Para instalar a Placa Voicer Box ISA: 1. Desligue e desconecte a energia do seu computador. 2. Remova a tampa do gabinete do seu computador. 3. Escolha um slot ISA de 16 bits e remova a tampa do slot (pequena tampa de metal na parte traseira do computador). 4. Segure a placa pelo topo (figura 2a) colocando-a no slot at estar completamente encaixada. No toque os contatos dourados da placa pois qualquer impureza nos contatos pode prejudicar o funcionamento do equipamento.
Figura 2a
34
5. Fixe a aleta da placa no gabinete do seu computador com um parafuso de fixao. 6. Recoloque a tampa do seu computador. Ao religar o computador, a placa no ser identificada pelo Windows por no ser uma placa ISA Plug & Play. Isto no afetar o seu funcionamento. VERSO PCI Para instalar a Placa Voicer Box PCI/4 ou Voicer Phone PCI/1: 1. Desligue e desconecte a energia do seu computador. 2. Remova a tampa do gabinete do seu computador. 3. Escolha um slot PCI de 32 bits e remova a tampa do slot (pequena tampa de metal na parte traseira do computador). 4. Segure a placa pelo topo (figura 2a) colocando-a no slot at estar completamente encaixada. No toque os contatos dourados da placa pois qualquer impureza nos contatos pode prejudicar o funcionamento do equipamento. 5. Fixe a aleta da placa do Voicer Box no gabinete do seu computador com um parafuso de fixao. 6. Recoloque a tampa do seu computador. A placa PCI no tem jumpers de configurao pois os recursos necessrios so alocados automaticamente pelo computador no momento do boot. 7. Ligue o computador. 8 O Windows detectar automaticamente a placa VoicerBox PCI/4 normalmente identificando-a como Dispositivo de udio . Ao aparecer a tela de procura de Driver, aponte para o CD na pasta Driver\InfParaPCI . Desta maneira o Windows detectar e instalar a placa corretamente. Caso a mquina no tenha unidade de CD disponvel, copie o contedo da pasta Driver\InfParaPCI do CD para um disquete e utilize-o. Para instalar placas PCI no seu cliente, leia o captulo Distribuindo sua Aplicao.
Iniciando
35
3.5
Preparando o Ambiente
Considerando que a placa (ISA ou PCI) j est instalada no computador,o prximo passo ser test-la atravs do programa de Diagnstico que foi fornecido junto com a biblioteca. Placa ISA No caso da placa ISA, necessrio configurar o Windows com a quantidade de placas, interrupes e endereos de I/O utilizados. Isto possvel atravs do utilitrio Configurar placas ISA que pode ser acessado atravs do grupo de programas Digivoice VoicerLib 2.0. Lembre-se de verificar se no h conflitos de interrupo com outro hardware instalado. Ao clicar no atalho Configurar placas ISA aparecer a seguinte tela:
36
Para adicionar uma placa selecione a Interrupo e o endereo de I/O desejado e clique no boto ">>" . Para remover, selecione a placa desejada na lista de Placas Instaladas e clique no boto Remover. Para gravar a configurao, clique no boto OK. Placa PCI/4 ou PCI/1 No necessrio executar o programa Configurar placas ISA para as placas PCI pois a interrupo e endereo de I/O so atribudos automaticamente. Testando o Hardware Para testar a placa instalada, execute o Programa de Diagnsticos encontrado no grupo de programa Digivoice VoicerLib 2.71.Ele tem a seguinte interface:
Iniciando
37
Para inicializar o hardware, primeiro selecione o tipo de placa instalada (ISA ou PCI) e clique no boto Inicia Driver. Devido ao maior rigor na inicializao do hardware, este processo ficou ligeiramente mais lento que na verso 1.x Caso ocorra alguma falha, voc receber uma mensagem com um cdigo:
38
Para saber o significado dos cdigos de erro, consulte o mtodo StartVoicerLib no captulo Guia de Referncia. Caso a inicializao seja feita com sucesso, voc poder testar as funes de Atende e Desliga, discagem, etc... Lembre-se de conectar uma linha ou ramal na placa antes de efetuar os testes. Algumas funes so pertinentes somente a placa VoicerPhone ISA e portanto no tem efeito nas placas PCI. Maiores detalhes sobre isso no captulo Tpicos de Programao. Nas placas ISA, caso o programa inicie corretamente, mas ao clicar no boto Atende e Desliga voc no obtiver resposta possvel que a interrupo esteja configurada incorretamente ou em conflito com outro hardware.
3.6
Requisitos Mnimos
A princpio a VoicerLib rodar em qualquer plataforma que comporta o Windows com performance, entretanto, para melhor utilizao recomendamos: Windows 95/98/Me/NT 4/2000/XP Pentium 233Mhz 64MB de memria
Iniciando
39
5MB de espao livre em disco Slots ISA (VoicerPhone) ou PCI (PCI/1 ou PCI/4) disponveis Delphi 5 ou maior e Visual Basic 6 ou maior. Importante: O cdigo da biblioteca foi otimizado para rodar em mquinas Pentium, portanto o sistema no funcionar em 486 ou menor. Mquinas Cyrix ou AMD compatveis com Pentium no tero problemas.
Parte
IV
Tpicos de Programao
42
4
4.1
Tpicos de Programao
Estrutura Bsica de Funcionamento
O 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 vrios canais simultaneamente. Se a aplicao ficasse presa na execuo de um mtodo, no conseguiria tratar os outros eventos dos outros canais. Lembre-
Tpicos de Programao
43
se que possvel que um canal esteja reproduzindo a mensagem enquanto outro esteja recebendo um ring. Como esta forma de programar um pouco diferente da que a maioria dos programadores sem experincia em aplicaes de telefnia em tempo real esto acostumados, recomenda-se ler todo este captulo: Aplicao Exemplo Passo a Passo e estudar os exemplos fornecidos.
4.2
Inicializando os Servios
Sempre que iniciar a aplicao, antes de executar qualquer mtodo, necessrio iniciar os servios (device driver). Isto pode ser feito atravs do mtodo StartVoicerLib. possvel verificar se os servios do hardware foram iniciados corretamente atravs do retorno da funo que deve ser 99. Os outros cdigos de erro podem ser consultados no Guia de Referncia deste manual. Exemplo:
Private Sub Form_Load() Dim x as Long 'Inicia device driver x = VoicerLibX1.StartVoicerLib 'se for diferente de 99 significa que deu erro If x <> 99 Then MsgBox "No foi possvel inicializar a placa", vbOKOnly, "Erro" End End Sub
Como a inicializao a primeira coisa a ser feita, recomendase sua colocao no incio da aplicao.
44
4.3
Finalizando os Servios
Antes de fechar a aplicao necessrio chamar o mtodo ShutdownVoicerLib, que finaliza todos os servios e reseta a placa. Caso o mtodo no seja chamado, recursos de memria continuaro alocados mesmo aps a finalizao do aplicativo. Neste caso ser necessrio reiniciar o computador para que estes recursos sejam liberados. A no utilizao do mtodo ShutdownVoicerLib poder causar travamento no Windows ou algum comportamento imprevisvel. possvel verificar se os servios do hardware foram finalizados corretamente atravs do retorno da funo, que deve ser 99. Exemplo:
Private Sub Form_UnLoad() Dim x as Long 'Finaliza device driver x = VoicerLibX1.ShutdownVoicerLib 'se for diferente de zero significa que deu erro If x <> 99 Then MsgBox "No foi possvel finalizar a placa" + _ " corretamente. Reinicie o micro", _ vbOKOnly, "Erro" End End Sub
O melhor local para se colocar esta funo em algum evento finalizador, que antecede o encerramento da aplicao (Unload, OnClose, etc...).
Tpicos de Programao
45
4.4
Detectando Ring
A VoicerLib permite detectar quando tem uma ligao entrante chegando atravs do ring. Sempre quando o ring for detectado, o evento OnRingDetected gerado. Exemplo:
'Chegou o ring, ento atende Private Sub VoicerLibX1_OnRingDetected(Port As Integer) lblStatus.Caption = "RING!! Atendi!!!" VoicerLibX1.PickUp(1) End Sub
Como o Ring ocorre em situaes bem especficas a sua deteco est sempre habilitada no havendo mtodos para ligar ou desligar.
4.5
Atendendo e Desligando
Para 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. O captulo Aplicao Exemplo Passo a Passo explicar bem esta relao. Para desligar a ligao, o mtodo utilizado o HangUp. Deve ser passado somente a porta que se deseja desligar.
46
Exemplos:
'Atende a ligao ou toma a linha para discar na porta 3 Private Sub cmdAtende_Click() x = VoicerLibX1.PickUp(3,0) 'sem pausa End Sub 'Desliga a linha Private Sub cmdDesliga_Click() x = VoicerLibX1.HangUp(3) End Sub
A varivel "x" nos exemplos recebe zero se os comandos foram executados com sucesso. Para deixar o aplicativo mais completo, recomenda-se testar "x" sempre. No caso da placa Voicer Phone, ao tomar a linha (PickUp) da primeira vez que o aplicativo executado, o usurio provavelmente no ouvir nada, pois o microfone e o fone do headset estaro desabilitados.
4.6
Superviso de Linha
A 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 Deteco de sinal de chamada Deteco de Atendimento
importante ressaltar que no aconselhvel ficar com estes sinais habilitados o tempo todo, porque possvel que acontea uma interpretao errada por parte do hardware. Uma situao tpica que esclarece bem a questo com relao deteco
Tpicos de Programao
47
de atendimento. Ela deve ser habilitada somente no momento que voc quiser detectar o atendimento, que via de regra seria aps a discagem, e desabilitada logo aps o atendimento ter sido detectado. Como o atendimento detectado atravs de certos rudos na linha, se a deteco estiver habilitada durante a conversao, por exemplo, um rudo qualquer durante a conversa pode ser entendido como atendimento. Isto vale para todos os tipos de deteco, portanto, sempre mantenha habilitada a deteco que seja necessria em um determinado momento. Sempre quando um destes sinais for detectado, o evento correspondente ser chamado. O sinal de ocupado, fax, tom de discagem e chamada so controlados pelos mtodos EnableCallProgress e DisableCallProgress. J a deteco de atendimento controlada em separado pelos mtodos EnableAnswerDetection e DisableAnswerDetection. A partir da verso 2.61, o mtodo SetToneTwist permite controlar a sensibilidade de deteco destes tons quando gerados em cima de uma mensagem. Este mtodo deve ser utilizado caso a deteco de tons (notadamente o ocupado) esteja gerando situaes de talk-off Sinal de Ocupado Ao ser detectado o sinal de ocupado, o evento OnBusyDetected gerado, podendo ser tratado pelo usurio da maneira como quiser. O evento gerado sempre que for detectado o ocupado, portanto, caso o sinal de ocupado permanea por muito tempo sem desligar, o programa desviar vrias vezes para o OnBusyDetected. Uma sada logo aps o primeiro ocupado, desabilitar a deteco com o mtodo DisableCallProgress.
48
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. sempre recomendado no fazer tratamentos muito demorados dentro das rotinas que manipulam os eventos para evitar que a biblioteca perca outros eventos que possam chegar em seguida. NUNCA chame MessageBox ou outras janelas modais de dentro destes eventos. Exemplo:
Private Sub VoicerLibX1_OnBusyDetected(Port As Integer) lblStatus.Caption = "Sinal de Ocupado..." VoicerLibX1.DisableCallProgress 1 End Sub
Deteco de Fax A 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. Exemplo:
Private Sub VoicerLibX1_OnFaxDetected(Port As Integer) lblStatus.Caption = "Transferindo para o Fax..." 'executa comando de flash para transferencia VoicerLibX1.Flash(1,600,1000) 'disca para o ramal do fax
Tpicos de Programao
49
VoicerLibX1.Dial(1,"202',1000) End Sub
Deteco de Atendimento A VoicerLib permite ao programador detectar quando uma ligao foi atendida do outro lado da linha. Os mtodos EnableAnswerDetection e DisableAnswerDetection controlam a ocorrncia ou no deste evento. O evento OnAnswerDetected gerado sempre quando este sinal for detectado. Uma aplicao exemplo seria uma rotina esperar o atendimento para ento discar o nmero do ramal desejado Exemplo:
Private Sub VoicerLibX1_OnAnswerDetected(Port As Integer) 'Primeiro desabilita a detecao para nao entrar aqui 'de novo VoicerLibX1.DisableAnswerDetection(1) lblStatus.Caption = "Atendeu, discando para o ramal" VoicerLibX1.Dial(1,"220',0) End Sub
A deteco de atendimento pode ter sua sensibilidade alterada atravs do mtodo SetAnswerSensitivity. Nele possvel passar parmetros de 1 (menos sensvel) at 10 (mais sensvel). O padro 6. A variao de sensibilidade pode ser necessria em situaes onde esteja difcil de pegar o atendimento ou o outro extremo: estar detectando atendimento falso. Deteco de sinal de discagem O sinal de discagem aquele tom contnuo que se houve ao tirar o fone do gancho. Em alguns casos, este sinal pode demorar alguns segundos, principalmente em centrais
50
congestionadas. Este evento controlado pelos mtodos EnableCallProgress e DisableCallProgress. O evento OnDialToneDetected gerado sempre quando este sinal for detectado. 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. Exemplo:
'Habilita Superviso de linha 'e toma a linha para discar a partir do click do boto Private Sub cmdAtende_Click() VoicerLibX1.EnableCallProgress(1) x = VoicerLibX1.PickUp(1,0) End Sub 'Quando o tom de discagem for detectado 'esta rotina chamada Private Sub VoicerLibX1_OnDialToneDetected(Port as Integer) 'disca VoicerLibX1.Dial("0,72952557") End Sub
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
Tpicos de Programao
51
ser atendida. Exemplo:

Private Sub VoicerLibX1_OnCalling(Port As Integer) nToques = nToques + 1 lblStatus.Caption = "Chamando... " & nToques if nToques = 5 then VoicerLibX1.HangUp(1) End if End Sub
Neste exemplo, aps o 5 toque, o sistema desiste e desliga. (Supor que existe uma varivel global chamada nToques inicializada com zero)
4.7
Deteco de Dgitos
A VoicerLib permite detectar dgitos tanto em tom como em pulso, entretanto a deteo de pulso desabilitada por default podendo ser habilitada pelo mtodo EnablePulseDetection e desabilitada pelo mtodo DisablePulseDetection. A deteo por tom esta sempre habilitada e disponvel. No h como desabilit-la O funcionamento das duas detees praticamente o mesmo exceto pelo fato que a deteo de tom pode ser feita durante a reproduo de uma mensagem e a de pulso somente no silncio aps a mensagem. Habilite a deteo de pulso somente quando for necessrio, pois caso contrrio, uma deteo de pulso habilitada, por exemplo, durante a reproduo pode causar inmeros talk-offs A VoicerLib permite tratar o reconhecimento de dgitos de duas
52
maneiras diferentes. A primeira atravs do evento OnDigitDetected, que gerado sempre que um digito 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 de saber o momento em que ele ocorreu, pois a deteco neste caso estar habilitada o tempo todo. uma maneira pouco recomendada por causa problema de talk-off que pode ocorrer durante o atendimento. TALK-OFF: A voz humana, em uma conversa normal, pode conter a mesma freqncia 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 ter algum mal funcionamento operacional. Para mensagens faladas atravs de arquivos SIG, o problema de talk-off no ocorre, pois o hardware consegue filtrar as freqncias conhecidas. Uma aplicao tpica que se recomenda a utilizao do evento OnDigitDetected na identificao de chamadas. Leia mais no tpico Identificao de Chamadas logo a seguir. 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 " +
Tpicos de Programao
53
Chr$(voicerlibx1.ReadDig its(Port)) End Sub
A segunda maneira de detectar dgitos atravs do mtodo GetDigits. O mtodo GetDigits inicia a monitorao de dgitos, sendo que possvel determinar o nmero mximo de dgitos, se esperar um digito 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. 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. A propriedade AutoClearDigits tambm interfere no funcionamento do mtodo GetDigits, ou seja, se esta propriedade estiver true (default), os dgitos so apagados dos buffers internos dos canais quando o GetDigits for chamado; se estiver false os dgitos permanecero at ser chamado o mtodo ClearDigits(Porta). Se for necessrio apagar a propriedade Digits manualmente, utilize o 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:
54
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) Select Case Status Case edMaxDigits: 'Alcanou o mximo de digitos, disca para o ramal '...... Case edTermDigit: 'Recebeu um nmero com # no fim '...... Case edDigitTimeOut: 'Time out global de 10 segundos '...... Case edInterDigitTimeOut: 'Deu time-out 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. A deteco de DTMF sai com um nvel de sensibilidade que funcionar em 99% das instalaes. Podem existir situaes extremas nas quais a deteco pode parecer muito ou pouco sensivel. Neste caso, o programador poder fazer uso do mtodo SetDTMFTwist que permite alterar a sensibilidade desta deteco.
Tpicos de Programao
55
O padro DTMF composto de um par de freqncias (tons) para cada dgito discado que chamaremos respectivamente de F1 e F2. Devido s caractersticas da linha telefnica e dos equipamentos a elas ligados, as amplitudes destes tons podem ter atenuaes diferentes na propagao pela rede telefnica. A presena de udio juntamente com o par de tons do DTMF (quando a placa est falando uma mensagem) pode prejudicar sua deteco pois gera novos tons F3, junto com F1 e F2. O parmetro TWIST1 diz respeito tolerncia na diferena de amplitude entre as duas freqncias do DTMF F1 e F2. Quanto maior o valor de TWIST, maior a tolerncia a variaes de amplitude entre as duas freqncias ou mais fcil ser a deteco de digitos (podendo at chegar em situaes de talkoff). Quando necessrio, o ajuste desta varivel deve ser feito sem que a placa esteja falando. O parmetro TWIST2 diz respeito seletividade de uma terceira freqncia F3 com relao s duas freqncias, F1 e F2 presentes no udio recebido pela placa, isto quer dizer que quanto menor o valor de TWIST2, maiores podero ser as amplitudes das outras freqncias presentes no udio sem que seja rejeitada a deteco de DTMF, ou seja, os valores menores aumentam a sensibilidade de DTMF podendo chegar at situaes de talk-off. Os dois valores devero ser ajustados empiricamente em situaes que os dgitos no estejam sendo detectados a contento ou, no outro extremo, em situaes de talk-off.
56
4.8
Discagem
A plataforma Digivoice permite discagem por Tom (DTMF) ou Pulsos, permitindo a utilizao de aplicaes baseadas em qualquer tipo de instalao ou central pblica. O mtodo utilizado para discagem o Dial que basicamente necessita da porta, de uma string contendo o nmero a ser discado, da pausa aps a discagem e do tipo de discagem (Pulso ou Tom).
x = VoicerLibX1.Dial(1,"72952557",1000, dtTone)
O tipo de discagem permite cada canal discar por pulso ou tom de forma independente, sendo que o parmetro pode assumir o valor dtTone para Tom (DTMF) ou dtPulse para Pulso (Decdico). Em algumas situaes necessrio dar pausas entre cada dgito. Um caso tpico a ligao externa atravs do PABX que necessrio discar "0" e em seguida discar o nmero de destino. A VoicerLib disponibilizou trs smbolos que podem ser utilizados dentro da string do nmero que indicaro ao sistema para esperar "n" milissegundos antes de prosseguir. Estas propriedades so: DelayDot, DelayComma e DelaySemicolon que definem a pausa para, respectivamente, o "ponto", a "vrgula" e o "ponto-e-vrgula". O valor da pausa deve ser expresso em milissegundos, isto , para esperar 1 segundo, atribuir o valor 1000. No exemplo abaixo mostrado um caso onde setado a discagem por pulso e utilizado a vrgula como smbolo de pausa para efetuar uma ligao externa:
Sub cmdDisca_Click()
Tpicos de Programao
57
VoicerLibX1.DelayComma = 1000 VoicerLibX1.Dial(1,"0,72952557",1000, dtPulse) End Sub
Neste outro exemplo, aps a discagem do nmero, o sistema esperar 5 segundos para poder discar o ramal.
Sub cmdDisca_Click() VoicerLibX1.DelayComma = 1000 VoicerLibX1.DelayDot = 5000 VoicerLibX1.Dial(1,"0,72952557.220",1000, dtTone); End Sub
Alm das pausas atravs das propriedades Delayxxx, existe a pausa aps discagem (3. Parmetro) que tambm representado em milissegundos. Este parmetro deve ser utilizado principalmente em casos de transferncia com superviso, pois existem centrais que geral rudos aps a discagem atrapalhando a deteo de atendimento, por exemplo. Se este parmetro estiver com valor maior que 0 o evento OnAfterDial s ser gerado aps acabar a discagem e a pausa. Como a discagem pode demorar vrios segundos, a VoicerLib disponibiliza o evento AfterDial, que gerado sempre quando um mtodo Dial acabar de discar todos os nmeros e pausas. Isto muito til para habilitar alguma superviso de linha necessria aps a discagem, como por exemplo, a deteco de atendimento (maiores detalhes sobre superviso no tpico seguinte). Aproveitando o exemplo anterior, aps a discagem possvel fazer algo como no exemplo a seguir:
Sub frmExemplo.VoicerLibAfterDial() 'Acabou de discar espera atendimento VoicerLibX1.EnableAnswerDetection 1 End Sub
58
Obs.: At a verso 2.56, a propriedade DialType determinada o tipo de discagem. A partir da verso 2.57 esta propriedade tornou-se obsoleta e o tipo de discagem deve ser passado em toda chamada ao mtodo Dial.
4.9
Configuraes de DTMF
As placas Digivoice j saem de fbrica ajustadas para ser compatvel com o maior nmero de centrais possveis, entretanto possvel que existam situaes que o tom gerado pela placa, principalmente nas discagem no PABX, possam no ser compreendidas. Para que os sistemas desenvolvidos com a Voicer Lib possam atender 100% dos equipamentos, existem alguns mtodos que permitem ajustar certos aspectos do tom gerado pela placa. O mtodo SetDTMFDuration permite modificar a durao de um tom, que iniciada em 100 milisegundos. Normalmente este tempo funcionar sem problemas mas o programador poder ajustar esta durao conforme a necessidade. O mtodo SetDTMFPause permite determinar a pausa interdigitos em uma discagem por tom. Isso s vlido quando o nmero passado completo no mtodo Dial. Tambm tem como valor default 100 ms. Os tons DTMF so gerados a partir de pares de freqncias pr-estabelicidas em normas internacionais. Os mtodos SetDTMFAttenuatingHigh e SetDTMFAttenuatingLow permitem determinar ndices de atenuao para cada uma destas duas freqncias. Por padro a freqncia alta iniciada com 4 dB de atenuao e a freqncia baixa em 6 dB. Normalmente estes valores sero suficientes mas caso haja problemas na deteo de tons por
Tpicos de Programao
59
parte do PABX, estes valores podero ser ajustados entre 0 e 50 dB. Na prtica, a diferena entre as duas freqncias no pode exceder 4 dB, ou seja, se a freqncia alta estiver com atenuao de 1 dB, a freqncia baixa no poder estar com atenuao maior que 5 dB. Se os dois valores estiverem em zero, significa que no h atenuao nenhuma. Lembre-se: Na maioria dos casos estes valores no devero ser alterados. Somente recorra a eles se a sua central no entender os tons de discagem.
4.10
Controle de Volume
A placa VoicerPhone permite que o usurio controle o ganho do udio em trs nveis, sendo que j vem com o nvel intermedirio (voTwo) como padro. Este ganho refere-se apenas ao headset do usurio, no tendo efeito na reproduo ou gravao de mensagens. O controle de ganho ou volume pode ser feito em qualquer momento, mesmo durante uma conversa. Para alterar o volume, utilize o mtodo SetVolume que pode assumir voOne, voTwo ou voThree. interessante disponibilizar este controle para o usurio final, pois existem grandes variaes na qualidade de udio de instalao para instalao. Exemplo: Neste exemplo, utilizamos o controle Slider do Visual Basic para aplicar o volume.
60
Private Sub trkVolume_Change() 'Modifica Volume de Acordo com a posio do slider Select Case trkVolume.Value Case 1 VoicerLibX1.SetVolume(voOne) Case 2 VoicerLibX1.SetVolume(voTwo) Case 3 VoicerLibX1.SetVolume(voThree) End Select End Sub
4.11
Microfone
Como foi dito anteriormente, a placa VoicerPhone tem tratamentos diferenciados para o microfone do headset. Como padro, o microfone est desabilitado, portanto o interlocutor do outro lado da linha no poder ouvir o que o usurio fala. Para habilitar o microfone, basta chamar o mtodo MicOn e para desabilitar, MicOff. Assim como os mtodos PhoneOn e PhoneOff, possvel colocar os mtodos MicOn e MicOff em qualquer ponto do programa. Tambm possvel associ-los a um boto com a funo de MUTE, permitindo que o interlocutor fique em espera sem ouvir o que o usurio fala. Exemplo:
'Liga MUTE Interlocutor no pode ouvir nada Private Sub cmdMUTEON_Click() x = VoicerLibX1.MicOff(1)
Tpicos de Programao
61
End Sub 'Desliga MUTE Interlocutor ouve Private Sub cmdMUTEOFF_Click() x = VoicerLibX1.MicOn(1) End Sub
Importante: As funes para microfone e fone no funcionam para o telefone, somente para o headset.
4.12
Fone do Headset
A placa VoicerPhone tem tratamentos diferenciados para o fone e o microfone do headset. Como padro, o fone est desabilitado, portanto o usurio no poder ouvir nada (voz, tom de discagem, ocupado, etc...). Para habilitar o fone, basta chamar o mtodo PhoneOn e para desabilitar, PhoneOff. Isso pode ser feito associado a um boto por exemplo, ou ainda o programador pode automaticamente habilitar o fone quando uma ligao atendida e desabilit-lo quando a ligao finalizada. Exemplo:
'Atende a ligao e habilita o fone Private Sub cmdAtende_Click() x = VoicerLibX1.PickUp(1,0) if x = 0 then 'Liga o fone VoicerLibX1.PhoneOn(1) End if End Sub 'Ao desligar, desabilita Private Sub cmdDesliga_Click() x = VoicerLibX1.HangUp(1)
62
if x = 0 then 'Liga o fone VoicerLibX1.PhoneOff(1) End if End Sub
4.13
Gravando uma Conversa
A VoicerLib permite gravar qualquer conversa tanto pelo headset como pelo monofone (aparelho comum). Para isso necessrio chamar o mtodo RecordFile onde voc deve informar o nome do arquivo que ser criado. O sistema utiliza o formato SIG ou o formato Wave (8 Bits, Mono, 8 Khz). Alm disso, possvel determinar se algum dgito ser utilizado como finalizador de gravao. Esta caracterstica permite uma implementao do tipo: "Grave seu recado e ao final digite # se quiser falar com a telefonista". O dgito detectado (se usado) armazenado na propriedade Digits, e pode ser tratado posteriormente. Dependendo do fluxo de operao do sistema desenvolvido, necessrio que a propriedade Digits v acumulando os digitos detectados. Neste caso necessrio mudar a propriedade AutoClearDigits para false, pois o padro true faz com que a propriedade Digits seja automaticamente apagada quando uma gravao iniciada. Sempre quando for iniciada a gravao o evento OnRecordStart gerado, permitindo tratamento nesta situao. Durante a gravao a propriedade Recording estar TRUE. Ao trmino da gravao o evento OnRecordStop gerado automaticamente, inclusive informando qual o motivo da
Tpicos de Programao
63
interrupo da gravao. Este motivo pode ser uma ao direta do operador (com a chamada do mtodo StopRecordFile), um dgito recebido ou ainda um erro qualquer (disco cheio, por exemplo). Exemplo: Aps falar: "Grave seu recado e ao final digite # se quiser falar com a telefonista", o sistema iniciar a gravao. Se for detectado o #, discar para o ramal 200.
Private Sub DeixarRecado() '.... cdigo para falar a mensagem .... 'Inicia gravao VoicerLibX1.RecordFile(1,"c:\recado.sig,"#") 'Lembre que o programa segue o fluxo normal aps iniciada 'a gravao End Sub 'Rotina de tratamento do click de um boto para o caso de o 'operador parar a gravao manualmente Private Sub cmdParaGravar_Click() VoicerLibX1.StopRecordFile(1) End Sub 'Evento que ocorre quando a gravao finalizada ' necessrio analisar o motivo Private Sub VoicerLibX1_OnRecordStop(ByVal Port as Integer, Status As VoicerLib.TxStopStatus) Select Case Status Case ssStopped: 'Gravao interrompida pelo operador VoicerLibX1.HangUp 1 Case ssDigitReceived: 'Recebeu o digito finalizador 'Transfere para a telefonista if Digits = "#" then
64
VoicerLibX1.Flash 1,600,1000 VoicerLibX1.Dial 1,"200",1000 VoicerLibX1.HangUp 1 end if End Select End sub
Alm disso, possvel monitorar o andamento da gravao atravs do evento OnRecording. O parmetro Duration indica a quantidade de segundos decorridos at aquele momento. A gravao pelo monofone conectado na VoicerPhone ISA ou atravs do cabo especial da VoicerBox PCI/4 pode ser iniciado atravs do evento OnLineReady e finalizada atravs do evento OnLineOff. A partir da verso 2.2, est disponvel o mtodo RecordPause, que permite interromper temporariamente uma gravao e em seguida continuar no mesmo arquivo. Neste mtodo necessrio passar a porta e uma flag booleano indicando se coloca em pausa (TRUE) ou retira da pausa (FALSE).
4.14
Identificao de Chamadas
A identificao de chamadas mais uma caracterstica da placas Digivoice o que permite a criao de aplicaes voltadas para este tipo de aplicao. A placa dever estar conectada diretamente no tronco, e este dever estar com a sinalizao habilitada pela companhia telefnica. A sinalizao enviada pela companhia telefnica pode ser em DTMF ou MFP. Voc deve verificar na companhia qual o tipo enviado pela sua central. Na VoicerLib, esta sinalizao deve ser modificada atravs do mtodo SetDetectionType(Porta). A sinalizao s enviada antes do primeiro ring, portanto
Tpicos de Programao
65
monitore-a atravs do evento OnDigitDetected somente com a placa desligada (HangUp). O evento OnDigitDetected recebe todos os digitos detectados o tempo todo, com a placa atendida ou desligada portanto importante saber em que estado est para evitar pegar talkoff durante a conversao. Caso a sinalizao seja em MFP, voc deve, logo aps o atendimento modificar o tipo de deteco para DTMF que o padro utilizado nos aparelhos telefnicos (o tom dos dgitos). A VoicerLib tambm oferece os mtodos IdleXXX que facilitam o processo de identificao de chamadas.
4.15
Reproduzindo Data
A VoicerLib permite ao programador implementar sistemas que falem datas atravs do mtodo PlayDate. O formato da funo :
vlb.PlayDate Porta, Date, "d/m/y", "#", 0
O primeiro parmetro refere-se ao canal da placa. O segundo parmetro e uma string contendo a data a ser reproduzido (pode-se utilizar uma varivel aqui ou mesmo a funo Date, que retorna a data corrente). . O terceiro parmetro a mscara de formatao da data. Esta mscara determina como a data ser falada. Pode assumir os seguintes valores: d/m/y Ex.: "25 de setembro de 2001" d/m Ex.: "25 de setembro" m/d Ex.: "Setembro 25"
66
m/d/y Ex.: "Setembro 25 2001" O quarto parmetro o TermDigits, que indica quais dgitos podem interromper a mensagem. O ltimo parmetro uma pausa a ser respeitada antes da reproduo da mensagem, expressa em milisegundos, ou seja, caso queira se esperar 1 segundo utilize o valor 1000. Mesmo utilizando a pausa, a funo retorna imediatamente aps sua execuo. Qualquer tratamento de seu resultado dever ser feito no evento OnPlayStop ou OnDigitsReceived. As frases-padro utilizadas para reproduzir esta mensagem encontram-se no CD de distribuio, na pasta StockSigs. Os arquivos contidos nesta pasta devero ser distribudos junto da aplicao desenvolvida.
4.16
Reproduzindo Hora
A VoicerLib permite ao programador implementar sistemas que falem hora atravs do mtodo PlayTime. O formato da funo :
vlb.PlayDate Porta, Time, "#", 0
O primeiro parmetro refere-se ao canal da placa. O segundo parmetro e uma string contendo a data a ser reproduzido (pode-se utilizar uma varivel aqui ou mesmo a funo Time, que retorna a hora corrente). A VoicerLib permite falar a hora no formato hh:mm:ss ou hh:mm. No parmetro Value deve ser passado uma string com a hora separada por ":". Se voc passar, por exemplo, "12:23:32" a VoicerLib entender que deve falar a hh:mm:ss. Se for passado apenas "12:32" a VoicerLib s reproduzir "hh:mm".
Tpicos de Programao
67
O terceiro parmetro o TermDigits, que indica quais dgitos podem interromper a mensagem. O ltimo parmetro uma pausa a ser respeitada antes da reproduo da mensagem, expressa em milisegundos, ou seja, caso queira se esperar 1 segundo utilize o valor 1000. Mesmo utilizando a pausa, a funo retorna imediatamente aps sua execuo. Qualquer tratamento de seu resultado dever ser feito no evento OnPlayStop ou OnDigitsReceived. As frases-padro utilizadas para reproduzir esta mensagem encontram-se no CD de distribuio, na pasta StockSigs. Os arquivos contidos nesta pasta devero ser distribudos junto da aplicao desenvolvida.
4.17
Reproduzindo Lista de Mensagens
Uma das mais importantes caractersticas da VoicerLib a possibilidade de montar uma lista de mensagens que sero reproduzidas como se fossem uma s, gerando apenas um evento OnPlayStart no incio e um OnPlayStop no final de todas. Com isso o programador poder montar frases ou seqncias de mensagens de maneira muito simples. A lista de mensagens permite que sejam inseridas mensagens baseadas em arquivos, data, hora, valor ou numeral cardinal. Vamos supor a seguinte frase: "Ol, hoje dia 25 de setembro de 2001 s 12:32:45". Temos 4 partes distintas nesta frase: "Ol, hoje dia" Arquivo pr-gravado do usurio "25 de setembro de 2001" Data do Sistema (PlayDate) "s" Arquivo pr-gravado do usurio "12:32:45" Hora do Sistema (PlayTime)
68
Adicionando Mensagens a Lista Para adicionar uma ou mais mensagens a uma lista, deve-se utilizar o mtodo PlayListAdd que tem o seguinte formato:
Voice1.PlayListAdd Porta, Tipo, String, Mscara, PausaAntes
O parmetro Porta refere-se ao canal a ser utilizado. A VoicerLib permite manter uma lista independente por canal. O parmetro Tipo indica que tipo de mensagem ser reproduzida. Pode assumir os seguintes valores (representados por constantes): ptCardinal Reproduzir um numeral cardinal (~ PlayNumber) ptFile Reproduzir um arquivo .SIG ptDate Reproduzir uma data (~ PlayDate) ptTime Reproduzir hora (~ PlayTime) ptCurrency Reproduzir um valor monetrio ptNumber Reproduz nmeros digito a digito. O terceiro parmetro (String) deve assumir a formatao exigida pelos tipos acima, ou seja se for indicado que do tipo ptFile, este parmetro deve receber uma string com o nome do arquivo a ser reproduzido. Para saber os formatos corretos para cada tipo, consulte as funes independentes relacionadas (PlayTime, PlayDate, etc...) no comeo desta seo. A Mscara (4. Parmetro) relacionada apenas ao tipo ptDate e segue a mesma padronizao indicada no mtodo PlayDate explicado anteriormente. O ltimo parmetro uma pausa a ser respeitada antes da reproduo da mensagem, expressa em milisegundos, ou seja, caso queira se esperar 1 segundo utilize o valor 1000. Cada mensagem da lista pode ter um valor diferente, ou seja,
Tpicos de Programao
69
possvel dar pausas diferenciadas entre cada item da lista na hora da reproduo. Seguindo o exemplo de frase do comeo desta seo, teramos a seguinte codificao:
voice1.PlayListAdd Port, "olahojeedia.sig","",0 voice1.PlayListAdd Port, voice1.PlayListAdd Port, voice1.PlayListAdd Port, ptFile, ptDate, Date, "d/m/y", 0 ptFile, "as.sig", "", 0 ptTime, Time, "", 0
Apagando o Contedo de Uma Lista A lista de mensagens permanece com seu contedo mesmo depois da reproduo portanto, necessrio apagar seu contedo antes de adicionar novos valores. Para isso deve ser utilizado o mtodo PlayListClear passando como parmetro o canal da placa:
voice1.PlayListClear Port 'Apaga a lista antes de us-la voice1.PlayListAdd Port, ptFile, "olahojeedia.sig","",0 ()
Verificando o tamanho da lista Para saber quantos elementos existem dentro da lista, utilize o mtodo PlayListGetCount, onde o nico parmetro o canal e o valor de retorno, a quantidade de elementos.
Dim i as integer i = voice1.PlayListGetCount(Port)
Removendo um tem Especfico da Lista Tambm possvel remover um determinado elemento da lista atravs do mtodo PlayListRemoveItem. Este mtodo tem dois parmetros: a Porta e o ndice do item a ser excludo (0 at n1).
70
'remove o primeiro elemento da lista voice1.PlayListRemoveItem(Port,0)
Reproduzindo a Lista de Mensagens Aps inserir os elementos da lista possvel reproduzi-la atravs do mtodo PlayList, que tem o seguinte formato:
voice1.PlayList Port,TermDigits
O primeiro parmetro indica o canal da placa. Lembre-se que cada canal tem uma lista independente. O parmetro TermDigits uma string que permite configurar quais dgitos podero interromper a mensagem, exatamente como funciona nos outros mtodos Playxxx. O mtodo PlayList tambm assncrono, ou seja, ao executar o comando o fluxo de execuo do aplicativo segue imediatamente. O final da reproduo dever ser monitorado atravs do evento OnPlayStop. O mtodo PlayList, apesar de reproduzir vrias mensagens encadeadas, funciona da mesma forma que o PlayFile, ou seja, gera apenas um OnPlayStart no incio e um OnPlayStop no final do ltimo item. Caso o parmetro TermDigits seja utilizado e a lista de mensagens seja interrrompida por dgito, toda a lista ser interrompida e sero gerados os eventos OnPlayStop e OnDigitsReceived, sendo que este ltimo receber o valor edDigitOverMessage na varivel Status. Na dvida, leia novamente a explicao sobre o mtodo PlayFile Tudo o que se refere a TermDigits aplica-se ao PlayList tambm.
Tpicos de Programao
71
4.18
Reproduzindo Nmeros Cardinais
A VoicerLib permite ao programador implementar sistemas que falem nmeros inteiros ou fracionrios por extenso (ex.:Dez vrgula trinta e cinco) atravs do mtodo PlayCardinal. O formato da funo :
vlb.PlayCardinal Porta, "10,35", "#", 0
At a verso 2.1 esta funo era desempenhada pelo mtodo PlayNumber, porm, devido novas funcionalidades do PlayNumber de falar digito a digito, a funo de falar o nmero cardinal foi colocada em um mtodo a parte. O primeiro parmetro refere-se ao canal da placa. O segundo parmetro e uma string contendo o nmero a ser reproduzido (pode-se utilizar uma varivel aqui, claro). necessrio passar o valor formatado de acordo com o mostrado acima, sem pontos separadores nos milhares e com vrgula como separador dcimal (nnnnnnn,nn). Qualquer coisa diferente disso far com que a funo no reproduza o valor corretamente. O terceiro parmetro o TermDigits, que indica quais dgitos podem interromper a mensagem. O ltimo parmetro uma pausa a ser respeitada antes da reproduo da mensagem, expressa em milisegundos, ou seja, caso queira se esperar 1 segundo utilize o valor 1000. Mesmo utilizando a pausa, a funo retorna imediatamente aps sua execuo. Qualquer tratamento de seu resultado dever ser feito no evento OnPlayStop ou OnDigitsReceived. As frases-padro utilizadas para reproduzir esta mensagem
72
encontram-se no CD de distribuio, na pasta StockSigs. Os arquivos contidos nesta pasta devero ser distribudos junto da aplicao desenvolvida.
4.19
Reproduzindo Nmeros Dgito a Dgito
A VoicerLib permite ao programador implementar sistemas que falem nmeros atravs do mtodo PlayNumber. Com isso possvel "soletrar" os dgitos de um dado qualquer (conta, carto, etc...). Tambm permite falar "/" barra, "-" trao, "." Ponto, "," vrgula. O formato da funo :
vlb.PlayNumber, "456790-23", "#", 0
At a verso 2.1 esta funo era desempenhada pelo mtodo PlayNumber, porm, devido novas funcionalidades do PlayNumber de falar digito a digito, a funo de falar o nmero cardinal foi colocada em um mtodo a parte. O primeiro parmetro refere-se ao canal da placa. O segundo parmetro e uma string contendo o nmero a ser reproduzido (pode-se utilizar uma varivel aqui, claro). O terceiro parmetro o TermDigits, que indica quais dgitos podem interromper a mensagem. O ltimo parmetro uma pausa a ser respeitada antes da reproduo da mensagem, expressa em milisegundos, ou seja, caso queira se esperar 1 segundo utilize o valor 1000. Mesmo utilizando a pausa, a funo retorna imediatamente aps sua execuo. Qualquer tratamento de seu resultado dever ser feito no evento OnPlayStop ou OnDigitsReceived.
Tpicos de Programao
73
As frases-padro utilizadas para reproduzir esta mensagem encontram-se no CD de distribuio, na pasta StockSigs. Os arquivos contidos nesta pasta devero ser distribudos junto da aplicao desenvolvida.
4.20
Reproduzindo uma Mensagem
A VoicerLib permite reproduzir qualquer mensagem gravada em formato SIG, tanto pelo headset como pelo monofone (ou tronco). Para isso basta utilizar o mtodo PlayFile. O PlayFile detecta automaticamente o tipo de arquivo, baseado na extenso para .sig, .gsm e se for wave, detecta se PCM ou LeiMi. Isso permite uso de diversos formatos para reproduo sem preocupao para o programador, assim ele no precisar se preocupar em converter o arquivo antes de reproduzir. Se for utilizado uma extenso desconhecida, fica valendo o que est especificado no SetPlayFormat. Alm disso, possvel determinar se algum dgito ser utilizado como finalizador da reproduo. Esta caracterstica interessante para, por exemplo, implantar um menu de opes em um sistema de auto-atendimento com a possibilidade de digitar a opo sobre a mensagem. O dgito detectado (se usado) armazenado internamente para cada porta da placa e pode ser recuperado atravs do mtodo ReadDigits(Porta) podendo ser tratado posteriormente. Dependendo do fluxo de operao do sistema desenvolvido, necessrio que os digitos detectados sejam acumulados. Neste caso necessrio mudar a propriedade AutoClearDigits para false, pois o padro true faz com que os digitos sejam automaticamente apagados quando uma gravao iniciada. Sempre quando for iniciada a reproduo o evento OnPlaytStart
74
gerado. Uma finalidade deste evento permitir atualizaes de interface, como por exemplo, desabilitar botes e exibir mensagens ao usurio. Ao trmino da reproduo o evento OnPlayStop gerado automaticamente, inclusive informando qual o motivo da interrupo da reproduo. Este motivo pode ser uma ao direta do operador (com a chamada do mtodo StopPlayFile), um dgito recebido, o simples trmino da mensagem ou ainda um erro qualquer (disco cheio, por exemplo). A partir da verso 2.1, se um digito for detectado durante a reproduo (desde que o parmetro TermDigits tenha sido configurado), alm do evento OnPlayStop, gerado tambm o evento OnDigitsReceived passando na varivel Status o valor edDigitOverMessage. Isto facilita a criao de menus de atendimento, j que toda a consistncia do que foi digitado pode ser feita apenas no evento OnDigitsReceived. O tpico seguinte (deteco de dgitos) aborda este evento em detalhes. Exemplo: O sistema atende uma ligao no evento OnRingDetected, fala uma mensagem e fica esperando o dgito de uma das opes: "Digivoice, disque 3 para vendas, 4 para tcnica ou 5 para fax". Dependendo da opo, disca para o ramal correspondente. A partir da verso 2.1 recomenda-se fazer o tratamento de dgitos no evento OnDigitsReceived e no no OnPlayStop. Neste caso o Case ssDigitReceived do exemplo abaixo seria movido para o evento OnDigitsReceived. O captulo Aplicao Passo a Passo explica em detalhes.
'Evento gerado quando a placa detecta um 'Ring. Neste exemplo, atende no primeiro toque Private Sub VoicerLibX1_OnRingDetected() 'Mensagem de boas vindas VoicerLibX1.PlayFile(1,"c:\boas.sig,"345",0)
Tpicos de Programao
75
'Lembre que o programa segue o fluxo normal aps iniciada 'a reproduo End Sub 'Evento que ocorre quando a reproduo finalizada ' necessrio analisar o motivo Private Sub VoicerLibX1_OnPlayStop(Port as Integer, Status As VoicerLib.TxStopStatus) Select Case Status Case ssNormal: 'Terminou a mensagem sem opo digitada 'ento manda para a telefonista VoicerLibX1.Flash 1,600,1000 VoicerLibX1.Dial 1,"200",0 VoicerLibX1.HangUp 1 Case ssDigitReceived: 'Recebeu o digito finalizador 'Verifica qual e transfere para o ramal VoicerLibX1.Flash 1,600 'Executa flash if Digits = "3" then VoicerLibX1.Dial 1,"220",0 'vendas ElseIf Digits = "4" then VoicerLibX1.Dial 1,"215",0 'tcnica ElseIf Digits = "5" then VoicerLibX1.Dial 1,"202",0 'fax else VoicerLibX1.Dial 1,"200",0 'telefonista End if 'Desliga VoicerLibX1.HangUp 1 End Select End sub
O ltimo parmetro do PlayFile (Origin) permite comear a reproduzir a mensagem a partir de um determinado ponto. Por exemplo, para reproduzir uma mensagem a partir de 10 segundos do incio dela, basta executar:
VoicerLibX1.PlayFile(1,"c:\boas.sig,"345",10)
76
Isto til para funes de reproduo de mensagens. Se for passado ZERO como parmetro, a mensagem ser reproduzida do incio. Se for passado -1 como parmetro a mensagem comear a ser reproduzida do final menos 2 segundos.
4.21
Reproduzindo Valores por Extenso
A VoicerLib permite ao programador implementar sistemas que falem valores monetrios por extenso (ex.: Um mil e quinhentos reais e trinta e dois centavos) atravs do mtodo PlayCurrency. O formato da funo :
vlb.PlayCurrency Porta, "1234,33", "#", 0
O primeiro parmetro refere-se ao canal da placa. O segundo parmetro e uma string contendo o valor a ser reproduzido (pode-se utilizar uma varivel aqui, claro). necessrio passar o valor formatado de acordo com o mostrado acima, sem pontos separadores nos milhares e com vrgula como separador dcima (nnnnnnn,nn). Qualquer coisa diferente disso far com que a funo no reproduza o valor corretamente. O terceiro parmetro o TermDigits, que indica quais dgitos podem interromper a mensagem. O ltimo parmetro uma pausa a ser respeitada antes da reproduo da mensagem, expressa em milisegundos, ou seja, caso queira se esperar 1 segundo utilize o valor 1000. Mesmo utilizando a pausa, a funo PlayCurrency retorna
Tpicos de Programao
77
imediatamente aps sua execuo. Qualquer tratamento de seu resultado dever ser feito no evento OnPlayStop ou OnDigitsReceived. As frases-padro utilizadas para reproduzir esta mensagem encontram-se no CD de distribuio, na pasta StockSigs. Os arquivos contidos nesta pasta devero ser distribudos junto da aplicao desenvolvida.A relao das frases e seus respectivos arquivos enconta-se no Apndice A deste manual
4.22
Status dos Canais
A VoicerLib disponibiliza o mtodo GetPortStatus para que o programador tenha acesso a situao da placa naquele instante. Exemplo:
sts = VoicerLibX1.GetPortStatus(1)
O retorno poder ter os seguintes valores: spFlashing - Executando um Flash spDialing - Discando spNone - Nada spWaitingDigits - Esperando Dgitos
4.23
Tratamento de Erros
Basicamente os erros que podem ocorrer com a biblioteca so decorrentes de mal funcionamento do device driver ou mesmo m configurao da placa (Interrupo, etc...).
78
Alm dos valores de retorno do mtodo StartVoicerLib que permitem saber se os servios foram inicializados corretamente, existe o evento OnErrorDetected, que ativado quando a placa para de responder ao aplicativo por mais de 15 segundos. Se isto ocorrer, o mais indicado reiniciar o micro e verificar a configurao da placa. Tambm existe a propriedade booleana DriverEnabled, que indica se o driver est ativo (true) ou no (false). No evento OnErrorDetected passado o parmetro ErrorType que pode assumir os seguintes valores: 1. 2. Placa Parou de Interromper Este erro ocorrer caso a placa pare de interromper a VoicerLib. Isso pode ser ocasionado principalmente por conflitos de interrupo. Erro de Buffer Ativo Este erro ocorrer se a VoicerLib perder algumas interrupes geradas pela placa. Esse problema tambm est relacionado conflitos de interrupo ou sobrecarga de processamento na mquina. Erro de Buffer Invalido O erro 3 ocasionado por problemas de carga do firmware na placa.
3.
Exemplo: Private Sub VoicerLibX1_OnErrorDetected(Port as Integer, ErrorType as Integer) If not VoicerLibX1.DriverEnabled then MsgBox "Erro na VoicerLib Codigo " & ErrorType End if End Sub
Tpicos de Programao
79
4.24
Protegendo sua Aplicao
A Voicer Lib disponibiliza ao programador uma rea de memria da placa de 10 caracteres. Esta rea voltada a proteo dos aplicativos desenvolvidos com a Voicer Lib. Importante: Somente as placas Voicer Phone a partir da verso 1.6 (impresso no circuito impresso) tem esta facilidade. Nesta rea possvel, por exemplo, gravar nmeros de srie, senhas, nome do cliente ou qualquer outra coisa que se faa necessria para proteo. Esto disponveis 10 bytes (caracteres) para gravao. Gravando na Memria Para efetuar a gravao, utilize o mtodo WriteSecurityWord, passando como parmetro a string desejada. Esta funo no permite acesso a endereos especficos nesta memria portanto necessrio passar a string completa. Se voc necessitar armazenar vrios dados, monte a string com estes dados e em seguida grave-a utilizando o mtodo WriteSecurityWord. No exemplo a seguir, temos uma rotina que grava o nmero de srie e o nome do cliente na memria.
Private Sub GravaMemoria Dim ret as integer ret = VoicerLibX1.WriteSecurityWord("000001DF","") if ret <> 0 then MsgBox "Erro ao gravar" end if End Sub
80
Lendo Dados da Memria Para ler os dados da memria da placa Voicer Phone, necessrio utilizar o mtodo ReadSecurityWord que retorna a string gravada, com 10 caracteres. Caso haja algum problema de leitura, o mtodo retornar uma string vazia (ou nula). Exemplo:
Private Sub LeMemoria Dim sDados as String sDados = VoicerLibX1.ReadSecurityWord("") if sDados = "" then MsgBox "Erro ao ler da memria" end if End Sub
Quando o mtodo ReadSecurityWord chamado, o fluxo de execuo do programa s continuar depois que o dados for lido. Esta ao de leitura pode demorar at alguns poucos segundos portanto no utilize o mtodo ReadSecurityWord dentro de looping ou de funes que necessitam de performance. Os dois mtodos tem um parmetro mostrado nos exemplos acima passados como vazio (""). Este um parmetro reservado e sempre deve ser passado o vazio ("").
Parte
V
Utilizando um aparelho telefnico
82

Na placa VoicerPhone, existe uma entrada para conectar um aparelho telefnico comum, que pode ser utilizado em alternativa headset. Quando utilizado o aparelho, os mtodos HangUp, PickUp, PhoneOn, PhoneOff, MicOn e MicOff no so aplicveis, pois referem-se exclusivamente ao headset, entretanto, possvel gravar e ouvir mensagens e fazer todos os outros tratamentos. Se o usurio estiver com o telefone fora do gancho e executar o mtodo PickUp, o telefone ficar mudo e o udio ser transferido para o headset. Quando o telefone retirado do gancho, o evento OnLineReady gerado. Exemplo:
Private Sub VoicerLibX1_OnLineReady(Port As Integer) lblStatus.Caption = "Telefone pegou linha" End Sub
Quando o telefone colocado novamente do gancho, o evento OnLineOff gerado. Exemplo:

Private Sub VoicerLibX1_OnLineOff(Port As Integer) lblStatus.Caption = "Telefone desligado" End Sub
A placa VoicerBox PCI/4 utiliza os eventos OnLineReady e OnLineOff utilizando-se um cabo especial em que possvel fazer a
83
entrada da linha e a sada pelo mesmo conector. Esta caracterstica voltada principalmente para aplicaes de gravador digital de tronco.
Parte
VI
Funes Especiais
86
6
6.1
Funes Especiais
Introduo
As funes especiais so destinadas a executar tarefas comuns em telefonia de maneira mais simples para o programador. Todas estas tarefas so plenamente realizveis atravs das funes apresentadas no captulo anterior, porm procuramos reunir as tarefas mais comuns em grupos especficos: Funes de Idle Atendimento Automtico, Bina, Integrao com PABX Funes de Prompt Entrada de dados com ou sem conferencia e confirmao (Senhas, etc...) Funes de Menu Reproduo de menu de opes com consistncia Funes de Discagem e Transferncia Discagem atravs de linha direta ou ramal, com opes para superviso de ocupado, etc... Funes de Conferncia - Comunicao entre canais. Os mtodos e eventos apresentados a seguir so sempre indexados pelo parmetro Port o que significa que as configuraes so totalmente independentes por canal. Para o pleno entendimento destas novas funcionalidades muito importante estudar atentamente os exemplos fornecidos em Delphi e Visual Basic que encontram-se no site da DigiVoice www.digivoice.com.br, na seo de desenvolvedores.
Funes Especiais
87
6.2
Funes de Idle
As funes de Idle permitem ao programador simplificar os processos de espera de ligaes: Atendimento Automtico aps n toques Deteo de Identificao do Assinante A (Bina) atravs do evento OnCallerID Deteo de Dgitos aps o atendimento, facilitando integraes com diversos modelos de Pabx. At a verso 2.3, estas atividades podiam ser desempenhadas atravs dos mtodos/eventos j conhecidos. Todas estas funes so configuradas atravs do mtodo IdleSettings (vejao no guia de referncia para acompanhar melhor este tpico), entram em ao a partir da chamada ao mtodo IdleStart e so interrompidas com a chamado do IdleAbort. Atendimento Automtico IMPORTANTE: As funes IdleXXXX so exemplificadas em um programa especfico encontrado no site da DigiVoice www.digivoice.com.br, na seo de desenvolvedores. Acompanhe e teste o exemplo. A VoicerLib permite ao programador, a partir de simples parmetros no mtodo IdleSettings, configurar um atendimento automtico a partir do ensimo toque e ainda esperar um tempo pr-definido antes de chamar o evento OnAfterPickup. Sem est funo, o programador tinha que "contar" os toques no evento OnRingDetected e atender atravs de uma chamada ao evento PickUp. Os parmetros do IdleSettings que interferem no funcionamento desta funo so o segundo, terceiro e quarto, sendo:
88
2. Parmetro (AutoPickUp) Campo booleano (true/false) que indica se atende automtico ou no 3. Parmetro (RingCount) Nmero de toques para o atendimento 4. Parmetro (PauseAfterPickUp) Pausa aps o atendimento. Esta pausa pode ser utilizada para dar um tempo antes de iniciar a reproduo da mensagem de boas vindas, o que til em atendedores com bloqueio DDC (Chamada a cobrar). Monitorao de Dgitos A monitorao de dgitos pode ser feita antes do atendimento, como nos casos de identificao de chamadas direto do tronco ou depois do atendimento, particularmente til em integrao do tipo inband com centrais PABX. Estas configuraes tambm so feitas a partir do mtodo IdleSettings do 5. ao ltimo parmetro: 5. Parmetro (WatchTrunkBefore) Indica que deve ser acionada a monitorao de dgitos antes do Ring. Deve ser utilizado principalmente em casos de identificao de chamadas. 6. Parmetro (WatchTrunkAfter) Indica que deve ser acionada a monitorao de dgitos depois do Atendimento. 7. Parmetro (Format) O formato indica como a espera de dgitos ser tratada: 1. wtDTMF/wtMFP Deve ser utilizado somente com o WatchTrunkBefore ligado para tratamento de Bina DTMF (wtDTMF) ou Bina MFP (wtMFP). Neste caso ser gerado o evento OnCallerID contendo o nmero identificado. 2. wtCustom Este formato traz os dgitos exatamente como foram detectados, sem nenhum tratamento. O resultado dado no evento OnDigitsReceived. Funciona praticamente igual a um GetDigits. 8. Parmetro (TimeOut) o tempo mximo que o sistema
Funes Especiais
89
esperar pelos dgitos a partir do primeiro detectado. Funciona como parmetro InterdigitTimeout do mtodo GetDigits e s tem utilidade quando o formato for wtCustom (neste caso o timeout global dado pelo parmetro PauseAfterPickup). 9. Parmetro (Max) Indica qual o nmero mximo de dgitos que o sistema dever esperar. Se no for utilizado, deve ser setado como 0 (zero). 10. Parmetro (TermDigits) Indica qual o digito terminador. Deixar vazio se no for utilizado. Para a compreenso destas funes, recomendamos estudo atento do exemplo fornecido na pasta encontrado no site da DigiVoice www.digivoice.com.br, na seo de desenvolvedores.
6.3
Funes de Prompt
As funes de Prompt facilitam os processos de entrada de dados e conferncia em uma aplicao de URA. Como exemplo de utilizao, observe a frase abaixo: "Digite sua senha ........ Voc digitou 123.... Tecle # para confirmar ou * para cancelar" "Disque o ramal desejado...." Para que os dgitos sejam reproduzidos corretamente, voc dever configurar corretamente a propriedade StockSigs apontando para a pasta onde os arquivos wave padro esto armazenados Basicamente as funes de prompt permitem reproduzir uma mensagem inicial (ou lista de mensagens), esperar por dgitos especficos (maxdigits, termdigits, etc...), reproduzir opcionalmente uma mensagem de conferncia com as informaes digitadas e ainda confirmar a digitao, permitindo
90
a reentrada dos dados. Tudo isto pode ser feito atravs de parmetros passados aos mtodos PromptSettings e PromptStart. Exemplos destas funes encontram-se no site da DigiVoice www.digivoice.com.br, na seo de desenvolvedores, tanto em VB como em Delphi. Ao chamar o mtodo PromptStart a reproduo da mensagem iniciada e o fluxo de execuo segue normalmente, da maneira anloga ao mtodo PlayFile, por exemplo. Quando as condies forem cumpridas de acordo com o configurado, o evento OnPrompt ser acionado e receber a varivel Status contendo o que aconteceu na execuo da funo e o parmetro Value contendo o dado digitado pelo usurio. Os detalhes do significado e funcionalidade de cada parmetro deve ser consultado no Guia de Referncia deste manual.
6.4
Funes de Menu
As funes de menu automatizam o processo de atendimento com opes de menu. Ex.: "...Para vendas disque 3, expedio 4 ..." ".... Para saldo disque 1, para falar com o atendente 3..." O mtodo MenuErrorSettings configura as respostas s situaes de erro: frase de erro ("...Opo Invlida!..."), nmero de tentativas em caso de erro e frase para quando o usurio no discar nada. O mtodo MenuStart inicia a reproduo da frase de menu sendo passado como parmetro a frase de opes, os dgitos
Funes Especiais
91
vlidos e o tempo mximo para digitao aps a frase. Assim como o prompt, aps a chamada do mtodo MenuStart, o fluxo de execuo segue normalmente. Aps o usurio interagir com o menu, o evento OnMenu ser chamado, recebendo o Status e e a opo selecionada (OptionSelected). Para interromper a execuo do menu basta chamar o mtodo MenuAbort. Os detalhes do significado e funcionalidade de cada parmetro deve ser consultado no Guia de Referncia deste manual. Exemplos dessas funes so fornecidos no site da DigiVoice www.digivoice.com.br, na seo de desenvolvedores, tanto em VB quanto em Delphi.
6.5
Funes de Discagem e Transferncia
Os mtodos e eventos que compem esta funcionalidade automatizam todo o processo de discagem, transferncia, superviso e atendimento atravs da chamada de um nico mtodo (MakeCall). Para acompanhar a explicao, observe atentamente o exemplo de Transferncia encontrado no site da DigiVoice www.digivoice.com.br, na seo de desenvolvedores, tanto em VB quanto em Delphi. Com este grupo de mtodos ser possvel efetuar de maneira simples: Discagem externa com superviso de atendimento, verificando se o destino atendeu ou no ou ainda se deu ocupado Transferncia entre ramais de um pabx com ou sem superviso.
92
Frases automticas em caso de ocupado e no atender Toda a configurao feita atravs dos mtodos SetCallxxxx. Voc pode programar um flash no incio da discagem atravs do mtodo SetCallStartFlash, til em casos de transferncia. Em termos de flash tambm possvel programar um flash especfico para retomada em caso de ocupado (SetCallBusyReturnFlash) e outro em caso de no atendimento (SetCallNoAnswerReturnFlash). Em todos os casos pode-se definir dgitos e pausa aps o flash e tambm pausa aps dgito que so suficientes para adaptao em qualquer central PABX. O tempo de flash uma configurao geral para todos os casos e definida pelo mtodo SetCallFlashTime. possvel definir frases a serem reproduzidas quando se detecta o ocupado (SetCallBusyPhrase) ou quando no atende (SetCallNoAnswerPhrase). O sistema utilizado o mtodo SetCallNoAnswerRingCount para determinar com quantos toques ser considerado um "no atendimento". Em caso de atendimento possvel programar uma pausa e uma frase a ser reproduzida para o usurio. Isto feito pelo mtodo SetCallAfterAnswer. O incio da discagem feito atravs da chamada ao mtodo MakeCall, onde so definidos o tipo de discagem (externa ou com flash), a frase a ser reproduzida inicialmente, o nmero que ser discado e se a discagem ser feita com ou sem superviso. Se for feita sem superviso, to logo o nmero discado a execuo do mtodo finalizada e o evento OnAfterMakeCall chamado. O tipo de discagem define uma srie de comportamentos importantes: Externa Inicia a discagem com um pickup pois entende
Funes Especiais
93
que o telefone est desligado. Utiliza as definies de digito e pausa aps o pickup definidos pelo mtodo SetCallAfterPickUp. Com Flash Executa um flash antes de iniciar a discagem pois entende que a linha est conectada a um PABX e o que vai ser feito uma transferncia entre ramais. Alm das configuraes anteriores, possvel determinar se o tom de discagem ser esperado obrigatoriamente (SetCallWaitForDialTone) e o tempo que a superviso ser iniciada aps a discagem (SetCallPauseBeforeAnalysis). Este ltimo til em supervises de transferncia para casos onde o PABX gera rudos durante o flash que podem induzir a placa a detees erradas de atendimento. Definindo um tempo com este mtodo a superviso s iniciar a nnn milisegundos aps a discagem, o que permitir ignorar estes rudos. Assim como todos os outros mtodos da VoicerLib, o MakeCall assncrono, ou seja, ao ser executado inicia o processo todo mas o fluxo de execuo do programa continua. IMPORTANTE: O MakeCall no pode ser chamado com a funo IdleStart ativa. Caso isso ocorra, retornar erro cdigo 1. A qualquer momento possvel saber se um MakeCall est em curso atravs da monitorao do evento OnCallStateChange. Por fim, o evento OnAfterMakeCall chamado informando o tipo de ocorrncia detectada durante o processo (ocupado, atendimento, etc...) atravs dos seguintes valores assumidos na varivel Status: mkNoDialTone No foi detectado tom de discagem, caso esta opo tenha sido ligada (*). mkDelivered Ligao entregue sem superviso. mkNoAnswer Destino no atendeu aps n toques. mkBusy Destino estava ocupado.
94
mkAnswered Ligao atendida. mkAborted MakeCall cancelado atravs do mtodo AbortCall. mkDialToneAfterDial - Indica recebimento de tom de linha depois da discagem. (*) No caso de receber um mkNoDialTone depois de efetuar o Flash para transferncia no PABX, voc deve retomar a ligao antes de deslig-la para evitar de prender a linha no PABX. Uma situao de no receber tom de discagem para transferncia entre ramais s pode ocorrer se as configuraes de Flash estiverem erradas ou no caso de sobrecarga de processamento do PABX (ocorre principalmente em discadores automticos).
6.6
Funes de Conferncia
Funes que facilitam o gerenciamento entre canais em conferncia. possvel criar "salas" (ou recursos) de conferncia contendo de 2 a, no mximo,10 canais.Esse limite muito dependente dos recursos de CPU. Em testes, foi possvel incluir 10 canais em uma mesma conferncia com boa qualidade de udio em um Pentium 4 1.6Ghz com 256MB de memria. Tambm possivel criar vrias salas em um mesmo computador. Tomando-se como exemplo um computador com 6 placas VoicerBox PCI/4 instaladas, possivel criar, por exemplo, 6 salas de 4 canais, 4 salas de 6 canais ou mesmo 12 salas de 2 canais cada. Exemplo: possvel criar uma conferncia que funciona como uma sala
Funes Especiais
95
de bate-papo, sendo que as pessoas que entram nas sala sero os canais que se alocam em determinadas conferncias. Para criar uma nova sala utiliza-se o mtodo CreateConferenceResource, passando o numero mximo de pessoas que podero se comunicar nesta sala. Quando se cria uma conferncia ela retorna um valor, o Handle, que ser utilizado pelos outros mtodos como identificao da sala. Para adicionar uma pessoa por exemplo informa-se esse valor para saber em qual sala ela ir entrar. O mtodo ConferenceAddPort permite adicionar as pessoas as salas, caso a sala esteja cheia, sendo utilizada pelo numero mximo de pessoas determinado, o mtodo retorna o valor -2, podendo ento avisar o usurio que a sala j est cheia e que ele tem que escolher outra sala. Para que uma pessoa esteja em comunicao com as outras da sala preciso que ela esteja habilitada, atravs do mtodo ConferenceEnablePort. A flexibilidade de habilitar e desabilitar uma pessoa importante pois, caso a pessoa queira ouvir o menu, os outros canais no iro ouvir tambm, basta desabilitla, atravs do mtodo ConferenceDisablePort, reproduzir o menu que somente ele ouvir, e aps isso habilit-la novamente. Isso sem precisar remov-la da sala. O mtodo ConferenceRemovePort permite remover as pessoas das salas e o mtodo DeleteConferenceResource deleta a sala. Quando vrios canais so somados em uma conferncia certamente haver um efeito de eco, podendo causar a total degenerao do udio desta "sala". Para diminuir o efeito de eco, dever ser habilitado o cancelamento atravs do mtodo EnableEchoCancel e para desabilit-lo, DisableEchoCancel. Em uma conferncia recomenda-se sempre utilizar o cancelamento de eco. Esse tipo de recurso consome CPU portanto, em situaes controladas e com poucas portas (duas), possivel ter boa qualidade de audio com o cancelamento de eco desabilitado. Por padro, o cancelamento de eco est
96
desabilitado na inicializao da VoicerLib.
6.7
Funes para Streaming de Audio
Uma nova caracterstica que est sendo implementada na VoicerLib a disponibilidade de eventos e mtodos que viabilizariam o envio da voz por uma rede local, por exemplo. Do lado do servidor ou quem gerar as amostras para a rede, o princpio disponibilizar as amostras de udio captadas pela placa para aplicao. O envio das amostras para a rede propriamente dito no responsabilidade da VoicerLib e dever ser implementado pelo desenvolvedor utilizando bibliotecas com suporte ao WinSock ou mesmo atravs das funes de baixo nvel das APIs do Windows. Para iniciar o envio das amostras do hardware para a aplicao, dever ser chamado o mtodo EnableSampleToApp(porta). Este mtodo faz com que o evento OnSampleReceived ser gerado de tempos em tempos. Neste evento, o programador dever extrair as amostras da FIFO e envi-las pela rede. Para extrair as amostras da fila que foi criada entre o hardware e a aplicao, utilize o mtodo GetSamples. Do lado do cliente as amostras chegaro atravs dos eventos TCP/IP ( que independem da VoicerLib) e devero ser tratados de acordo com a vontade do programador. Se na mquina cliente houver uma placa VoicerPhone e o desejo que o udio seja ouvido atravs dela, dever ser chamado inicialmente o mtodo EnableSampleToCard que habilita o envio de amostras da aplicao para a placa. Em seguida, a cada n amostras recebidas via TCP/IP, dever
Funes Especiais
97
ser chamado o mtodo PutSamples que efetivamente envia a amostra para a placa. Isto tem o mesmo efeito do PlayFile, por exemplo. Normalmente o programa dever manter um buffer para receber e armazenar as amostras em memria para ento envi-las pela rede. Lembre-se que a taxa de envio de amostras de e para a placa dever ser de 1.65 Kb/s pois o padro o envio e recebimento apenas no formato GSM.
Parte
VII
Distribuindo uma Aplicao
100
7
7.1

Introduo
Visando facilitar a distribuio de todos os arquivos necessrios para a execuo de uma aplicao construda utilizando a VoicerLib, as placas VoicerPhone e VoicerBox so acompanhadas de um disquete contendo os componentes runtime. No CD de instalao o dri ver para distribuio encontra-se na pasta Driver\Instalao Para placas VoicerBox PCI/4 e VoicerPhoe PC/1, tambm necessrio criar um disquete com o contedo da pasta Driver\InfParaPCI. Esta pasta contm os arquivos necessrios para instalao do hardware no momento que o Windows detectad a(s) nova(s) placa(s). Aps detectar, o Windows pede a localizao do Driver. Neste caso informe o disquete ou o caminho onde se encontra os arquivos da pasta Driver\InfParaPCI do CD-ROM. Alm do procedimento acima, necessrio instalar os outros arquivos da biblioteca atravs do programa setup.exe da pasta Driver\Instalao do CD-ROM. Ele pode ser executado diretamente do CD ou atravs de disquete ou drive de rede. Caso o desenvolvedor queira agregar a instalao do driver ao seu prprio set de instalao, o programa setup.exe pode ser executado em modo silencioso, ou seja, sem as janelas de dilogo iniciais. Isto pode ser feito passando o parmetro /q . Ex.:
Setup.exe /q
Desta maneira o desenvolvedor pode mandar executar o setup
101
do Digivoice Driver aps o trmino da sua prpria instalao.
7.2
Preparando o Ambiente
Placa PCI/4 e PCI/1 No necessrio nenhum procedimento de configurao para as placas PCI pois a interrupo e endereo de I/O so atribudos automaticamente pela BIOS do PC. Placa ISA No caso da placa ISA, necessrio configurar o Windows com a quantidade de placas, interrupes e endereos de I/O utilizados. Isto possvel atravs do utilitrio GERAINI.EXE instalado no diretrio do Windows. Tambm possvel o desenvolvedor criar o arquivo de configurao por conta prpria, pois segue o padro dos arquivos tipo INI do Windows Lembre-se de verificar se no h conflitos de interrupo com outro hardware instalado. Utilitrio GeraIni.EXE Voc pode execut-lo atravs do menu Iniciar Executar...
102
Para adicionar uma placa selecione a Interrupo e o endereo de I/O desejado e clique no boto ">>" . Para remover, selecione a placa desejada na lista de Placas Instaladas e clique no boto remover. Para gravar a configurao, clique no boto OK. Criando o prprio arquivo de configurao O arquivo de configurao padro das placas VoicerPhone ISA o voicerlib.ini que fica no diretrio do Windows. Ele segue o padro dos arquivos INI do Windows e tem o seguinte formato:
[ISA] NumCards=2 micro [ISA1] ISAn irq=5 Nmero de placas instaladas no Cada placa deve ter o nome Nmero da Interrupo desta
103
placa io=672 [ISA2] se houver irq=5 io=816
Endereo de I/O (em decimal) Informaes da segunda placa
Os endereos de I/O devem ser representados atravs do seu valor decimal. Neste manual e na propria placa eles estao representados em hexadecimal portanto necessrio convertlos. Veja abaixo os valores que devem ser utilizados:
Hexadecimal 220H 2a0H 330H Decimal 544 672 816
O Windows disponibiliza as funes GetPrivateProfileString e WritePrivateProfileString que manipulam este tipo de arquivo com facilidade. Para maiores detalhes consulte o Guia de Referncia de sua linguagem de programao. Os uurios do Borland Delphi e C++Builder tem a classe TIniFile que facilita ainda mais a manipulao deste tipo de arquivo.
Parte
VIII
Aplicao Exemplo
106
8
8.1
Aplicao Exemplo
Apresentao
Este captulo apresenta uma aplicao de atendimento automtico comentada passo a passo. Com ele, o programador poder facilmente entender os procedimentos corretos de programao utilizando a VoicerLib. A aplicao foi desenvolvida utilizando-se o Borland Delphi, portanto o cdigo apresentado aqui Pascal. Os programadores de Visual Basic e outras linguagens no tero dificuldades em entender a lgica apresentada pois tudo comentado em detalhes. O mesmo programa escrito em Visual Basic pode ser encontrado no site da DigiVoice www.digivoice.com.br, na seo de desenvolvedores. O exemplo voltado a explicar a VoicerLib, portanto alguns detalhes que seriam imprescindveis em um programa comercial sero omitidos ou mesmo utilizaremos tcnicas hardcode (dados cravados no cdigo) para detalhes de configurao. Aqui optamos por utilizar os mtodos de "baixo nvel" para firmar os conceitos da VoicerLib e passar tcnicas de programao para este tipo de aplicao que difere bastante das aplicaes procedurais tradicionais. Um exerccio interessante fazer a mesma aplicao utilizando-se das funes especiais apresentadas no captulo anterior. Com elas o programa ficar bem menor e mais simples! O programa de atendimento executa as seguintes funes: 1. Espera chamada
Aplicao Exemplo
107
2. 3. 4. 5. 6.
Executa frase de atendimento com menu Espera digitao das opes de menu ou do ramal Abre opes de sub-menu - se houver Transfere para o ramal desejado Efetura superviso de ramal, verificando se est ocupado ou no atende. 7. Transfere para os ramais de fuga com superviso 8. Desliga. Para otimizar o cdigo aqui no manual, em alguns pontos da listagem aparecer o smbolo (.........) que indicar que neste ponto existe algum cdigo que no importante para o escopo da explicao naquele momento. Qualquer dvida no posicionamento correto do cdigo, o exemplo pode ser encontrado no site da DigiVoice www.digivoice.com.br, na seo de desenvolvedores. O Programa O programa apresentado a seguir pode ser encontrado no site da DigiVoice www.digivoice.com.br, na seo de desenvolvedores. A interface de um programa como este extremamente simples;
108
Tambm utilizado um objeto Timer para funes de timeout. Repare que no foi utilizado nenhum elemento exclusivo do Delphi, o que torna a transcrio do programa para outra linguagem extremamente simples. Consulte periodicamente o site www.digivoice.com.br/ na seo de desenvolvedores para verificar se o exemplo j foi traduzido para outras linguagens. O componente VoicerLibX200 colocado no form principal e dado o nome voice1.
Aplicao Exemplo
109
8.2
Atendimento de uma ligao
Neste exemplo, todas as ligaes sempre sero atendidas no primeiro toque. Neste caso, o primeiro evento que deve ser codificado o OnRing que gerado sempre que chegar um tom de ring pela linha/ramal. No cdigo abaixo utilizamos o case .. of do Pascal pois muito mais legvel que uma seqncia de if aninhados (ifs dentro de ifs!) principalmente quando houverem muitos estados a tratar. O Visual Basic tem o equivalente Select Case e o C/C++ tem o switch. Caso sua linguagem no tenha uma estrutura equivalente, s caber utilizar o if...
procedure TForm1.voice1RingDetected(Sender: TObject; Port: Smallint); begin case Estado[Port] of NADA: //S entra aqui se estiver no estado de espera begin //Limpa o buffer de digitos da porta corrente voice1.ClearDigits(Port); //comentario na janela de status InsereDado(Port,'Atendeu'); //Atende a ligao voice1.PickUp(Port,4000); //indica para esperar DTMF voice1.SetDetectionType(Port,dtDTMF); end; end; end;
Repare que somente o Estado NADA tratado, ou seja, se chegar um ring e a varivel Estado estiver com outro valor, nada
110
ser feito. Dentro do case do Estado NADA, temos a chamada ao mtodo ClearDigits que limpa o buffer interno de dgitos. Este buffer que conter os nmeros digitados pelo usurio que ligou para a placa. Em seguida chamado o mtodo PickUp que efetivamente atende a ligao. passado como parmetros a porta e a pausa aps atendimento de 4 segundos (4000). Esta pausa necessria para prever situaes onde o PABX demora algum tempo para comutar a linha com o ramal, ou mesmo nos casos onde existe um bloqueador de chamadas cobrar (como o caso do atendimento da Digivoice). A continuao do atendimento ser efetuada no evento OnAfterPickUp que gerado aps os 4 segundos passados no mtodo PickUp. Tambm chamamos aqui o mtodo SetDetectionType passando a porta e o parmetro dtDTMF que necessrio para que as placas entendam os tons gerados pelo telefone do cliente. Este mtodo chamado aqui mas tambm poderia ser chamado no evento OnAfterPickUp.
8.3
Concluso
Este exemplo prev uma srie de situaes comuns a sistemas de auto-atendimento, URA, etc.... Ele poder ser utilizada e modificada como ponto de partida para suas prprias aplicaes. Ateno: como a aplicao apresentada foi criada para fins didticos, a Digivoice no se responsabiliza pelo seu funcionamento em ambientes de produo. Caber aos desenvolvedores adequar e aprimorar seu funcionamento para atender suas necessidades especficas.
Aplicao Exemplo
111
8.4
Definindo Constantes para a Aplicao
Uma boa prtica para aplicaes de telefonica em tempo real a utilizao de estados. Nada mais so que variveis nas quais so atribudos valores diferenciados para cada situao possvel (falando, atendendo, esperando, etc...). Por ter mtodos assncronos, a VoicerLib exige do programador uma certa disciplina para manter o cdigo legvel e de fcil manuteno. O uso de estados ajuda neste aspecto. Para aumentar ainda mais a legibilidade de cdigo, definiremos constantes para cada estado possvel da aplicao, ao invs de utilizar o nmero literal na hora de atribuir valores aos estados. Observe o cdigo:
Estado := 6; //Ilegvel -> Dificil manuteno (....) Estado := TRANSFERENCIA; //Facilidade de manuteno
Isto no um procedimento obrigatrio mas, todos ho de convir que muito mais fcil trabalhar com palavras do que com valores. No Delphi, as constantes so definidas em qualquer janela ou mdulo, na rea const. Todas as linguagens conhecidadas tem seu equivalente. No caso do nosso exemplo, isto ser feito no form principal, pouco antes da palavra-chave implementation.
const //AS CONTANTES SERO DEFINIDAS AQUI //Voc deve digitar a palavra const tambm var Form1: TForm1; implementation
112
{$R *.DFM}
Obviamente voc pode ir definindo as constantes a medida que os estados vo aparecendo. Aqui j temos todos os estados que sero necessrios na execuo do programa:
const // Estados de Atendimento NADA = 1; BOASVINDAS = 3; ESPERA_DIGITOS_MENU = 4; ESPERA_DIGITOS_RAMAL = 5; TRANSFERENCIA = 6; TENTEMAISTARDE = 7; SUBMENU = 8; ESPERA_SUBMENU = 9;
Alm dos estados principais do fluxo de atendimento do programa, teremos tambm alguns estados que sero utilizados durante a transferncia e superviso das ligaes: os estados de ramais e de flash:
const // Estados de Atendimento NADA = 1; BOASVINDAS = 3; ESPERA_DIGITOS_MENU = 4; ESPERA_DIGITOS_RAMAL = 5; TRANSFERENCIA = 6; TENTEMAISTARDE = 7; SUBMENU = 8; ESPERA_SUBMENU = 9; //Estado de Ramais LIVRE = 0; OCUPADO = 1; NAOATENDE = 2; //Estados de Flash DISCA = 0; RETOMA = 1;
Aplicao Exemplo
113
Por ltimo temos algumas constantes que sero utilizadas no exemplo para simplificar as coisas. So configuraes de funcionamento da aplicao como ramal de fuga e toques para retomada. Em uma aplicao real estes valores ficam melhor em uma arquivo de configurao e lidos na inicializao da aplicao:
const (...colocar abaixo dos estado de flash.....) //Ramais de fuga (telefonista, portaria, etc...) RAMAL_FUGA1 = '220'; RAMAL_FUGA2 = '222'; //Toque para retomada da ligacao em caso do ramal //no atender NUMTOQUESRETOMADA = 5;
8.5
Finalizando a VoicerLib
A finalizao da biblioteca deve ser feita, preferencialmente, no ltimo evento chamado antes do trmino da aplicao. Aqui faremos isso no evento OnClose.
//Aqui testamos se a placa est inicializada //antes de finaliz-la if voice1.DriverEnabled then voice1.ShutdownVoicerLib;
114
8.6
Inicializando a VoicerLib
O mtodo StartVoicerLib deve ser utilizado para inicializar a(s) placa(s) que sero utilizadas. Aqui, como um programa de apenas uma janela, a biblioteca inicializada quando ela mostrada pela primeira vez, no evento OnShow.
//Indica se utiliza placa ISA (ctVPISA) ou PCI (ctVPPCI ou ctVBPCI) voice1.CardType := ctVPISA; //Inicializa e j testa se deu tudo certo if voice1.StartVoicerLib <> 99 then ShowMessage('Erro de Inicializao');
Antes da inicializao, a propriedade CardType preenchida com a constante ctVPISA que indica que sero utilizadas placas VoicerPhone ISA. Se fossem placas VoicerBox PCI/4, a constante deveria ser ctVBPCI e se for a placa Voicer Phone PCI/1, utiliza-se a constante ctVPPCI A funo StartVoicerLib retorna o set status. Qualquer valor diferente de 99 significa erro. Consulte o guia de referncia para saber os erros possveis e seus respectivos cdigos.
8.7
Inicializando o Estado da Aplicao
No mesmo lugar onde iniciamos o driver da placa (OnShow) necessrio inicializar a varivel Estado para o correto funcionamento.
//Inicializa e j testa se deu tudo certo if voice1.StartVoicerLib <> 99 then ShowMessage('Erro de Inicializao'); //Inicializao do Estado Inicial for i:=1 to 20 do
Aplicao Exemplo
115
Estado[i] := NADA;
O estado NADA indica que o canal no est fazendo nada, apenas esperando uma ligao chegar.
8.8
Iniciando o menu de atendimento
A frase de atendimento reproduzida a partir do evento OnAfterPickUp . No exemplo utilizamos o enfileiramento de mensagens para poder reproduzir a seqncia de mensagens: Digivoice Bom Dia Disque o nmero do ramal .... Neste caso, utilizamos 3 mensagens ao invs de uma simplesmente para poder implementar a facilidade do atendimento falar bom dia, boa tarde ou boa noite, conforme a hora da ligao. Tambm neste exemplo utilizamos frases de menu diferenciadas para o perodo comercial e no comercial. Para isso utilizaremos o conjunto de mtodos PlayListxxxxxxxx que disponibilizam uma lista de mensagens independente por canal. Isto importante porque cada canal das placas estaro em um ponto diferente de atendimento durante uma operao real. No evento OnAfterPickUp teremos:
procedure TForm1.voice1AfterPickUp(Sender: TObject; Port: Sma llint); begin //muda o estado Estado[Port] := BOASVINDAS; //limpa lista de frases do canal voice1.PlayListClear(Port);
116
//Adiciona a primeira frase voice1.PlayListAdd(Port,ptFile,'empresa.sig','',0 ); //bom dia boa tarde boa noite if ( (Time >= StrToTime('08:00:00')) and (Time <= StrToTime('12:00:00'))) then voice1.PlayListAdd(Port,ptFile,'bomdia. sig','',0) else if ( (Time > StrToTime('12:00:00')) and (Time <= StrToTime('18:00:00'))) then voice1.PlayListAdd(Port,ptFile,'boatarde.si g','',0) else voice1.PlayListAdd(Port,ptFile,'boanoite.si g','',0); //menu principal de acordo com o periodo if ( (Time >= StrToTime('07:59:00')) and (Time <= StrToTime('18:00:00'))) then voice1.PlayListAdd(Port,ptFile,'menu_dia.sig', '',0) else voice1.PlayListAdd(Port,ptFile,'menu_noite.sig ','',0); //inicia a reproducao das 3 mensagens em sequencia ret := voice1.PlayList(Port, '23456'); end;
No cdigo acima, primeiro setamos a varivel Estado com a constante BOASVINDAS, indicando que agora este canal encontra-se neste estado. Utilizamos a varivel Port como ndice do vetor pois ela passada como parmetro do evento OnAfterPickUp indicando a porta atual. Em seguida apagamos todo o contedo da lista de mensagens. Isto necessrio para que somente as mensagens seguintes sero reproduzidas, no ficando nenhuma do atendimento
Aplicao Exemplo
117
anterior. A primeira seqncia de ifs serve para o programa saber se fala "bom dia", "boa tarde" ou "boa noite", dependendo do hora do relgio do micro. O segundo if (menu principal) serve para o programa decidir se fala uma mensagem diurna ou uma noturna. Por fim, chamado o mtodo PlayList que comea as mensagem da lista,. Foi configurado que ela pode ser interrompida pelos dgitos 23456 (terceiro parmetro). Como o PlayList assncrono (assim como todos os outros mtodos) o fluxo de execuo continua aps o incio da mensagem. Desta maneira, o prximo tratamento deve ser feito quando terminar a mensagem, ou seja, no evento OnPlayStop ou o evento OnDigitReceived no caso da mensagem ser interrompida por dgitos.
8.9
Janela de Monitoramento
Apesar de no fazer parte propriamente do fluxo de atendimento, uma rea onde se monitora o que est acontecendo muito til. Aqui utilizamos um objeto TMemo, que uma rea de texto com possibilidade de inserir vrias linhas. O VisualBasic utiliza o TEditBox com a propriedade MultiLine igual a True. Voc tambm pode utilizar um ListBox. Criaremos uma procedure (sub-rotina) que simplesmente adiciona uma linha neste TMemo, junto com a hora e o canal corrente. Esta rotina chama-se InsereDado:
118
//Concatena hora e insere no TMemo procedure TForm1.InsereDado(nPorta:integer;sDado: string); begin memStatus.Lines.Add(TimeToStr(Time) + ': <' + IntToStr(nPorta)+'> '+sDado); end;
Desta maneira, sempre que quisermos adicionar um comentrio de status, bastar chamar a procedure InsereDado assim:
InsereDado(Porta,'Seu comentrio');
8.10
Transferncia e Superviso
Quando o usurio seleciona uma opo de menu ou disca um nmero de ramal, o atendedor tenta transferir para este ramal. Caso d ocupado ou no atender ele transfere para um ramal de fuga e se ainda assim no conseguir, transfere para outro ramal de fuga. Este ciclo idntico para o ramal desejado e para os ramais de fuga independente da quantidade. Por isso, utilizamos a tcnica de criar uma lista para os ramais que sero discados. Obviamente se o ramal desejado for atendido, a ligao entregue e o ciclo termina. Esta lista do tipo TStringList e se chama lstRamal. Ela deve ser declarada como global, criada no evento OnShow e destruda no evento OnClose. A superviso consiste no sistema monitorar se um ramal est sendo chamado sem sucesso, der ocupado ou ainda ser
Aplicao Exemplo
119
atendido. No caso de ramal ocupado, a VoicerLib gera o evento OnBusyDetected. J o tom de chamada gera o evento OnCalling e o atendimento deve ser tratado no evento OnAnswerDetected. No sistema de atendimento da Digivoice, como em tantos outros, para transferir a ligao necessrio dar um flash e em seguida discar o ramal desejado. O incio da discagem foi implementado no evento OnPlayStop porque sempre antes de transferir uma ligao o sistema falar "aguarde um instante..." como pode ser observado na listagem anterior (PlayFile). A mensagem "aguarde um instante..." no admite nenhum tipo de interrupo por dgito, por isso somente o caso ssNormal do evento OnPlayStop precisa ser considerado:
procedure TForm1.voice1PlayStop(Sender: TObject; Port, StopStatus: Smallint); begin case StopStatus of ssNormal: //MENSAGEM FOI ATE O FIM begin case Estado[Port] of (........) TRANSFERENCIA: begin if (lstRamal.Count > 0) then //ainda tem ramais begin if nEstadoRamal[Port] <> LIVRE then begin //verifica se nEstadoRamal[Port] := LIVRE; voice1.PlayFile(Port,'sisaguar.sig', ''); end else Begin //prepara discagem InsereDado(Port,'Executando
120
Flash...'); nEstadoFlash[Port] := DISCA; voice1.Flash(Port,700,1500); end; end else begin //Acabaram os ramais da lista //Fala "tente mais tarde" Estado[Port] := TENTEMAISTARDE; voice1.PlayFile(Port,'MAISTARD.SIG','' ); end; end; TENTEMAISTARDE: begin Sleep(100); voice1.HangUp(Port); Estado[Port] := NADA; InsereDado(Port,'No ouve atendimento. Desligado!'); InsereDado(Port,'Esperando nova ligao...'); end; end; ssDigitReceived: begin (........) end; //submenu end; (........)
Repare que a lgica de tratamento da lista idntica lista de frases de boas vindas no incio do atendimento. Cada vez que o sistema entrar neste bloco, ele ter discado para o ramal, supervisionado e detectado que o ramal no atendeu o estava ocupado. Isto se repetir at que a lista lstRamal esteja vazia. Quando isso acontecer, o sistema falar "tente mais tarde", sair da rotina e voltar a ela no tratamento do estado TENTEMAISTARDE que desligar e colocar no estado NADA, pronto para esperar uma nova ligao.
Aplicao Exemplo
121
Mais uma vez reforamos esta caracterstica assncrona que a VoicerLib tem. Repare que dentro do evento OnPlayStop executado o PlayFile. O fluxo continua e sai do OnPlayStop. Quando a mensagem termina o evento chamado novamente. No se trata de recursividade. O primeiro bloco da rotina anterior inicia a transferncia atravs do comando Flash. Antes necessrio atribuir a varivel nEstadoFlash com o valor DISCA para que possa ser diferenciado a situao de flash para discar e flash para retomar a ligao (em caso de ocupado ou no atender). Como o flash um comando lento, sua concluso dar-se- no evento OnAfterFlash:
procedure TForm1.voice1AfterFlash(Sender: TObject; Port: Smallint); begin case nEstadoFlash[Port] of DISCA: begin InsereDado(Port,'Discando para o Ramal ' + lstRamal.S trings[0]); voice1.Dial(Port, lstRamal.Strings[0],1000); nChamando[Port] := 1; end; (......)
A varivel nChamando[Port] inicializada em 1 para contar os toques de chamada. No nosso sistema as ligaes so retomadas aps 5 toques. O incio da superviso se dar aps a discagem no evento OnAfterDial:
procedure TForm1.voice1AfterDial(Sender: TObject; Port:
122
S mallint); begin case Estado[Port] of TRANSFERENCIA: begin InsereDado(Port,'Iniciando Superviso...'); voice1.EnableCallProgress(Port); voice1.EnableAnswerDetection(Port); //12 segundos ate o primeiro toque nContaTimeOutAtende[Port] := 12; end; end; end;
A superviso iniciada com o EnableCallProgress que monitora os tons de "chamando" e ocupado e o EnableAnswerDetection que monitora o atendimento. Com a placa VoicerPhone utilizando um headset necessrio desligar o microfone antes de habilitar as supervises de linha Neste momento o sistema dever estar preparado para 3 situaes: atendimento, ocupado e no atende. O atendimento poder ser tratado de duas maneiras: a primeira atravs da deteco propriamente dita que gera o evento OnAnswerDetected:
procedure TForm1.voice1AnswerDetected(Sender: TObject; Port: Smallint); begin case Estado[Port] of TRANSFERENCIA: begin voice1.DisableAnswerDetection(Port); voice1.DisableCallProgress(Port); InsereDado(Port,'Ligao Entregue. Esperando nova...');
Aplicao Exemplo
123
voice1.HangUp(Port); Estado[Port] := NADA; end; end; end;
A segunda forma de deteco de atendimento no envolve comandos da placa. Em algumas ocasies a placa poder no detectar o atendimento atravs do mtodo acima. Isso devido a condies de linha, etc... Nestes casos o sistema jamais entenderia o atendimento e consequentemente no transferiria a ligao, causando um comportamento indesejado. Para cobrir 100% das vezes necessrio criar um timeout para atendimento atravs de um componente do tipo Timer, colado no form. Este timer seria utilizado da seguinte maneira.
procedure TForm1.tmrGeralTimer(Sender: TObject); var Port: integer; begin for Port := 1 to 20 do begin case Estado[Port] of TRANSFERENCIA: begin Dec(nContaTimeOutAtende[Port]); if nContaTimeOutAtende[Port] = 0 then begin //timeout, significa que atendeu InsereDado(Port,'Timeout de atendimento'); //chama a rotina que trata o atendimento voice1AnswerDetected(Sender,Port); end; end; end; end; end;
A partir do momento que o sistema disca, considera-se que, se no houver sinal de chamada ou ocupado por um determinado
124
tempo, houve um atendimento. Por isso que no evento OnAfterDial a varivel nContaTimeOutAtende inicializada com 12, indicando que o sistema esperar at 12 segundos para o primeiro sinal de chamada (OnCalling). Aps o primeiro, o timeout cair para 8 segundos entre cada sinal de chamada. Para maiores detalhes observe tambm a listagem do evento OnCalling logo a seguir. Ao ser detectado o atendimento, importante desabilitar todas as supervises para no interferir no funcionamento do prximo atendimento. Em seguida desliga-se e muda a varivel Estado para NADA. A cada sinal de "chamando" o evento OnCalling chamado:
procedure TForm1.voice1Calling(Sender: TObject; Port: Smallint); begin case Estado[Port] of TRANSFERENCIA: begin InsereDado(Port,IntToStr(nChamando[Port])+ 'o. Toque...'); //8 segundos ate os proximos toques nContaTimeOutAtende[Port] := 8; if nChamando[Port] > NUMTOQUESRETOMADA then begin //deu ocupado voice1.DisableAnswerDetection(Port); Sleep(10); voice1.DisableCallProgress(Port); InsereDado(Port,'Ramal no atende...'); nEstadoRamal[Port] := NAOATENDE; nEstadoFlash[Port] := RETOMA; voice1.Flash(Port,700,1500); end else Inc(nChamando[Port]); end; end;
Aplicao Exemplo
125
end;
A varivel nChamando[Port] incrementada a cada tom recebido. Se ela ultrapassar NUMTOQUESRETOMADA o programa prepara a retomada da ligao. Seta a varivel nEstadoRamal para NAOATENDE e a nEstadoFlash para RETOMA. A primeira necessria para falar "ramal no atende" e a segunda para o tratamento especfico de retomada no evento OnAfterFlash (listada mais adiante): No caso de dar ocupado, o evento OnBusyDetected gerado:
procedure TForm1.voice1BusyDetected(Sender: TObject; Port: Smallint); begin case Estado[Port] of TRANSFERENCIA: begin //deu ocupado na transferencia voice1.DisableAnswerDetection(Port); Sleep(10); voice1.DisableCallProgress(Port); InsereDado(Port,'Ocupado na Superviso...'); nEstadoRamal[Port] := OCUPADO; nEstadoFlash[Port] := RETOMA; voice1.Flash(Port,700,1500); end; else begin //qualquer outro caso desliga Sleep(100); voice1.HangUp(Port); Estado[Port] := NADA; InsereDado(Port,'Cliente Desligou.'); InsereDado(Port,'Esperando nova ligao...'); end; end; end;
Voc tem o caso de TRANSFERENCIA e todos os outros no

126
bloco else. Nos casos diferentes de transferncia, ao receber um ocupado o sistema simplesmente desliga a ligao e volta o Estado para NADA, esperando novas chamadas. No caso de TRANSFERENCIA o sistema desabilita as supervises, seta a varivel nEstadoRamal para OCUPADO e a nEstadoFlash para RETOMA. A primeira necessria para falar "ramal ocupado" e a segunda para o tratamento especfico de retomada no evento OnAfterFlash:
procedure TForm1.voice1AfterFlash(Sender: TObject; Port: Smallint); begin case nEstadoFlash[Port] of (......) RETOMA: begin InsereDado(Port,'Retomando Ligao...'); try lstRamal.Delete(0); except end; //fala ramal ocupado ou ramal nao atende if nEstadoRamal[Port] = OCUPADO then begin voice1.PLayFile(Port,'SISROCUP.SIG',' ') end else begin voice1.PLayFile(Port,'SISRNAOA.SIG', ''); end; end; (......)
Ao retomar a ligao, depois do flash, necessrio excluir o primeiro ramal da lista (para que o prximo se torne o ramal corrente) e falar "ramal ocupado" ou "ramal no atende". A discagem para o prximo ramal (se houver) ser iniciada
Aplicao Exemplo
127
novamente no evento OnPlayStop (consulte a listagem da pgina 70). Este ciclo se repetir at que no haja mais ramais.
8.11
Tratamento de Entrada de Dados
O evento OnPlayStop chamado sempre quando uma mensagem termina, portanto este evento ser chamado diversas vezes durante o atendimento. Ele junto com o evento OnDigitsReceived so os mais complexos do exemplo e merecem maior ateno. Nesta primeira parte do tratamento do OnPlayStop, contemplaremos apenas a execuo em seqncia da mensagem de boas vindas. O evento OnPlayStop passa o status como parmetro atravs da varivel StopStatus. No nosso atendimento necessrio tratar duas situaes.: quando a mensagem termina normalmente ou quando ela interrompida por causa do recebimento de um dgito. No primeiro caso a varivel StopStatus recebe o valor ssNormal. Nesta situao o sistema ficar em silncio por 5 segundos esperando a digitao do ramal ou opo de menu pelo usurio.
procedure TForm1.voice1PlayStop(Sender: TObject; Port, StopStatu s: Smallint); Begin case StopStatus of ssNormal: //MENSAGEM FOI ATE O FIM begin case Estado[Port] of BOASVINDAS: begin //aqui espera 1 digito que pode ser a opo //de menu ou o primeiro digito
128
do ramal InsereDado(Port,'Esperando Digitao'); Estado[Port] := ESPERA_DIGITOS_MENU; voice1.GetDigits(Port,1,'',5000 ,5000); //habilita espera de ocupado voice1.EnableCallProgress(port) ; //Habilita deteco de pulso voice1.EnablePulseDetection(Por t); end; end; end; end;
Este if acima trata o caso de as mensagens de boas vindas terem sido reproduzidas sem a interrupo do usurio. O fluxo de atendimento pede que aps a mensagem o sistema fique 5 segundos em silncio esperando a digitao do usurio. Isto feito apenas com a chamada a funo GetDigits. No cdigo apresentado o GetDigits indica que a VoicerLib esperar por 1 digito que poder ser a opo de menu ou o primeiro dgito do ramal. O tratamento desta funo GetDigits ser feito no OnDigitsReceived, explicado mais adiante. Repare que o estado alterado para ESPERA_DIGITOS_MENU para que o evento OnDigitsReceived saiba qual a situao a tratar. Ainda preciso prever a situao do usurio teclar algo sobre a mensagem. At a verso 2.0 isto deveria ser feito no evento OnPlayStop. A partir da verso 2.1, o evento OnDigitsReceived tambm gerado quando um dgito detectado durante a reproduo de mensagem sendo que a varivel Status recebe o valor edDigitOverMessage para indicar a situao. Isto faz com que
Aplicao Exemplo
129
tanto o tratamento de dgito sobre a mensagem como o gerado a partir do mtodo GetDigits sejam tratados em um nico lugar, no caso, o evento OnDigitReceived. Agora apresentaremos o caso de dgito sobre mensagem. Se for o primeiro dgito da numerao de ramais (dois no nosso exemplo) o sistema dever ficar esperando os proximos 2 dgitos. Se for outro, deve ser tratado como opo de menu.
procedure TForm1.voice1DigitsReceived(Sender: TObject; Port, Status: Smallint); var ret: integer; begin case Status of EdMaxDigits, edDigitOverMessage: //msg interrompida por digito begin case Estado[Port] of ESPERA_DIGITOS_MENU, BOASVINDAS: begin InsereDado(Port, 'Tratamento de Digito aps mensagem'); TrataPrimeiroDigito(Port); {<IMPORTANTE} end; end; end; end; end;
O case mais externo (Status) testa se o valor EdMaxDigits ou edDigitOverMessage. O primeiro indicar que a mensagem de boas vindas foi executada at o fim e o mtodo GetDigits foi acionado, conforme mostrado no cdigo da pgina anterior. J o segundo indica que a mensagem foi interrompida por dgito. Como o tratamento o mesmo para os dois casos, o fato de
130
separarmos as constantes por virgula indica um OU outro. A funo TrataPrimeiroDigito uma subrotina que verificar se ramal ou opo de menu. Este cdigo foi colocado em uma subrotina para deixar o programa mais organizado. Eis o cdigo da rotina TrataPrimeiroDigito:
procedure TForm1.TrataPrimeiroDigito(Port: smallint); begin if Copy(voice1.ReadDigits(Port),1,1) = '2' then begin InsereDado(Port,'Esperando resto do ramal'); Estado[Port] := ESPERA_DIGITOS_RAMAL; voice1.GetDigits(1,3,'',5000,5000); end else begin nOpMenu[Port] := StrToInt(Copy(voice1.ReadDigits( Port),1,1)); if rcMenu[nOpMenu[Port]].sRamalMenu <> '' then begin //disca direto //adiciona o ramal lstRamal.Add(rcMenu[nOpMenu[Port]].sRama lMenu); //adiciona fuga lstRamal.Add(RAMAL_FUGA1); lstRamal.Add(RAMAL_FUGA2); Estado[Port] := TRANSFERENCIA; nEstadoRamal[Port] := LIVRE; //aguarde um instante... voice1.PlayFile(Port,'sisaguar.sig',''); end else if rcMenu[nOpMenu[Port]].sFrase <> '' then begin voice1.ClearDigits(Port);
Aplicao Exemplo
131
Estado[Port] := SUBMENU; //fala submenu voice1.PlayFile(Port, rcMenu[nOpMenu[Port]].sFr ase, rcMenu[nOpMenu[Port]].sOp coesSubMenu); end else begin //estrutura errada, sem ramal nem submenu //ento vai parafuga (.....) end; end; end;
Aqui importante entender um detalhe de implementao do aplicativo exemplo. Como ele prev a possibilidade de menus e sub-menus era necessrio criar uma estrutura de dados que simplificasse a codificao desta necessidade. No exemplo, se o usuario escolher a opo de menu 3, por exemplo, ele ir para um sub-menu com duas opes. Cada uma destas duas opes transfere para um ramal diferente. J a opo 6, transfere para um ramal diretamente, sem submenu. O esquema abaixo ilustra a estrutra de menu e sub-menu do nosso exemplo:
132
No programa, foi criado uma estrutura do tipo record da seguinte maneira:

TrcMenu = record sRamalMenu: string; //se for vazio pq tem submenu sFrase: string; //preenhida no caso de submenu sOpcoesSubMenu: string; end;
Em seguida foram criadas duas variveis globais, uma do tipo acima que contemplar o menu e outra do tipo string que contemplar os ramais de sub-menu.
Public (......) rcMenu: array[0..9] of TrcMenu; sRamalSubMenu:array[0..9,0..9] of string; (......)
A varivel rcMenu um vetor de 0 9 pois utilizaremo o ndice do vetor como a opo digitada pelo usurio. Por exemplo, se o usurio digitar a opo 3, pegaremos a varivel rcMenu ndice 3
Aplicao Exemplo
133
(rcMenu[3]) para saber se deve tem sub-menu ou discagem para ramal direto. J o array sRamalSubMenu um vetor bidimencional, onde o primeiro ndice a opo de menu, e o segundo a opo de sub-menu. Desta maneira, quando o usurio escolher o menu e em seguida o sub-menu, o programa j saber para qual ramal discar: sRamalSubMenu[op_menu,op_submenu]. No evento OnShow do form, inicializaremos essas duas variveis com a configurao do nosso atendendor. Aqui tudo est hardcoded mas em uma aplicao real interessante ter estes dados lidos de arquivos de configurao.
procedure TForm1.FormShow(Sender: TObject); (.........) //estrutura de menus e submenus rcMenu[3].sRamalMenu := ''; rcMenu[3].sFrase := 'sub_coml.sig'; rcMenu[3].sOpcoesSubMenu := '12'; rcMenu[4].sRamalMenu := ''; rcMenu[4].sFrase := 'sub_sup.sig'; rcMenu[4].sOpcoesSubMenu := '12'; rcMenu[5].sRamalMenu := ''; rcMenu[5].sFrase := 'sub_fax.sig'; rcMenu[5].sOpcoesSubMenu := '12'; rcMenu[6].sRamalMenu := '241'; rcMenu[6].sFrase := ''; //submenu sRamalSubMenu[3][1] := '231'; //cons final sRamalSubMenu[3][2] := '220'; //revendas sRamalSubMenu[4][1] := '212'; //sup soft sRamalSubMenu[4][2] := '211'; //tecnica sRamalSubMenu[5][1] := '202'; //fax coml sRamalSubMenu[5][2] := '235'; //fax tec (.........) end;
A estrutura rcMenu funciona da seguinte forma: se o campo

134
sRamalMenu tiver algum valor, significa que no h sub-menu e deve discar direto para o ramal (caso do ndice 6). Caso contrrio, o campo sFrase dever estar preenchido com a mensagem a ser reproduzida com o sub-menu e o campo sOpcoesSubMenu contm os dgitos a serem aceitos como opes de cada um dos sub-menus. Agora, voltemos a comentar o cdigo da rotina TrataPrimeiroDigito da pgina 71. O primeiro if (abaixo) verifica se o primeiro dgito recebido 2, que no nosso caso significa o incio de um ramal, pois todos os ramais comeam com 2.
(....) if Copy(voice1.ReadDigits(Port),1,1) = '2' then begin InsereDado(Port,'Esperando resto do ramal'); Estado[Port] := ESPERA_DIGITOS_RAMAL; voice1.GetDigits(Port,3,'',5000,5000); end else (....)
O programa dever ento esperar os outros dois dgitos do ramal. Repare que a funo GetDigits passa o 3 como segundo parmetro, indicando que deve esperar 3 dgitos. Isto est correto pois, como a propriedade AutoClearDigits est false, o buffer de dgitos do canal j entra com aquele nmero 2 digitado anteriormente, restando apenas mais 2 nmeros a serem digitados para completar os 3 que a funo GetDigits est esperando. Em resumo, o segundo parmetro da funo GetDigits indica, na realidade, quantos dgitos devem existir no buffer interno de dgitos do canal e no quantos dgitos devem ser digitados a partir de sua chamada (Se a propriedade AutoClearDigits estiver true, as duas situaes se equivalem). No else do if acima est o tratamento da situao de ter sido
Aplicao Exemplo
135
digitado um dgito diferente do plano de numerao de ramais. Ento dever ser verificado se o dgito uma opo de menu vlida para sub-menu ou para transferncia direta. Observe a poro de cdigo abaixo:
(....) else begin nOpMenu[Port] := StrToInt(Copy(voice1.ReadDigits( Port),1,1)); if rcMenu[nOpMenu[Port]].sRamalMenu <> '' then begin //disca direto //adiciona o ramal lstRamal.Add(rcMenu[nOpMenu[Port]].sRama lMenu); //adiciona fuga lstRamal.Add(RAMAL_FUGA1); lstRamal.Add(RAMAL_FUGA2); Estado[Port] := TRANSFERENCIA; nEstadoRamal[Port] := LIVRE; //aguarde um instante... voice1.PlayFile(Port,'sisaguar.sig',''); end else (....)
Para facilitar, atribumos varivel nOpMenu[Port] o nmero da opo digitada pelo usurio. Ela deve ser declarada como global. um array de 20 posies para prever at 20 canais:
(....) public nOpMenu: array[1..20] of integer; //menu nOpSubMenu: array[1..20] of integer; //submenu (....)
136
O if rcMenu[nOpMenu[Port]].sRamalMenu <> '' testa se o campo sRamalMenu tem algum contedo. Se tiver, entra no bloco deste if e trata a discagem direta ao ramal. Aqui pressupomos que o contedo de sRamalMenu ser um ramal vlido. Quando o sistema disca para o ramal, existe a possibilidade de o ramal estar ocupado ou no atender. No nosso aplicativo, caso isso acontea o sistema tentar transferir para os ramais de fuga que so dois. Utilizamos a mesma tcnica das mensagens em seqncia, criando uma lista para os ramais. O tratamento de transferncia ser explicado em detalhes no item "Transferncia e Superviso". Ainda na rotina TrataPrimeiroDigito temos a necessidade de tratar o caso de sub-menu:
procedure TForm1.TrataPrimeiroDigito(Port: smallint); begin if Copy(voice1.ReadDigits(Port),1,1) = '2' then begin (.......) end else begin nOpMenu[Port] := StrToInt(Copy(voice1.ReadDigits( Port),1,1)); if rcMenu[nOpMenu[Port]].sRamalMenu <> '' then begin (.......) end else if rcMenu[nOpMenu[Port]].sFrase <> '' then begin voice1.ClearDigits(Port); Estado[Port] := SUBMENU;
Aplicao Exemplo
137
//fala submenu voice1.PlayFile(Port, rcMenu[nOpMenu[Port]].sFr ase, rcMenu[nOpMenu[Port]].sOp coesSubMenu); end else (.......)
No bloco que trata o sub-menu, o sistema ter que falar uma nova mensagem e em seguida esparar a digitao de uma das opes propostas. Ento necessrio apagar o buffer interno de dgitos atravs do mtodo ClearDigits(port) , mudar o estado da aplicao para SUBMENU e iniciar a reproduo da mensagem de sub-menu (PlayFile). Toda esta entrada de dados pode ser simplificada com os mtodos Menuxxx e Promptxxx.
8.12
Tratamento de Sub-Menu
O estado de SUBMENU muito semelhante ao de BOAS VINDAS pois reproduz uma mensagem e espera opes. A nica diferena que no SUBMENU no existe a possibilidade de digitar o ramal diretamente. Desta forma teremos que fazer tratamentos no evento OnPlayStop para quando a mensagem de sub-menu acabar e no evento OnDigitsReceived para tratar as opes digitadas durante ou aps a mensagem de sub-menu. No evento OnPlayStop, como foi dito, podemos ter a situao da mensagem de sub-menu ter sido reproduzida at o fim (StopStatus = ssNormal).
138
Neste caso, deveremos esperar at 5 segundos para digitao da opo.

procedure TForm1.voice1PlayStop(Sender: TObject; Port, StopStatus: Smallint); begin case StopStatus of ssNormal: //MENSAGEM FOI ATE O FIM begin case Estado[Port] of (.......) SUBMENU: begin //mensagem de sub menu terminou corretamente //espera as opcoes voice1.ClearDigits(Port); InsereDado(Port,'Espera opcao de submenu'); Estado[Port] := ESPERA_SUBMENU; voice1.GetDigits(Port,1,'',5000,5000) ; //para esperar o ocupado voice1.EnableCallProgress(Port); end; //fim estado submenu end; end; end;
Devemos fazer este tratamento dentro do bloco ssNormal pois a mensagem terminou sem interrupo e no case do Estado de SUBMENU. Primeiro apagamos os dgitos do buffer interno atravs do ClearDigits. Em seguida entramos na espera de um dgito por 5 segundos (GetDigits). Aqui, aps chamar o GetDigits, habilitamos a deteo de tom com o mtodo EnableCallProgress(Port) para que seja possvel detectar o sinal de ocupado. Com isso o programa poder desligar caso o usurio desligue
Aplicao Exemplo
139
antes de completar a chamada. Da mesma forma que na mensagem principal, aqui trataremos a situao de dgito sobre mensagem ou durante o silncio aps a mensagem no evento OnDigitsReceived.
procedure TForm1.voice1DigitsReceived(Sender: TObject; Port, Status: Smallint); var ret: integer; begin case Status of EdMaxDigits, edDigitOverMessage: //msg interrompida por digito begin case Estado[Port] of ESPERA_DIGITOS_MENU, BOASVINDAS: begin (.....) end; ESPERA_SUBMENU, //tratamento de submenu SUBMENU: begin //recebeu um dos digitos esperados disca para //o ramal voice1.DisablePulseDetection(Port); //testa se eh digito valido entre 0 e 9 nOpSubMenu[Port] := StrToInt(Copy( voice1.ReadDigits (Port),1,1)); //insere ramais para transferencia lstRamal[Port].Clear; if sRamalSubMenu[nOpMenu[Port]] [nOpSubMenu[Port ]] <> '' then
140
lstRamal[Port].Add(sRamalSubMenu[nO pMenu[Port]] [nOpSub Menu[Port]]); //adiciona fuga lstRamal[Port].Add(RAMAL_FUGA1); lstRamal[Port].Add(RAMAL_FUGA2); Estado[Port] := TRANSFERENCIA; nEstadoRamal[Port] := LIVRE; //aguarde um instante... voice1.PlayFile(Port,'sisaguar.sig',' ',0); end; end; end; end; end;
Como as opes de sub-menu requerem somente um dgito, o tratamento de digito sobre mensagem recai no bloco de programa mostrado acima, onde o sistema pega a opo de sub-menu e disca para o ramal. Aqui tambm utilizamos o recurso de criar uma lista para discar para os ramais em seqncia no caso de algum no atender ou estar ocupado. A varivel Estado deve mudar para o estado de TRANSFERENCIA e pela primeira vez utilizada a varivel nEstadoRamal, que guardar se o ramal deu ocupado ou no atendeu. Isto apenas necessrio para o sistema falar "ramal ocupado" ou "ramal no atende".
8.13
Variveis Globais da Aplicao
Algumas variveis de controle necessitam ser declaradas como globais, para poderem ser acessadas de qualquer ponto da aplicao. No nosso exemplo, declaramos na rea private da declarao do form, para que elas sejam globais apenas para esta janela. Isto mera implementao. Voc pode declar-las
Aplicao Exemplo
141
em outro lugar, contanto que sejam globais. Nem todas as variveis sero inseridas neste momento. Faremos isso a medida que elas vo aparecendo no programa. Lembre-se: sempre que for comentado que a varivel global, declare-a neste mesmo ponto. A primeira e principal varivel global a que conter o estado em que o fluxo de atendimento se encontra. Como temos que prever o tratamento independente de vrios canais, necessrio que ela seja um vetor (ou array). Vamos declar-la como um vetor de 20 posies:
TForm1 = class(TForm) memStatus: TMemo; (.. outras linhas que nao vem ao caso..) private { Private declarations } Estado: array[1..20] of integer;
Declaramos com 20 posies, permitindo que se trate at 20 portas na mesma aplicao (canal 1 ao 20). A VoicerLib suporta atualmente at 24 portas por computador.
Parte
IX
Guia de Referncia
144
9
9.1
9.1.1
Guia de Referncia
Propriedades
AutoClearDigits
Tipo: Boolean Funo: Determina se o buffer interno de dgitos de cada canal deve ser apagado ou no, automaticamente antes da chamada dos mtodos GetDigits, PlayFile ou RecordFile. Descrio: Se a propriedade AutoClearDigits for true, sempre que um dos mtodos GetDigts, PlayFile ou RecordFile forem chamados, o contedo ddo buffer de dgitos apagado automaticamente. Se AutoClearDigits for false, o buffer de dgitos ir acumulando os dgitos recebidos, at que o mtodo ClearDigits( ) seja chamado explicitamente. Exemplo: Delphi:
VoicerLibX1.AutoClearDigits := true;
Visual Basic:
VoicerLibX1.AutoClearDigits = True
9.1.2
CardsCount
Tipo: Integer
Guia de Referncia
145
Funo: Devolve a quantidade de placas instaladas Descrio: uma propriedade readonly e disponvel somente em runtime. Ela informa quantas placas esto em funcionamento no sistema. Exemplo:
Delphi: X := VoicerLibX1.CardsCount; Visual Basic: X = VoicerLibX1.CardsCount
9.1.3
CardType
Tipo: Integer Funo: Determina o tipo da placa instalada na mquina. Descrio: Podendo assumir os valores ctVPISA para placas VoicerPhone ISA e ctVBPCI para placas VoicerBox PCI/4. Quando o sistema trabalhar com placas ISA necessrio ter um arquivo de configurao definido, atravs do utilitrio GERAINI.EXE. Exemplo:
Delphi: VoicerLibX1.CardType := ctVPISA; Visual Basic: VoicerLibX1.DelayComma = ctVPISA
146
9.1.4
ConfigFile
Tipo: String Funo: Determina o arquivo e o caminho de configurao para as placas VoicerPhone ISA. Descrio: Esta propriedade permite ao programador customizar o nome e o caminho do arquivo de configurao para as placas ISA. O padro, voicerlib.ini, ser procurado no diretrio do Windows. Exemplo:
Delphi: VoicerLibX1.ConfigFIle := 'c:\teste\meuconfig.ini'; Visual Basic: VoicerLibX1.ConfigFIle = "c:\teste\meuconfig.ini"
9.1.5
DelayComma
Tipo: Integer Funo: Determina o tempo em milissegundos para a pausa relativa ao caracter "," (vrgula) . Descrio: Quando o mtodo Dial( ) chamado, um dos parmetros passados uma string contendo uma seqncia de dgitos a serem discados pela placa. Ser dado uma pausa entre os dgitos anterior e posterior "vrgula", cujo tempo determinado pela propriedade DelayComma, para cada "vrgula" da string. Exemplo: Para discar o digito ZERO, uma pausa de 1 segundo
Guia de Referncia
147
(1000 milissegundos) e o resto do nmero em seqncia, utilize: Delphi:

VoicerLibX1.DelayComma := 1000; VoicerLibX1.Dial('0,72952557');
Visual Basic:
VoicerLibX1.DelayComma = 1000 VoicerLibX1.Dial("0,72952557")
Veja Tambm: DelaySemicolon, DelayDot, Dial
9.1.6
DelayDot
Tipo: Integer Funo: Determina o tempo em milissegundos para a pausa relativa ao caracter "." (ponto) . Descrio: Quando o mtodo Dial( ) chamado, um dos parmetros passados uma string contendo uma seqncia de dgitos a serem discados pela placa. Ser dado uma pausa entre os dgitos anterior e posterior ao "ponto", cujo tempo determinado pela propriedade DelayDot, para cada "ponto" da string. Exemplo: Para discar o digito ZERO, uma pausa de 1 segundo (1000 milissegundos) e o resto do nmero em seqncia, utilize: Delphi:
VoicerLibX1.DelayDot := 1000; VoicerLibX1.Dial('0.72952557',0);
Visual Basic:
VoicerLibX1.DelayDot = 1000 VoicerLibX1.Dial("0.72952557",0);
148
Veja Tambm: DelaySemicolon, DelayComma, Dial
9.1.7
DelaySemicolon
Tipo: Integer Funo: Determina o tempo em milissegundos para a pausa relativa ao caracter ";" (ponto-e-vrgula) . Descrio: Quando o mtodo Dial( ) chamado, um dos parmetros passados uma string contendo uma seqncia de dgitos a serem discados pela placa. Ser dado uma pausa entre os dgitos anterior e posterior ao "ponto-e-vrgula", cujo tempo determinado pela propriedade DelaySemicolon, para cada "ponto-e-vrgula" da string. Exemplo: Para discar o digito ZERO, uma pausa de 1 segundo (1000 milissegundos) e o resto do nmero em seqncia, utilize: Delphi:
VoicerLibX1.DelaySemicolon := 1000; VoicerLibX1.Dial('0;72952557');
Visual Basic:
VoicerLibX1.DelaySemicolon = 1000 VoicerLibX1.Dial("0;72952557")
Veja Tambm: DelayComma, DelayDot, Dial
9.1.8
DialType
Tipo: EnumDialType { dtPulse=0, dtTone=1}
Guia de Referncia
149
Funo: Determina o tipo de discagem que a placa ir realizar: PULSO ou TOM. A partir da verso 2.57 esta propriedade ainda existe mas est obsoleta e no tem efeito nenhum se for utilizada. Para determinar o tipo de discagem deve-se utilizar o parmetro do mtodo Dial.
9.1.9
DriverEnabled
Tipo: Boolean Funo: Determina o estado de funcionamento da placa. Descrio: A propriedade DriverEnabled do tipo "ReadOnly" e s est disponvel em tempo de execuo. Se a interrupo estiver ocorrendo DriverEnabled assume True, caso contrrio assume False. O evento OnErrorDetected pode ser utilizado para diagnosticar rapidamente a falha de processamento. Exemplo: Tratamento de erro utilizando o evento OnErrorDetected: Delphi:
if (not VoicerLibX1.DriverEnabled) then ShowMessage("Placa Inativa!");
Visual Basic:
if not VoicerLibX1.DriverEnabled then MsgBox "Placa Inativa" End if
Veja Tambm: OnErrorDetected
150
9.1.10 DriverVersion
Tipo: Integer Funo: Mostra a verso interna do Driver da VoicerLib Descrio: A propriedade DriverVersion do tipo "ReadOnly" e s est disponvel em tempo de execuo. Ela exibe a verso da VoicerLib e ideal para verificar com facilidade qual a verso instalada no computador.
9.1.11 FirmwareVersion
Tipo: Integer Funo: Mostra a verso interna do firmware das placas Digivoice. Descrio: A propriedade FirmwareVersion do tipo "ReadOnly" e s est disponvel em tempo de execuo. Ela exibe a verso do firmware das placas da Digivoice (firmware o programa que roda dentro do hardware).
9.1.12 ForcePlay
Tipo: Boolean Funo: Indica o tipo de tratament a ser dado no caso de erros de reproduo de arquivo.
Guia de Referncia
151
Descrio: At a verso 2.4, ao tentar reproduzir um arquivo e outro j estar sendo reproduzido, a biblioteca voltada erro. Se a propriedade ForcePlay estiver com valor True, o novo arquivo a ser reproduzido interromper o anterior e sua reproduo iniciar. Se o valor estiver False (default) o comportamento ser como antes.
9.1.13 PortsCount
Tipo: Integer Funo: Devolve a quantidade de canais disponiveis. Descrio: uma propriedade readonly e disponvel somente aps iniciar o driver. Exemplo:
Delphi: X := VoicerLibX1.PortsCount; Visual Basic: X = VoicerLibX1.PortsCount
9.1.14 StockSigs
Tipo: String Funo: Determina o caminho onde sero encontradas os arquivos SIG utilizados para reproduzir valores por extenso, data, etc...
152
Descrio: Ao distribuir uma aplicao onde so utilizadas as funes PlayCurrency, PlayDate, PlayTime, PlayNumber ou PlayList, o desenvolvedor necessita tambm enviar as mensagens a serem utilizadas. Esta propriedade permite configurar o caminho para estas mensagens. Exemplo: Delphi:
VoicerLibX1.StockSigsPath := 'r:\frasespadrao';
Visual Basic: VoicerLibX1.StockSigsPath = "r:\frasespadrao" A seguir apresentamos os nomes dos arquivos fornecidos com a biblioteca e a respectiva frase que reproduz.
Guia de Referncia
153
Arquivo SIG
Frase
Arquivo SIG
Frase
Hora.sig Minuto.sig Segundo.sig Reais.sig Centavo.sig Cento.sig 200.sig 400.sig 600.sig 800.sig Mil.sig milhoes.sig bilhoes.sig trilhoes.sig Ponto.sig
Hora Minuto Segundos Reais Centavo Cento Duzentos Quatrocentos
Horas.sig Minutos.sig Real.sig DeReais.sig Centavos.sig 100.sig 300.sig 500.sig 700.sig 900.sig milho.sig bilho.sig trilho.sig Virgula.sig De.sig
Horas Minutos Real De Reais Centavos Cem Trezentos Quinhento s Setecento s Novecento s Milho Bilho Trilho Vrgula De
Seiscentos
Oitocentos Mil Milhes Bilhes Trilhes Ponto
154
Arquivo SIG
Frase
Arquivo SIG
Frase
e.sig traco.sig 1.sig 3.sig 5.sig 7.sig 9.sig 11.sig 13.sig 15.sig 17.sig 19.sig
Arquivo SIG
E Trao Um Trs Cinco Sete Nove Onze Treze Quinze Dezessete Dezenove
Frase
Barra.sig 0.sig 2.sig 4.sig 6.sig 8.sig 10.sig 12.sig 14.sig 16.sig 18.sig 20.sig
Arquivo SIG
Barra Zero Dois Quatro Seis Oito Dez Doze Quatorze Dezessei s Dezoito Vinte
Frase
30.sig 50.sig 70.sig 90.sig Fevereiro.sig Abril.sig Junho.sig Agosto.sig Outubro.sig Dezembro.sig
Trinta Cinqenta Setenta Noventa Fevereiro Abril Junho Agosto Outubro Dezembro
40.sig 60.sig 80.sig Janeiro.sig Marco.sig Maio.sig Julho.sig Setembro.sig Novembro.sig
Quarenta Sessenta Oitenta Janeiro Maro Maio Julho Setembro Novembr o
Caso o desenvolvedor queira fazer sua prpria locuo ou mesmo em outra lngua basta criar as frases acima,
Guia de Referncia
155
respeitando-se sempre o nome do arquivo.
9.2
9.2.1
Eventos
OnAfterDial
Ocorre ao trmino de uma discagem feita por um nico comando Dial. Declaraes: Delphi:
OnAfterDial(Sender: TObject, smallint Port);
Visual Basic:
OnAfterDial (Port As Integer)
Descrio: Para efetuar uma discagem, necessrio utilizar o mtodo Dial, que pode discar de um a 28 nmeros. Visando facilitar o controle de fluxo do programa, o evento AfterDial ocorrer to logo todos os dgitos passados como parmetro no mtodo Dial sejam discados pela placa. Se for utilizado o parmetro PauseAfterDial do mtodo Dial, o evento OnAfterDial s ser gerado aps a discagem mais a pausa.
9.2.2
OnAfterFlash
Ocorre ao trmino de um comando Flash Declaraes:

156
Delphi:
OnAfterFlash(Sender: TObject, smallint Port);
Visual Basic:
OnAfterFlash (Port As Integer)
Descrio: De maneira semelhante ao evento OnAfterDial, o evento OnAfterFlash ocorrer ao trmino do comando executado pelo mtodo Flash.
9.2.3
OnAfterMakeCall
Ocorre ao trmino da funo de discagem MakeCall. Declaraes: Delphi:

OnAfterMakeCall(Sender: TObject, smallint); Port, Status:
Visual Basic:
OnAfterMakeCall (Port As Integer, Status as Integer)
Descrio: Ocorre ao trmino da discagem com superviso. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Status Pode assumir: mNoDialTone Sem tom de discagem mkDelivered Ligao entregue sem superviso mkNoAnswer Ligao no foi atendida
Guia de Referncia
157
mkBusy Ligao ocupada mkAnswered - Ligao atendida mkAborted ligao cancelada pelo AbortCall mkDialToneAfterDial - Indica recebimento de tom de linha depois da discagem. mkFaxDetected - Indica deteco de fax.
9.2.4
OnAfterPickUp
Ocorre ao trmino de um comando PickUp Declaraes: Delphi:

OnAfterPickup(Sender: TObject, smallint Port);
Visual Basic:
OnAfterPickup (Port As Integer)
Descrio: De maneira semelhante ao evento OnAfterDial, o evento OnAfterPickup ocorrer aps a pausa determinada na chamada do mtodo PickUp.
9.2.5
OnAnswerDetected
Ocorre quando a placa detecta atendimento da ligao originada. Declaraes: Delphi:

OnAnswerDetected(Sender: TObject, Copyright 2005 Digivoice Eletrnica smallint Port);
158
Visual Basic:
OnAnswerDetected(Port As Integer)
Descrio: A placa possui recursos de monitorao do status da linha ela conectada, e de repass-los para a aplicao. Para tanto, ela deve ser habilitada a utilizar estes recursos. O programador tem a flexibilidade de a qualquer ponto da aplicao habilitar e desabilitar tais recursos, fazendo uso dos mtodos EnableAnswerDetection() para habilitar e DisableAnswerDetection() para desabilitar. Quando uma ligao originada pela placa, e os recursos citados estiverem habilitados, o evento OnAnswerDetected ocorrer no momento em que essa ligao for atendida. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Veja Tambm: EnableAnswerDetection, DisableAnswerDetection
9.2.6
OnBusyDetected
Ocorre quando a placa detecta tom de ocupado na linha. Declaraes: Delphi:

OnBusyDetected(Sender: TObject, smallint Port);
Visual Basic:
OnBusyDetected(Port As Integer)
Descrio:
Guia de Referncia
159
A placa possui recursos de monitorao do status da linha ela conectada (Call Progress), e de repassa-los para a aplicao, para tanto, ela deve ser habilitada a utilizar estes recursos. O programador tem a flexibilidade de a qualquer ponto da aplicao habilitar e desabilitar tais recursos, fazendo uso dos mtodos EnableBusyDetection() para habilitar e DisableBusyDetection() para desabilitar. Sempre quando a placa tomar a linha conectada ela, para originar uma ligao, e receber tom de ocupado, o evento OnBusyDetected ocorrer, desde que os recursos de monitorao estejam habilitados. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Para VoicerPhone, o valor fixo em 1.
Veja Tambm: EnableCallProgress, DisableCallProgress
9.2.7
OnCallerID
Ocorre quando a placa detecta o identificador de A. Declaraes: Delphi:

OnCallerID(Sender: TObject, string); Port: smallint, Number:
Visual Basic:
OnCallerID(Port As Integer, Number as string)
Descrio:
160
Este evento gerado quando o identificador de A recebido pelo tronco. Isto ocorre somente se o mtodo IdleSettings for configurado para tal. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Para VoicerPhone, o valor fixo em 1. Numero Nmero identificado exatamente como enviado pela companhia telefnica.
9.2.8
OnCalling
Ocorre quando a placa detecta tom chamada na linha. Declaraes: Delphi:

OnCalling(Sender: TObject, smallint Port);
Visual Basic:
OnCalling(Port As Integer)
Descrio: A placa possui recursos de monitorao do status da linha ela conectada (Call Progress), e de repassa-los para a aplicao, para tanto, ela deve ser habilitada a utilizar estes recursos. O programador tem a flexibilidade de a qualquer ponto da aplicao habilitar e desabilitar tais recursos, fazendo uso dos mtodos EnableCallProgress() para habilitar e DisableCallProgress() para desabilitar. Sempre quando a placa tomar a linha conectada ela, originar uma ligao e receber tom de chamada, o evento OnCalling
Guia de Referncia
161
ocorrer, desde que os recursos de monitorao estejam habilitados. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Veja Tambm: EnableCallProgress, DisableCallProgress, Dial, PickUp, HangUp
9.2.9
OnCallStateChange
Ocorre em vrias situaes durante o MakeCall. Declaraes: Delphi:

OnCallStateChange(Sender: TObject, Status: smallint); Port: smallint;
Visual Basic:
OnCalling(Port As Integer, Status as Integer)
Descrio: O mtodo MakeCall inicia uma discagem completa, com superviso, frase inicial, discagem, etc... O evento OnCallStateChange indica, por canal, em qual etapa o MakeCall est no momento. Este evento deve ser utilizado para fins de monitoramento e depurao de programas. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Status - Indica o estado atual do MakeCall, podendo
162
assumir os seguintes valores: csPlayingStartPhrase - Falando frase inicial csPickingUp - Iniciando discagem sem transf csInitialFlash - Dando flash inicial csDialingPrefix - Prefixo apos o flash csStartAnalysis - Iniciando supervisao csNoAnswerReturn - Retomada em caso de no atendimento csPlayingBusyPhrase - Falando frase de ret. caso ocupado csPlayingNoAnswerPhrase - Falando frase de ret. caso ocupado csWaitingDialTone - Esperando tom de discagem csDialing - Discando csCalling - Chamando Veja Tambm: MakeCall, AbortCall
9.2.10 OnDialToneDetected
Ocorre quando a placa detecta tom de discagem na linha. Declaraes: Delphi:
OnDialToneDetected(Sender: TObject, smallint Port);
Visual Basic:
OnDialToneDetected (Port As Integer)
Descrio: A placa possui recursos de monitorao do status da linha ela conectada (Call Progress), e de repassa-los para a aplicao, para tanto, ela deve ser habilitada a utilizar estes recursos.
Guia de Referncia
163
O programador tem a flexibilidade de a qualquer ponto da aplicao habilitar e desabilitar tais recursos, fazendo uso dos mtodos EnableCallProgress() para habilitar e DisableCallProgress() para desabilitar. Sempre quando a placa tomar a linha conectada ela, para originar uma ligao, e receber um tom de discagem, o evento OnDialToneDetected ocorrer, desde que os recursos de monitorao estejam habilitados. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Para VoicerPhone, o valor fixo em 1. Veja Tambm: EnableCallProgress, DisableCallProgress, Dial, PickUp, HangUp
9.2.11 OnDigitDetected
Ocorre sempre que a placa detecta um dgito. Declaraes: Delphi:
OnDigitDetected(Sender: TObject, smallint Port, smallint Digit);
Visual Basic:
OnDigitDetected(Port As Integer, Digit as Integer)
Descrio: Toda vez que a placa detectar um dgito (DTMF), o evento OnDigitDetected ocorrer, e o cdigo ASCII dgito ser passado atravs do parmetro Digit. Um dgito DTMF um par de freqncias pr-definidas e na
164
faixa da voz. O programador deve estar ciente que a placa sempre est habilitada a detectar os digitos, logo, durante uma conversao comum a placa detectar alguns dgitos indevidamente, pois ela analisa todo o contedo de freqncia da voz dos locutores e toda vez em que ela encontrar na voz um par de freqncias que coincidam com um dgito DTMF, o evento OnDigitDetected ocorrer. Quando o programador quiser validar os dgitos apenas em certos momentos, deve-se fazer uso do mtodo GetDigits e do evento OnDigitReceived ao invs de tratar dgito a dgito. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Digit Cdigo ASCII do digito recebido Veja Tambm: GetDigits, OnDigitsReceived, PlayFile, RecordFile
9.2.12 OnDigitsReceived
Ocorre sempre depois que o mtodo GetDigits( ) chamado. Declaraes: Delphi:
OnDigitsReceived(Sender: TObject, smallint Port; var Status: TOleEnum);
Visual Basic:
OnDigitsReceived(Port As Integer, Status As VoicerLib.TxWaitDigit)
Descrio: Este evento ocorre em resposta ao mtodo GetDigits. Basicamente este mtodo espera um determinado nmero de dgitos e/ou finalizador por um intervalo de tempo. Os digitos
Guia de Referncia
165
detectados devem ser recuperados atravs da propriedade Digits. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Status Indica qual das situaes gerou o evento OnDigitsReceived, a saber: EdMaxDigits(2) Recebeu o nmero mximo de digitos estipulado. EdTermDigit(5) Recebeu o digito finalizador EdDigitTimeout(3) Estourou o tempo total para entrada de todos os digitos. EdInterDigitTimeOut(4) Estourou o tempo inter-dgito. EdDigitOverMessage Detectou dgito durante a reproduo.
Veja Tambm: GetDigits, PlayFile, RecordFile
9.2.13 OnErrorDetected
Ocorre quando a placa pra de responder Declaraes: Delphi:
OnErrorDetected(ASender: TObject; Port,ErrorType: Smallint);
Visual Basic:
OnErrorDetected (Port As Integer,ErrorType As Integer)
Descrio:
166
A placa deve permanecer com a interrupo ativa durante toda a operao. Caso haja algum problema e a placa pare de responder aos comandos da VoicerLib, o evento OnErrorDetected gerado, permitindo avisar ao operador do problema e indicando o procedimento a tomar. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Para VoicerPhone, o valor fixo em 1. No utilizado neste evento. ErrorType: Veja Tambm: DriverEnabled
9.2.14 OnFaxDetected
Ocorre quando um sinal de fax detectado pela placa. Declaraes: Delphi:
OnFaxDetected(Sender: TObject, smallint Port);
Visual Basic:
OnFaxDetected (Port As Integer)
Descrio: A placa possui recursos de monitorao do status da linha ela conectada (Call Progress), e de repassa-los para a aplicao, para tanto, ela deve ser habilitada a utilizar estes recursos. O programador tem a flexibilidade de a qualquer ponto da aplicao habilitar e desabilitar tais recursos, fazendo uso dos
Guia de Referncia
167
mtodos EnableCallProgress() para habilitar e DisableCallProgress() para desabilitar. Sempre quando for detectado um sinal de fax na linha, o evento OnFaxDetected ser chamado, permitindo tratamentos especiais, como por exemplo, desviar para o ramal do aparelho de fax. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Para VoicerPhone, o valor fixo em 1. Veja Tambm: EnableCallProgress, DisableCallProgress, Dial, PickUp, HangUp, Flash
9.2.15 OnLineOff
Ocorre quando o usurio desliga o aparelho telefnico conectado placa. Declaraes: Delphi:
OnLineOff(Sender: TObject, smallint Port);
Visual Basic:
OnLineOff(Port As Integer)
Descrio: O Evento OnLineOff ocorre sempre que o aparelho telefnico for desligado. importante ressaltar que isso s ocorrer se antes, o aparelho for retirado do "gancho" com a placa desligada. Tanto este evento como o OnLineReady so para tratamento exclusivo do aparelho telefnico conectado placa.
168
9.2.16 OnLineReady
Ocorre quando um aparelho telefnico conectado placa toma a linha para originar uma ligao. Declaraes: Delphi:
OnLineReady(Sender: TObject, smallint Port);
Visual Basic:
OnLineReady(Port As Integer)
Descrio: Existem na placa 3 conectores: "Linha", onde conectado um linha ou ramal; "Aparelho", onde pode ser conectado um aparelho telefnico e "HeadSet", onde pode ser conectado um HeadSet. Se a placa tomar a linha ou para originar uma ligao ou para atender uma ligao, o aparelho telefnico automaticamente fica mudo, e a conversao ser feita atravs do HeadSet. Caso a linha esteja livre e o aparelho conectado, este poder atender e efetuar ligaes, bastando para isso, tirar o monofone do gancho. Sempre que isso ocorrer, o evento OnLineReady tambm ocorrer. Neste caso, o udio tambm estar disponvel no HeadSet, e a placa poder monitorar toda conversao. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento
Veja Tambm: Dial
Guia de Referncia
169
9.2.17 OnMenu
Ocorre ao trmino de uma funo de menu iniciada pelo MenuStart Declaraes: Delphi:
OnMenu(ASender: TObject; Port: Smallint;const OptionSelected: WideString; Status: Smallint);
Visual Basic:
OnMenu(Port As Integer, OptionSelected as string, Status as Integer)
Descrio: O evento OnMenu gerado aps o trmino da funo especial de menu Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento OptionSelected Opo digitada pelo usurio Status Indica o que aconteceu: msAborted Cancelado pelo mtodo MenuAbort msTimeOut Usurio no digitou nada msRetriesExceeded Nmero de tentativas excedido msValidOptionDetected Foi digitada uma opo vlida
170
9.2.18 OnPlayStart
Ocorre sempre quando for iniciado o playback de qualquer mensagem. Declaraes: Delphi:
OnPlayStart(Sender: TObject, smallint Port);
C++ Builder:
OnPlayStart(TObject *Sender, short &Port);
Visual Basic:
OnPlayStart(Port As Integer)
Visual C++:
OnPlayStartVoicerlibx1(short FAR* Port);
Descrio: Sempre quando se desejar que a placa fale uma mensagem, deve-se fazer uso do mtodo PlayFile, e toda vez que este mtodo chamado, o evento OnPlayStart ocorrer. Este evento indicado para atualizaes na interface, como por exemplo, desabilitar botes, mostrar mensagens, etc... Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Veja Tambm: PlayFile, StopPlayFile, OnPlayStop
9.2.19 OnPlayStop
Ocorre sempre quando for finalizado o playback de qualquer
Guia de Referncia
171
mensagem. Declaraes: Delphi:

OnPlayStop(ASender: TObject; Port,StopStatus: Smallint);
Visual Basic:
OnPlayStop(Port As Integer, StopStatus As Integer)
Descrio: O evento OnPlayStop ocorrer quando o playback for interrompido. Este evento retorna na varivel StopStatus o motivo da interrupo. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento StopStatus Indica o motivo da interrupo. Os cdigos so: ssNormal Significa a mensagem foi falada por completo (terminou normalmente); ssDigitReceived Significa que a mensagem foi interrompida pelo recebimento de um dos dgitos passados como parmetro para interrupo da mensagem. O digito deve ser recuperado na propriedade Digits. ssStopped Significa que a mensagem foi interrompida pela chamada do mtodo StopPlayFile( ). ssAbnormal Significa que a mensagem foi interrompida por causa de algum erro indeterminado. Veja Tambm: PlayFile, StopPlayFile
172
9.2.20 OnPrompt
Ocorre quando a funo de prompt chega ao fim. Declaraes: Delphi:
OnPrompt(Sender: TObject, smallint Port, Value: string, Status: smallint);
Visual Basic:
OnPrompt(Port As Integer, Value as string, Status as integer)
Descrio: O Evento ocorre ao final do prompt, que foi iniciado pelo mtodo PromptStart. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Value Valor digitado pelo usurio Status Pode assumir os valores: mpAborted Cancelado pelo mtodo PromptAbort mpRetriesExceeded Nmero de tentativa excedido mpOk Usurio confirmou entrada de dados mpCanceled Usurio cancelou
9.2.21 OnRecording
Ocorre durante a gravao de uma mensagem. Declaraes: Delphi:
OnRecordgin(Sender: TObject, smallint Port, var
Guia de Referncia
173
Duration: Integer);
Visual Basic:
OnResetDetected (Port As Integer, Duration as Long)
Descrio: O evento OnRecording ideal para monitorar o andamento de uma gravao. A varivel Duration contm a durao em segundos da gravao at aquele momento. Atravs deste evento possvel limitar o tamanho das mensagens ou mesmo exibir informaes sobre o andamento da gravao. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Para VoicerPhone, o valor fixo em 1. Duration Indica a durao da gravao em segundos naquele instante.
9.2.22 OnRecordStart
Ocorre sempre quando for iniciado a gravao de qualquer mensagem. Declaraes: Delphi:
OnRecordStart(Sender: TObject, smallint Port);
Visual Basic:
OnRecordStart(Port As Integer)
Descrio: Sempre quando se desejar gravar uma conversa, deve-se fazer uso do mtodo RecordFile, e toda vez que este mtodo
174
chamado, o evento OnRecordStart ocorrer. Este evento indicado para atualizaes na interface, como por exemplo, desabilitar botes, mostrar mensagens, etc... Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Para VoicerPhone, o valor fixo em 1. Veja Tambm: RecordFile, StopRecordFile, OnRecordStop
9.2.23 OnRecordStop
Ocorre sempre quando for finalizado a gravao de qualquer mensagem. Declaraes: Delphi:
OnRecordStop(ASender: TObject; Port,StopStatus: Smallint);
Visual Basic:
OnRecordStop(Port As Integer, StopStatus As Integer)
Descrio: O evento OnRecordStop ocorrer quando a gravao for interrompida. Este evento retorna na varivel Status o motivo da interrupo. Parmetros Recebidos: Port Indica o canal da Placa que gerou o evento Para VoicerPhone, o valor fixo em 1.
Guia de Referncia
175
StopStatus Indica o motivo da interrupo. Os cdigos so: ssDigitReceived Significa que a mensagem foi interrompida pelo recebimento de um dos dgitos passados como parmetro para interrupo da mensagem. O digito deve ser recuperado na propriedade Digits. ssStopped Significa que a mensagem foi interrompida pela chamada do mtodo StopPlayFile( ). ssAbnormal Significa que a mensagem foi interrompida por causa de algum erro indeterminado. Veja Tambm: RecordFile, StopRecordFile
9.2.24 OnRingDetected
Ocorre sempre quando for detectado o sinal de Ring na linha. Declaraes: Delphi:
OnRingDetected(Sender: TObject, smallint Port);
Visual Basic:
OnRingDetected (Port As Integer)
Descrio: O evento Ring ocorre sempre quando o sinal de ring for detectado pela placa, portanto, se o usurio demorar 3 toques para atender o telefone, o evento OnRingDetected ocorrer 3 vezes. Parmetros Recebidos:
176
Port Indica o canal da Placa que gerou o evento Para VoicerPhone, o valor fixo em 1. Veja Tambm: PickUp
9.2.25 OnSampleReceived
Ocorre em intervalos regulares de tempo permitindo a leitura de amostras GSM. Declaraes: Delphi:
OnSampleReceived(Sender: TObject, smallint Port);
Visual Basic:
OnSampleReceived (Port As Integer)
Descrio: Este evento ocorre em intervalos de tempo suficiente para ler amostras vindas da placa atravs do mtodo GetSamples.
9.3
9.3.1
Mtodos
AbortCall
Cancela a discagem automtica feita pelo mtodo MakeCall. Declaraes:
Guia de Referncia
177
Delphi:
function AbortCall(Port: Smallint): Smallint;
Visual Basic:
Function AbortCall (Port As Integer) As Integer
Descrio: Durante o processo de discagem automtica possvel cancelar atravs da chamada deste mtodo Parmetros: Port Indica o canal da Placa que gerou o evento Valor de Retorno: Retorna zero se foi executado com sucesso.
9.3.2
ClearDigits
Apaga o contedo do buffer de dgitos de cada canal. Declaraes: Delphi:

function ClearDigits(Port: Smallint): Smallint;
Visual Basic:
Function ClearDigits(Port As Integer) As Integer
Descrio: utilizada para apagar o buffer interno de dgitos detectados, principalmente quando a propriedade AutoClearDigits est com valor false.
178
Parmetros: Port Indica o canal da Placa que gerou o evento Valor de Retorno: Retorna zero se foi executado com sucesso. Veja Tambm: ReadDigits, AutoClearDigits
9.3.3
ConferenceAddPort
Adiciona canal a determinada conferencia. Declaraes: Delphi:

function ConferenceAddPort(Handle: Smallint; Port: Smallint): Smallint;
Visual Basic:
Function ConferenceAddPort(Handle As Integer, Port As Integer) As Integer
Descrio: Aps criada a conferencia necessrio adicionar os canais desejados a ela, para adicionar os canais chama-se essa funo passando o canal e a conferencia em que ele ser adicionado. Parmetros: Handle - Obtido como retorno da funo CreateConferenceResource Port - Canal fisico da placa.
Guia de Referncia
179
Valor de Retorno: -1 - Driver no habilitado -2 - Numero maximo de canais por recurso alcanado (sala cheia) -3 - Porta j est alocada em outro recurso 0 - Porta Inserida com sucesso
Veja Tambm: ConferenceRemovePort
9.3.4
ConferenceDisablePort
Desabilita porta alocada em um recurso de conferencia a converar com as outras Declaraes: Delphi:
function ConferenceDisablePort(Port: Smallint): Smallint;
Visual Basic:
Function ConferenceDisablePort(Port As Integer) As Integer
Descrio: Este mtodo importante pois, caso um dos canais queira ouvir um menu, os outros canais no iro ouvir tambm, basta desabilitar o canal atravs do mtodo deste mtodo, reproduzir o menu que somente ele ouvir, e aps isso habilit-lo novamente atravs do mtodo ConferenceEnablePort. Isso sem precisar remover o canal da conferencia.
180
Parmetros: Port - Canal fisico da placa. Valor de Retorno: 0 - Retorno Padro Veja Tambm: ConferenceEnablePort
9.3.5
ConferenceEnablePort
Habilita porta alocada em um recurso de conferencia a converar com as outras. Declaraes: Delphi:
function ConferenceEnablePort(Port: Smallint): Smallint;
Visual Basic:
Function ConferenceEnablePort(Port As Integer) As Integer
Descrio: Mesmo que o canal esteja alocado em uma determinada conferencia necessrio que ele esteja habilitado para que possa se comunicar com os outros canais. Isso importante pois, caso um dos canais queira ouvir um menu, os outros canais no iro ouvir tambm, basta desabilitar o canal, atravs do mtodo ConferenceDisablePort, reproduzir o menu que somente ele ouvir, e aps isso habilit-lo novamente atravs
Guia de Referncia
181
deste mtodo. Isso sem precisar remover o canal da conferencia. Parmetros: Port - Canal fisico da placa. Valor de Retorno: -1 - Driver no habilitado ou canal no alocado em nenhum recurso 0 - Canal habilitado com sucesso Veja Tambm: ConferenceDisablePort
9.3.6
ConferenceGetHandle
Pega o Handle de determinada porta. Declaraes: Delphi:

function ConferenceGetHandle(Port: Smallint): Smallint;
Visual Basic:
Function ConferenceGetHandle(Port As Integer) As Integer
Descrio: Esse mtodo deve ser utilizado para saber em que conferencia o canal est alocado. Parmetros:
182
Port - Canal fisico da placa. Valor de Retorno: >= 0 - O handle a que a porta pertence -1 - Canal no alocado Veja Tambm: CreateConferenceResource
9.3.7
ConferenceRemovePort
Remove canal de determinada conferencia. Declaraes: Delphi:

function ConferenceRemovePort(Handle: Smallint; Port: Smallint): Smallint;
Visual Basic:
Function ConferenceRemovePort(Handle As Integer, Port As Integer) As Integer
Descrio: Para remover os canais de determinada conferencia chama-se essa funo passando o canal e a conferencia de que ele ser removido. Parmetros: Handle - Obtido como retorno da funo CreateConferenceResource Port - Canal fisico da placa.
Guia de Referncia
183
Valor de Retorno: -1 - Driver no habilitado 0 - Porta Removda com sucesso Veja Tambm: ConferenceAddPort
9.3.8
CreateConferenceResource
Cria recurso para conferencia ("cria sala de bate papo"). Declaraes: Delphi:
function CreateConferenceResource(MaxPorts: Smallint): Smallint;
Visual Basic:
Function CreateConferenceResource(MaxPorts As Integer) As Integer
Descrio: A criao da conferencia permite que um numero determinado de canais conversem entre si. Ao criar esse recurso o valor de retorno utilizado como um cdigo para cada conferncia (cada sala). Parmetros: MaxPorts Maximo de canais permitido nesta conferencia ("sala").
184
Valor de Retorno: >= 0 o Handle vlido a ser usado nas outras funes -1 - Erro ao criar recurso Veja Tambm: DeleteConferenceResource
9.3.9
DeleteConferenceResource
Remove recurso para conferencia ("sala de bate papo"). Declaraes: Delphi:

function DeleteConferenceResource(Handle: Smallint): Smallint;
Visual Basic:
Function DeleteConferenceResource(Handle As Integer) As Integer
Descrio: Deve-se utilizar esse mtodo para excluir uma conferencia j existente, passando o Handle que cdigo utilizado para identificar cada conferencia. Parmetros: Handle - Obtido como retorno da funo CreateConferenceResource Valor de Retorno:
Guia de Referncia
185
-1 - Driver no foi iniciado -2 - Recurso no existia 0 - Remoo do recurso sem problemas
Veja Tambm: CreateConferenceResource
9.3.10 Dial
Disca uma seqencia de nmeros ou pausa. Declaraes: Delphi:
function Dial(Port: Smallint; const Number: WideString; PauseAfterDial: Integer, DialType: integer): Smallint;
Visual Basic:
Function Dial(Port As Integer, Number As String, PauseAfterDial as Integer, DialType as Integer) As Integer
Descrio: O mtodo Dial permite enviar a VoicePhone at 16 digitos ou pausas para que seja efetuada a discagem. Pode ser enviado os dgitos de "0" a "9", "#", "*" e os smbolos de pausa "vrgula" "ponto-e-vrgula" e "ponto". A pausa para cada smbolo deve ser atribuda atravs das propriedades DelayComma, DelaySemicolon e DelayDot (assumem o padro de 1 segundo). O tipo de discagem (pulso ou tom) determinado pelo 4o.
186
parmetro, o DialType. Parmetros: Port Indica o canal da Placa Number String contendo os dgitos ou pausas para discagem. PauseAfterDial - um tempo extra em milisegundos que dado aps a discagem. O evento OnAfterDial s ser gerado aps este tempo. DialType - Pode assumir o valor dtTone ou dtPulse, indicando se a discagem por pulso e tom. Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Exemplos: Delphi:
VoicerLibX1.Dial(1,'0,72952557...202',1000);
Visual Basic:
x = VoicerLibX1.Dial(1,"0,72952557...202" ,1000)
Veja Tambm: DelayComma, DelaySemicolon, DelayDot
9.3.11 DisableAnswerDetection
Desabilita a superviso de atendimento. Declaraes: Delphi:
function DisableAnswerDetection(Port: Smallint):
Guia de Referncia
187
Smallint;
Visual Basic:
Function DisableAnswerDetection (Port As Integer) As Integer
Descrio: O mtodo DisableAnswerDetection desabilita a superviso de atendimento. Esta superviso permite detectar ou no quando a ligao foi atendida. Deve ser usado somente em momentos onde o atendimento tem sentido, principalmente durante a chamada. Parmetros: Port Indica o canal da Placa que gerou o evento Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: EnableAnswerDetection, OnAnswerDetected, OnFaxDetected, OnCalling
9.3.12 DisableCallProgress
Desabilita a superviso de linha, fax e ocupado. Declaraes: Delphi:
function DisableCallProgress(Port: Smallint): Smallint;
188
Visual Basic:
Function DisableCallProgress(Port As Integer) As Integer
Descrio: O mtodo DisableCallProgress desabilita a superviso de linha. A superviso de linha permite monitorar o sinal de chamada, ocupado, fax e tom de discagem. Quando o sistema iniciado, a superviso est desabilitada como padro. Parmetros: Port Indica o canal da Placa Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: EnableCallProgress, OnAnswerDetected, OnFaxDetected, OnCalling
9.3.13 DisableEchoCancel
Desabilita cancelamento de eco em recursos de conferncia. Declaraes: Delphi:
function DisableEchoCancel: Smallint;
Visual Basic:
function DisableEchoCancel As Integer
Guia de Referncia
189
Descrio: O mtodo DisableEchoCancel desabilita o cancelamento de eco nos recursos de conferncia. Valor de Retorno: Retorna sempre zero.
9.3.14 DisablePulseDetection
Desabilita a deteo de pulso. Declaraes: Delphi:
function DisablePulseDetection(Port: Smallint): Smallint;
Visual Basic:
Function DisablePulseDetection (Port As Integer) As Integer
Descrio: O mtodo DisablePulseDetection desabilita a deteo de pulso. Parmetros: Port Indica o canal da Placa que gerou o evento Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de
190
erro.
9.3.15 DisableSampleToApp
Desabilita o envio de amostras GSM da placa para a aplicao.
Declaraes:
Delphi:
procedure DisableSampleToApp(Port: Smallint)
Visual Basic:
Sub DisableSampleToApp (Port As Integer)
Descrio:
Este mtodo desliga os procedimentos iniciados pelo EnableSampleToCard
Parmetros: Port Indica o canal da Placa. Valor de Retorno:

0 - OK
9.3.16 DisableSampleToCard
Desabilita o envio de amostras GSM da aplicao para a placa.
Guia de Referncia
191
Declaraes:
Delphi:
procedure DisableSampleToCard(Port: Smallint)
Visual Basic:
Sub DisableSampleToCard (Port As Integer)
Descrio:
Este mtodo desliga os procedimentos iniciados pelo EnableSampleToCard

0 - OK
9.3.17 EnableAnswerDetection
Habilita a superviso de atendimento. Declaraes: Delphi:
function EnableAnswerDetection(Port: Smallint): Smallint;
Visual Basic:
Function EnableAnswerDetection(Port As Integer) As Integer
Descrio:
192
O mtodo EnableAnswerDetection habilita a superviso de atendimento. A superviso de linha permite monitorar quando uma ligao for atendida. Parmetros: Port Indica o canal da Placa Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: DisableAnswerDetection, OnAnswerDetected, OnBusyDetected, OnFaxDetected, OnCalling
9.3.18 EnableCallProgress
Habilita a superviso de linha. Declaraes: Delphi:
function EnableCallProgress(Port: Smallint): Smallint;
Visual Basic:
Function EnableCallProgress(Port As Integer) As Integer
Descrio: O mtodo EnableCallProgress habilita a superviso de linha. A superviso de linha permite monitorar o tom de discagem, ocupado, chamada e fax. Quando o sistema iniciado, a superviso est desabilitada como padro, portanto necessrio chamar este mtodo
Guia de Referncia
193
quando se quiser monitorar a linha. Parmetros: Port Indica o canal da Placa. Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: DisableCallProgress, OnAnswerDetected, OnFaxDetected, OnCalling
9.3.19 EnableEchoCancel
Habilita cancelamento de eco em recursos de conferncia. Declaraes: Delphi:
function EnableEchoCancel: Smallint;
Visual Basic:
function EnableEchoCancel As Integer
Descrio: O mtodo EnableEchoCancel habilita o cancelamento de eco nos recursos de conferncia, evitando a degradao do sinal causada pelo efeito de eco no udio. Valor de Retorno: Retorna sempre zero.
194
9.3.20 EnablePulseDetection
Habilita a deteo de pulso. Declaraes: Delphi:
function EnablePulseDetection(Port: Smallint): Smallint;
Visual Basic:
Function EnablePulseDetection (Port As Integer) As Integer
Descrio: O mtodo EnablePulseDetection habilita a deteo de pulso. S possvel detectar pulso com razovel preciso durante o silncio. Parmetros: Port Indica o canal da Placa Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro.
9.3.21 EnableSampleToApp Habilita o envio de amostras GSM da placa para a aplicao.
Guia de Referncia
195
Declaraes:
Delphi:
procedure EnableSampleToApp(Port: Smallint)
Visual Basic:
Sub EnableSampleToApp (Port As Integer)
Descrio:
Este mtodo faz com que todas as amostras de udio (GSM) vindas da placa sejam disponibilizadas para a aplicao atravs do mtodo OnSampleReceived.

0 - OK 1 - Amostras j habilitadas 3 - Driver Desabilitado
9.3.22 EnableSampleToCard
Habilita o envio de amostras GSM da aplicao para a placa.
Declaraes:
Delphi:
196
procedure EnableSampleToCard(Port: Smallint)
Visual Basic:
Sub EnableSampleToCard (Port As Integer)
Descrio:
Este mtodo faz com que amostras de udio (GSM) possam ser enviadas para a placa atravs do mtodo PutSamples, fazendo com que sejam reproduzidas pela placa atravs da porta especificada, com funcionamento similar a um PlayFile.

0 - OK 1 - Amostras j habilitadas 3 - Driver Desabilitado
9.3.23 Flash
Executa um comando de flash para a central PABX. Declaraes: Delphi:
function Flash(Port: Smallint; Milliseconds: Integer; PauseAfterFlash: integer): Smallint;
Visual Basic:
Guia de Referncia
197
Function Flash(Port As Integer, Milliseconds As Long, PauseAfterFlash as Integer) As Integer
Descrio: As centrais PABX sempre necessitam do flash (desligar e ligar) para poder efetuar uma transferncia ou outra funo qualquer. O mtodo Flash permite que seja encaminhado para a placa um comando flash com o tempo em milissegundos especificado e tambm um tempo de pausa aps o flash. Esta pausa til em algumas centrais que demoram para comutar os ramais. Parmetros: Port Indica o canal da Placa Milisseconds Indica o tempo em milissegundos para o Flash (consulte a documentao do PABX para maiores detalhes) PauseAfterFlash - Indica a pausa aps flash em milissegundos. Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro.
9.3.24 GetDigits
Inicia a espera de uma seqncia de dgitos. Declaraes: Delphi:
function GetDigits(Port, MaxDigits: Smallint; const TermDigits: WideString; DigitsTimeOut, InterDigitsTimeOut: Integer): Smallint;
198
Visual Basic:
Function GetDigits(Port As Integer, MaxDigits As Integer, TermDigits As String, DigitsTimeOut As Long, InterDigitsTimeOut As Long) As Integer
Descrio: O mtodo GetDigits permite iniciar a espera de um conjunto de digitos, por um determinado tempo ou at receber um digito finalizador. Como a VoicerLib tem um processamento assncrono, aps a execuo de GetDigits, necessrio tratar o resultado no evento OnDigitsReceived, o que pode acontecer segundos mais tarde. Para recuperar os dgitos detectados deve-se utilizar o mtodo ReadDigits. Ao executar o GetDigits, o programa segue seu fluxo normal, isto , no fica esperando a execuo do GetDigits at o fim. Parmetros: Port Indica o canal da Placa MaxDigits Nmero mximo de dgitos permitido. Utilize esta propriedade para limitar o nmero de digitos que o usurio poder teclar. TermDigits uma string contendo um ou mais dgitos, que ao serem detectados finaliza a execuo do GetDigits e gera o evento OnDigitsReceived. Se qualquer dgito puder interromper utilize o smbolo "@" ao invs de colocar "0123456789#*", apesar de a segunda forma tambm estar correta. Se no houver dgito finalizador, passar "" (vazio). DigitsTimeOut Refere-se ao tempo mximo de espera pelo primeiro dgito programado no GetDigits. Caso seja detectado o primeiro dgito, este timeout no ocorrer mais. InterDigitsTimeOut - o tempo mximo que o GetDigits
Guia de Referncia
199
esperar de intervalo entre cada dgito. Aps este tempo, ser gerado o evento OnDigitsReceived como cdigo correspondete ao time-out interdgito. Em milissegundos. Valor de Retorno: Retorna zero se foi iniciado com sucesso ou 1 no caso de erro. Veja Tambm: OnDigitsReceived, ReadDigits
9.3.25 GetPortStatus
Recupera o status do canal especificado Declaraes: Delphi:
function GetPortStatus(Port: Smallint): Smallint;
Visual Basic:
Function GetPortStatus(Port As Integer) As Integer
Descrio: Este mtodo permite ao desenvolvedor saber o que o canal especificado est executando em um determinado momento. Parmetros: Port Indica o canal da Placa Valores de Retorno: spFlashing -Executando um Flash spDialing -Discando spNone -Ocioso
200
spWaitingDigits -Esperando Dgitos
9.3.26 GetSamples
L amostras da placa. Declaraes: Delphi:
function GetSamples(Port: Smallint): Variant;
Visual Basic:
Sub GetSamples(Port as Integer) as Variant
Descrio: Este mtodo l um grupo de 33 (1 frame GSM) amostras vindas da placa e devolve em um array do tipo Variant (tipo de dado varivel). Normalmente esta funo deve ser chamada de dentro do evento OnSampleReceived. Parmetros: Port Indica o canal da Placa. Valor de Retorno: Vetor de amostras lidas
9.3.27 GsmToWave
Converte do formato GSM para o formato Wave. Declaraes: Delphi:
Guia de Referncia
201
function GsmToWave(const Source: WideString, Destination: WideString): Sma lli nt;
Visual Basic:
Function GsmToWave(Source As String, Destination As String) As Int ege r
Parmetros: Source String contendo o nome e caminho completo do arquivo GSM que ser convertido. Destination String contendo o nome e caminho completo do arquivo Wave que ser gravado. Valores de Retorno: 0 - Executado com sucesso 1 - No foi encontrado o arquivo de origem (Source) 2 - No foi possvel criar o arquivo de destino (Destination) 3 - Arquivo GSM corrompido. 4 - Erro durante a gravao do arquivo de destino. 5 - Erro durante a leitura do arquivo de origem. Veja Tambm: WaveToGsm.
202
9.3.28 HangUp
Libera a linha conectada a placa (desliga). Declaraes: Delphi:
function HangUp(Port: Smallint): Smallint;
Visual Basic:
Function HangUp(Port As Integer) As Integer
Descrio: Ao chamar este mtodo, a linha desconectada e a porta liberada. Equivale ao desligar do telefone. Parmetros: Port Indica o canal da Placa que gerou o evento Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: PickUp
9.3.29 IdleAbort
Interrompe a execuo de uma funo de Idle. Declaraes: Delphi:
Guia de Referncia
203
function IdleAbort(Port: Smallint): Smallint;
Visual Basic:
Function IdleAbort (Port As Integer) As Integer
Descrio: Ao chamar este mtodo a funo iniciada pelo IdleStart ser interrompida para o canal especfico. Parmetros: Port Indica o canal da Placa que gerou o evento Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro.
9.3.30 IdleSettings
Configura a monitorao do estado de espera. Declaraes: Delphi:
function IdleStart(Port: Smallint; AutoPickUp: boolean; RingCount, PauseAfterPickUp: smallint; WatchTrunkBefore, WatchTrunkAfter: boolean; Format, TimeOut, Max: smallint; TermDigits: string): Smallint;
Visual Basic:
Function IdleStart (Port As Integer AutoPickUp as boolean, RingCount, PauseAfterPickUp as integer, WatchTrunkBefore,
204
WatchTrunkAfter as boolean, Format, TimeOut, Max as integer, TermDigits as string) as integer
Descrio: Esta funo configura as opes a serem monitoradas durante o estado de espera. Permite configurar deteo automtica de bina (OnCallerID), atendimento automtico e integrao com o PABX Parmetros: Port Indica o canal da Placa que gerou o evento. AutoPickUp Indica se atende automtico ou no. RingCount Nmero de rings para o atendimento automtico PauseAfterPickUp Pausa aps o pickup WatchTrunkBefore Monitora a linha antes do atendimento. Deve ser utilizado para sinalizaes antes do Ring (BINA) WatchTrunkAfter - Monitora a linha depois do atendimento. Format - wtDTMF, wtMFP, wtCustom Ver detalhes no captulo Funes Especiais. Timeout Timeout interdigito Max Nmero mximo de dgitos da sinalizao TermDigits Indica um ou mais dgitos como finalizadores. Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: IdleAbort, IdleStart
Guia de Referncia
205
9.3.31 IdleStart
Inicia a execuo de uma funo de Idle. Declaraes: Delphi:
function IdleStart(Port: Smallint): Smallint;
Visual Basic:
Function IdleStart (Port As Integer) As Integer
Descrio: Ao chamar este mtodo a funo de monitorao de estado de espera iniciada. Parmetros: Port Indica o canal da Placa que gerou o evento Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: IdleAbort, IdleSettings
9.3.32 IsCallInProgress
Indica se existe uma discagem em curso. Declaraes: Delphi:
206
function IsCallInProgress (Port: Smallint): Boolean;
Visual Basic:
Function IsCallInProgress (Port As Integer) As Boolean
Descrio: Esta funo permite saber se existe uma discagem em curso. Parmetros: Port Indica o canal da Placa que gerou o evento Valor de Retorno: True ou False
9.3.33 IsPlaying
Indica se a placa est reproduzindo alguma mensagem Declaraes: Delphi:
function IsPlaying(Port: Smallint): boolean;
Visual Basic:
Function IsPlaying(Port As Integer) As Boolean
Descrio: Este mtodo permite ao desenvolvedor saber se o canal especificado est reproduzindo uma mensagem Parmetros:
Guia de Referncia
207
Port Indica o canal da Placa Valores de Retorno: True ou False
9.3.34 IsRecording
Indica se a placa est gravando alguma mensagem Declaraes: Delphi:
function IsRecording(Port: Smallint): boolean;
Visual Basic:
Function IsRecording (Port As Integer) As Boolean
Descrio: Este mtodo permite ao desenvolvedor saber se o canal especificado est gravando uma mensagem Parmetros: Port Indica o canal da Placa Valores de Retorno: True ou False
9.3.35 MakeCall
Inicia a discagem com superviso.
208
Declaraes: Delphi:
procedure MakeCall(Port: Smallint; CallType: Smallint; Number: string; InitialPhrase: String; WithAnalysis: boolean; DialType:smallint): smallint;
Visual Basic:
Function MakeCall(Port As Integer, CallType as integert; Number as string; InitialPhrase as String; WithAnalysis as boolean;DialType as Smallint) as integer;
Descrio: Este mtodo inicia a discagem com superviso conforme configurado pelos mtodos SetCallxxxxx. O trmino ser tratado no evento OnAfterMakeCall. Parmetros: Port Indica o canal da Placa. CallType ctExternal ou ctWithFlash Number Nmero que ser discado InitialPhrase Frase a ser reproduzida no incio do processo WithAnalysis True/False que indicar se a discagem ser com superviso (monitorar ocupado, etc...) ou sem (ligao entregue aps a discagem). DialType Define o tipo de discagem :pulso/tom. Retorno: Retorna Zero se executado com sucesso.
9.3.36 MenuAbort
Interrompe a execuo de uma funo de Menu.
Guia de Referncia
209
Declaraes: Delphi:
function MenuAbort(Port: Smallint): Smallint;
Visual Basic:
Function MenuAbort(Port As Integer) As Integer
Descrio: Ao chamar este mtodo a funo iniciado pelo MenuStart ser interrompida para o canal especfico. Parmetros: Port Indica o canal da Placa que gerou o evento Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: MenuStart
9.3.37 MenuErrorSettings
Configura as opes de menu Declaraes: Delphi:
function MenuErrorSettings(Port: Smallint; InvalidDigitPhrase:string; InvalidDigitRetries: smallint;TimeOutPhrase: String;): smallint;
Visual Basic:
210
Function MenuErrorSettings(Port As Integer, InvalidDigitPhrase as string, InvalidDigitRetries as integer, TimeOutPhrase as string) as integer
Descrio: Tem a finalidade de configurar as frases e situaes de erro de entrada de dados das funes especiais de menu Parmetros: Port Indica o canal da Placa. InvalidDigitPhrase Frase utilizada em caso de opo invlida InvalidDigitRetries Nmero de tentativas TimeOutPhrase Frase a ser reproduzida caso o usurio no digite nada no tempo especificado no MenuStart. Retorno: Retorna Zero se executado com sucesso.
9.3.38 MenuStart
Inicia a funo de menu. Declaraes: Delphi:
function MenuStart(Port: Smallint; Message:string; ValidDigits: string;TimeOut: smallint): smallint;
Visual Basic:
Function MenuStart(Port As Integer, Message as string, ValidDigits as string, TimeOut as integer) as integer
Guia de Referncia
211
Descrio: Inicia a execuo de um menu. Aps sua execuo o mtodo OnMenu ser chamado devolvendo o dgito escolhido e o status. Parmetros: Port Indica o canal da Placa. Message Frase do menu ValidDigits Dgitos considerados vlidos. Devem ser colocados todos os dgitos de opes vlidas sem separadores. Ex.: "235" TimeOut Tempo mximo para digitao da opo aps a frase definida em Message. Retorno: Retorna Zero se executado com sucesso.
9.3.39 MicOff
Desconecta o udio do microfone ao HeadSet. Somente para placas de 1 canal. Declaraes: Delphi:
function MicOff(Port: Smallint): Smallint;
Visual Basic:
Function MicOff(Port As Integer) As Integer
Descrio: Existem na placa 3 conectores. Num deles pode ser conectado

212
um HeadSet, por onde o usurio do sistema poder estabelecer conversao, dispensando o uso do aparelho telefnico. Quando o componente inicializado, o microfone do headset est desconectado. Porm, o programador tem a flexibilidade de a qualquer momento conect-lo e desconect-lo. Ao desconectar o udio, o interlocutor no poder ouvir o que falado atravs do headset, equivalente a funo MUTE dos aparelhos telefnicos. Parmetros: Port Indica o canal da Placa Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: MicOn
9.3.40 MicOn
Conecta o udio do microfone ao HeadSet. Declaraes: Delphi:
function MicOn(Port: Smallint): Smallint;
Visual Basic:
Function MicOn(Port As Integer) As Integer
Descrio: Existem na placa 3 conectores. Num deles pode ser conectado
Guia de Referncia
213
um HeadSet, por onde o usurio do sistema poder estabelecer conversao, dispensando o uso do aparelho telefnico. Quando o componente inicializado, o microfone do headset est desconectado. Porm, o programador tem a flexibilidade de a qualquer momento conect-lo e desconect-lo. Ao conectar o udio, o interlocutor poder ouvir o que falado atravs do headset. Parmetros: Port Indica o canal da Placa Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: MicOff
9.3.41 PhoneOff
Desconecta o udio do fone ao HeadSet. Declaraes: Delphi:
function PhoneOff(Port: Smallint): Smallint;
Visual Basic:
Function PhoneOff(Port As Integer) As Integer
Descrio: Existem na placa 3 conectores. Num deles pode ser conectado um HeadSet, por onde o usurio do sistema poder estabelecer
214
conversao, dispensando o uso do aparelho telefnico. Quando o componente inicializado, o fone do headset estar desconectado. Porm, o programador tem a flexibilidade de a qualquer momento conectar e desconectar de forma independente, o udio do fone, fazendo uso dos mtodos PhoneOn( ) e PhoneOff( ). Enquanto o fone no for conectado, o usurio no ouvir nada, mas isso no implica que a linha est desligada. Uma ligao pode estar atendida e a placa poder gravar tanto a fala da pessoa que estiver na outra ponta da ligao quanto a do usurio do sistema, que est com o headset, desde que o microfone do headset esteja ligado, porm este no estar ouvindo nada. Parmetros: Port Indica o canal da Placa Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: PhoneOn
9.3.42 PhoneOn
Conecta o udio do fone ao HeadSet. Declaraes: Delphi:
function PhoneOn(Port: Smallint): Smallint;
Visual Basic:
Function PhoneOn(Port As Integer) As Integer
Descrio:
Guia de Referncia
215
Existem na placa 3 conectores. Num deles pode ser conectado um HeadSet, por onde o usurio do sistema poder estabelecer conversao, dispensando o uso do aparelho telefnico. Quando o componente inicializado, o fone do headset estar desconectado. Porm, o programador tem a flexibilidade de a qualquer momento conectar e desconectar de forma independente, o udio do fone, fazendo uso dos mtodos PhoneOn( ) e PhoneOff( ). Enquanto o fone no for conectado, o usurio no ouvir nada, mas isso no implica que a linha est desligada. Uma ligao pode estar atendida e a placa poder gravar tanto a fala da pessoa que estiver na outra ponta da ligao quanto a do usurio do sistema, que est com o headset, desde que o microfone do headset esteja ligado, porm este no estar ouvindo nada. Parmetros: Port Indica o canal da Placa Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: PhoneOff
9.3.43 PickUp
Atende a linha conectada a placa (Liga). Declaraes: Delphi:
function PickUp(Port: Smallint; PauseAfterPickUp: Copyright 2005 Digivoice Eletrnica
216
integer): Sma llint;
Visual Basic:
Function PickUp (Port As Integer, PauseAfterPickUp as Integer) As Integer
Descrio: Sempre que se desejar tomar a linha conectada placa para originar uma ligao ou para atender uma ligao entrante, deve-se fazer uso do mtodo PickUp. A pausa aps o atendimento permite ao desenvolvedor continuar os procedimentos de atendimento aps um tempo especificado por este parmetro. Neste caso o evento OnAfterPickUp gerado aps decorrido este tempo. Parmetros: Port Indica o canal da Placa Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: HangUp
9.3.44 PlayCardinal
Permite reproduzir numerais cardinais inteiros ou fracionrios por extenso. Declaraes:
Guia de Referncia
217
Delphi:
function PlayCardinal(Port: Smallint; Value: string; TermDigits: string; PauseBefore: integer): smallint;
Visual Basic:
Function PlayCardinal (Port As Integer, Value as String, TermDigits as String, PauseBefore as integer) as Integer
Parmetros: Port Indica o canal da Placa. Value Uma string ou varivel contendo o nmero a ser reproduzido. No se deve utilizar ponto como separador de milhares e deve-se utilizar a vrgula como separador decimal TermDigits - uma string contendo um ou mais dgitos, que ao serem detectados finaliza a reproduo das mensagens e gera os eventos OnPlayStop e OnDigitsReceived. PauseBefore Indica uma pausa de n milisegundos antes de iniciar a reproduo Valor de Retorno: Retorna zero se foi iniciado com sucesso ou diferente de Zero no caso de erro
9.3.45 PlayCurrency
Permite reproduzir valores monetrios por extenso. Declaraes: Delphi:
218
function PlayCurrency(Port: Smallint; Value: string; TermDigits: string; PauseBefore: integer): smallint;
Visual Basic:
Function PlayCurrency (Port As Integer, Value as String, TermDigits as String, PauseBefore as integer) as Integer
Parmetros: Port Indica o canal da Placa. Value Uma string ou varivel contendo o valor a ser reproduzido. No se deve utilizar ponto como separador de milhares e deve-se utilizar a vrgula como separador decimal TermDigits - uma string contendo um ou mais dgitos, que ao serem detectados finaliza a reproduo das mensagens e gera os eventos OnPlayStop e OnDigitsReceived. PauseBefore Indica uma pausa de n milisegundos antes de iniciar a reproduo Valor de Retorno: Retorna zero se foi iniciado com sucesso ou diferente de Zero no caso de erro
9.3.46 PlayDate
Permite reproduzir data por extenso. Declaraes: Delphi:
function PlayDate(Port: Smallint; Value: string; Mask: string;
Guia de Referncia
219
TermDigits: string; PauseBefore: integer): smallint;
Visual Basic:
Function PlayDate (Port As Integer, Value as String, Mask as string, TermDigits as String, PauseBefore as integer) as Integer
Parmetros: Port Indica o canal da Placa. Value Uma string ou varivel contendo a data a ser reproduzida. Obrigatoriamente deve ser utilizado a barra "/" como separador. Mask Mscara utilizada que indica o formato da data. Pode assumir os seguintes valores: d/m/y Ex.: "25 de setembro de 2001" d/m Ex.: "25 de setembro" m/d Ex.: "Setembro 25" m/d/y Ex.: "Setembro 25 2001" TermDigits - uma string contendo um ou mais dgitos, que ao serem detectados finaliza a reproduo das mensagens e gera os eventos OnPlayStop e OnDigitsReceived. PauseBefore Indica uma pausa de n milisegundos antes de iniciar a reproduo Valor de Retorno: Retorna zero se foi iniciado com sucesso ou diferente de Zero no caso de erro
9.3.47 PlayFile
Inicia a reproduo de um arquivo atravs da placa.
220
Declaraes: Delphi:
function PlayFile(Port: Smallint; const File_, TermDigits: WideString; Origin: integer): Smallint;
Visual Basic:
Function PlayFile(Port As Integer, File As String, TermDigits As String, Origin as Integer) As Integer
Descrio: O mtodo PlayFile inicia a reproduo de um arquivo atravs da placa. possvel programar a interrupo atravs de um ou mais dgitos recebidos atravs do parmetro TermDigits. Ao iniciar a reproduo o evento OnPlayStart gerado e o evento OnPlayStrop ao trmino, indicando o motivo da interrupo. possvel interromper tambm manualmente atravs do mtodo StopRecordFile. O PlayFile detecta automaticamente o tipo de arquivo, baseado na extenso para .sig, .gsm e se for wave, detecta se PCM ou LeiMi. Isso permite uso de diversos formatos para reproduo sem preocupao para o programador. Se for utilizado uma extenso desconhecida, fica valendo o que est especificado no SetPlayFormat. Parmetros: File String contendo o nome e caminho completo do arquivo SIG a ser reproduzido. TermDigits uma string contendo um ou mais dgitos, que ao serem detectados finaliza a reproduo das mensagens e gera os eventos OnPlayStop e OnDigitsReceived. Se qualquer dgito puder interromper utilize o smbolo "@". Se no houver dgito finalizador, passar "" (vazio). Origin - Este parmetro permite reproduzir a mensagem a partir de um determinado ponto. Se for passado 0 (zero) a
Guia de Referncia
221
mensagem reproduzida do incio. Se for passado -1 a mensagem reproduzida a partir do final menos 2 segundos (ideal para ouvir em real-time). Qualquer nmero diferente de 0 e -1 significa a partir de quantos segundos a mensagem ser reproduzida. Valor de Retorno: Retorna zero se foi iniciado com sucesso ou 1 no caso de erro.
9.3.48 PlayList
Inicia a reproduo de uma lista de mensagens de um determinado canal. Declaraes: Delphi:
function PlayList(Port: Smallint; TermDigits:string): smallint;
Visual Basic:
Function PlayList(Port As Integer,TermDigits as String) as i n t e g e r
Descrio: Inicia a reproduo da lista de mensagens associada ao canal indicado por Port que foi criada a partir do mtodo PlayListAdd. O funcionamento idntico ao do PlayFile, sendo gerado apenas um evento OnPlayStart no incio e um OnPlayStop no final da ltima mensagem da lista.
222
Parmetros: Port Indica o canal da Placa. TermDigits uma string contendo um ou mais dgitos, que ao serem detectados finaliza a reproduo das mensagens e gera os eventos OnPlayStop e OnDigitsReceived. Valor de Retorno: 0 OK 1 Lista de mensagens vazia 3 Driver desabilitado
9.3.49 PlayListAdd
Permite adicionar itens a serem reproduzidos na lista do canal. Declaraes: Delphi:
function PlayListAdd(Port: Smallint; ItemType Smallint, Value: string; Mask: string; PauseBefore: integer): Smallint;
Visual Basic:
Function PlayListAdd(Port As Integer, ItemType as integer, Value As String, Mask as String, PauseBefore as Integer) As Integer
Parmetros: Port Indica o canal da Placa. ItemType Configura o tipo de mensagem a ser reproduzida (ptFile, ptCurrency, ptCardinal, ptDate e ptTime)
Guia de Referncia
223
Value a string que contm o valor a ser reproduzido, respeitando a sintaxe determinada por ItemType. Mask Mscara utilizada somente para o tipo ptDate. PauseBefore Indica uma pausa de n milisegundos antes de iniciar a reproduo Valor de Retorno: Retorna zero se foi iniciado com sucesso ou 1 no caso de erro.
9.3.50 PlayListClear
Elimina todos os itens na lista do canal. Declaraes: Delphi:
procedure PlayListClear(Port: Smallint)
Visual Basic:
Sub PlayListClear(Port As Integer)
Descrio: Este mtodo deve ser chamado antes do mtodo PlayListAdd para eliminar todos os elementos que porventura estejam l. Parmetros: Port Indica o canal da Placa. Valor de Retorno: A funo no retorna nada.
224
9.3.51 PlayListGetCount
Retorna a quantidade de elementos na lista daquele canal. Declaraes: Delphi:
function PlayListGetCount(Port: Smallint): smallint;
Visual Basic:
Function PlayListGetCount(Port As Integer) as integer
Descrio: Esta funo devolve a quantidade de elementos da lista de mensagens. Parmetros: Port Indica o canal da Placa. Valor de Retorno: Um inteiro com a quantidade de elementos
9.3.52 PlayListRemoveItem
Remove o item especificado da lista de mensagens do canal Declaraes: Delphi:
function PlayListRemoveItem(Port, Index: Smallint): smallint;
Guia de Referncia
225
Visual Basic:
Function PlayListRemoveItem (Port, Index As Integer) as integer
Descrio: Remove o item especificado pelo parmetro Index. Deve ser utilizado um valor entre 0 e n-1. Parmetros: Port Indica o canal da Placa. Index ndice do elemento a ser removido Valor de Retorno: True se conseguiu remover e False no caso de erro.
9.3.53 PlayNumber
Permite reproduzir nmeros dgito a digito. Declaraes: Delphi:
function PlayNumber(Port: Smallint; Value: string; TermDigits: string; PauseBefore: integer): smallint;
Visual Basic:
Function PlayNumber (Port As Integer, Value as String, TermDigits as String, PauseBefore as integer) as Integer
Parmetros: Port Indica o canal da Placa.

226
Value Uma string ou varivel contendo o nmero a ser reproduzido. No se deve utilizar ponto como separador de milhares e deve-se utilizar a vrgula como separador decimal TermDigits - uma string contendo um ou mais dgitos, que ao serem detectados finaliza a reproduo das mensagens e gera os eventos OnPlayStop e OnDigitsReceived. Pode falar tambm: barra, trao, vrgula e ponto PauseBefore Indica uma pausa de n milisegundos antes de iniciar a reproduo Valor de Retorno: Retorna zero se foi iniciado com sucesso ou diferente de Zero no caso de erro
9.3.54 PlayTime
Permite reproduzir hora por extenso. Declaraes: Delphi:
function PlayTime(Port: Smallint; Value: string; TermDigits: string; PauseBefore: integer): smallint;
Visual Basic:
Function PlayTime(Port As Integer, Value as String, TermDigits as String, PauseBefore as integer) as Integer
Parmetros: Port Indica o canal da Placa.
Guia de Referncia
227
Value Uma string ou varivel contendo a hora a ser reproduzida. Obrigatoriamente a hora deve estar representada no formato hh:mm:ss ou hh:mm TermDigits - uma string contendo um ou mais dgitos, que ao serem detectados finaliza a reproduo das mensagens e gera os eventos OnPlayStop e OnDigitsReceived. PauseBefore Indica uma pausa de n milisegundos antes de iniciar a reproduo Valor de Retorno: Retorna zero se foi iniciado com sucesso ou diferente de Zero no caso de erro
9.3.55 PromptAbort
Interrompe a execuo de uma funo de PromptStart. Declaraes: Delphi:
function PromptAbort(Port: Smallint): Smallint;
Visual Basic:
Function PromptAbort (Port As Integer) As Integer
Descrio: Ao chamar este mtodo a funo iniciada pelo PromptStart ser interrompida para o canal especfico. Parmetros: Port Indica o canal da Placa que gerou o evento
228
Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: PromptStart
9.3.56 PromptSettings
Configura as opes de prompt Declaraes: Delphi:
function PromptSettings(Port: Smallint;PlaybackPhrase:string; ConfirmationPhrase: string;RetryDigit: string; ConfirmationDigit:string; CancelDigit: string):smallint
Visual Basic:
Function PromptSettings(Port As Integer, PlaybackPhrase as string, ConfirmationPhrase as string, RetryDigit as string, ConfirmationDigit as string, CancelDigit as string) as integer
Descrio: Tem a finalidade de configurar as condies de confirmao e conferncia dos dados digitados. Parmetros: Port Indica o canal da Placa. PlaybackPhrase Frase utilizada para conferncia ex.: "Voc digitou" ConfirmationPhrase Frase para confirmao ex.: "Tecle * para confirmar, # para cancelar ou 9 para digitar de
Guia de Referncia
229
novo" RetryDigit Digito que indicar redigitao dos dados ConfirmationDigit - Digito que indicar aceitao dos dados CancelDigit - Digito que indicar cancelamento da entrada de dados Retorno: Retorna Zero se executado com sucesso.
9.3.57 PromptStart
Inicia a funo especial de entrada de dados Declaraes: Delphi:
function PromptStart(Port: Smallint; Message: string; MinDigit, MaxDigit,Timeout: smallint; InterdigitTimeout: smallint; TermDigits: string; WithConfirmation, WithPlayback: boolean; Retries: smallint): Smallin t;
Visual Basic:
Function PromptAbort(Port As Integer, Message as string, MinDigit, MaxDigit,Timeout as integer; InterdigitTimeout as integer; TermDigits as string; WithConfirmation, WithPlayback as boolean; Retries as integert) as integer
Descrio: Ao chamar este mtodo a funo de prompt iniciada. O processo terminar gerando o evento OnPrompt que indicar o
230
dado digitado e o Status. Parmetros: Port Indica o canal da Placa que gerou o evento Message Mensagem ou lista de mensagens a serem reproduzidas para indicar a entrada de dados. Ex.: "Digite sua senha..." MinDigit Nmero mnimo de dgitos a serem esperados pela funo. Aps o timeout ou digito terminador, se o nmero mnimo no for alcanado, a funo avisar no evento OnPrompt MaxDigit Nmero mximo de dgitos a serem esperados pela funo. TimeOut Timout global de espera de dgitos a ser contado aps o trmino da mensagem. InterdigitTimeOut Timeout interdgito a ser considerado aps a digitao do primeiro dgito. TermDigits Dgitos terminadores de entrada de dados. Ex.: "Disque sua senha e # para terminar" neste caso a # deve ser passada como parmetro aqui. WithConfirmation Se true, Executa as funes de confirmao WithPlayback Se true, executa as funes de conferncia, reproduzindo o que foi digitado. Retries Nmero de repeties do prompt em caso do usurio no digitar nada. Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro.
9.3.58 PutSamples
Envia amostras para um canal da placa.
Guia de Referncia
231
Declaraes: Delphi:
Function PutSamples(Port: integer, VARIANT SamplesArray)
Visual Basic:
Sub PutSamples(Port As Integer, SamplesArray)
Descrio: Este mtodo envia o contedo de SamplesArray para um determinado canal da placa, permitindo que estas amostras sejam reproduzidas pela placa. Parmetros: Port Indica o canal da Placa. SamplesArray Vetor Variant de 33 amostras Valor de Retorno: 0 OK > 0 - Falha
9.3.59 ReadDigits
L o contedo do buffer de dgitos do canal especificado Declaraes: Delphi:
function ReadDigits(Port: Smallint): string;
Visual Basic:
Function ReadDigits(Port As Integer) As String
Descrio:
232
O mtodo ReadDigits permite ler o contedo do buffer de dgitos do canal informado. Este buffer preenchido pelos mtodos PlayFile, RecordFile ou GetDigits. Parmetros: Port Indica o canal da Placa Valor de Retorno: Retorna uma string com os dgitos ou nulo caso no haja nada
9.3.60 ReadSecurityWord
Permite ler a string de segurana da memria da placa. Declaraes: Delphi:
function ReadSecurityWord(Card: smallint; Param: WideString):string;
Visual Basic:
Function WriteSecurityWord(Card as Integer, Param as String) as String
Descrio: Esta funo permite ler 10 caracteres da memria da placa. Sempre so lidos os 10 caracteres em uma nica chamada da funo. Esta funo relativamente lenta e, por isso, no deve ser utilizada durante algum processamento mais intenso. Parmetros: Card Indica a placa a ser lida, indo de 1 a n. Param String reservada. Passar sempre nula.
Guia de Referncia
233
OBS.: Esta funo s est disponvel em placas equipadas com memria EEPROM (v1.6 em diante) da VoicerPhone e em todas as VoicerBox PCI/4
9.3.61 RecordFile
Inicia a gravao de um arquivo atravs da placa. Declaraes: Delphi:
function RecordFile(Port: Smallint; const File_, TermDigits: WideString): Smallint;
Visual Basic:
Function RecordFile(Port As Integer, File As String, TermDigits As String) As Integer
Descrio: O mtodo RecordFile inicia a gravao de um arquivo atravs da placa. possvel programar a interrupo da gravao atravs de um ou mais dgitos recebidos atravs do parmetro TermDigits. Ao iniciar a gravao o evento OnRecordStart gerado e o evento OnRecordStop ao trmino, indicando o motivo da interrupo. possvel interromper tambm manualmente atravs do mtodo StopRecordFile. Parmetros: Port Indica o canal da Placa. File String contendo o nome e caminho completo do arquivo SIG que ser gravado. TermDigits uma string contendo um ou mais dgitos, que ao serem detectados finaliza a execuo do GetDigits e gera o evento OnDigitsReceived. Se qualquer dgito puder interromper utilize o smbolo "@" ao invs de colocar "0123456789#*", apesar de a segunda forma tambm estar
234
correta. Se no houver dgito finalizador, passar "" (vazio). Valor de Retorno: Retorna zero se foi iniciado com sucesso ou 1 no caso de erro. Veja Tambm: OnRecordStart, OnRecordStop, StopRecordFile
9.3.62 RecordPause
Interrompe temporariamente uma gravao, permitindo sua continuao no mesmo arquivo Declaraes: Delphi:
function RecordPause(Port: Smallint;Paused: boolean): Smallint;
Visual Basic:
Function RecordFile(Port As Integer, Paused as Boolean) As Integer
Descrio: O mtodo RecordPause permite que a gravao fique em pausa. Isto facilita a programao principalmente quando o usurio quiser colocar o cliente em espera e no desejar que este perodo seja gravado. Parmetros: Port Indica o canal da Placa. Paused True coloca em pausa e False retira.
Guia de Referncia
235
9.3.63 SetAnswerSensitivity
Permite aumentar ou diminuir a sensibilidade da deteco de atendimento. Declaraes: Delphi:
procedure SetAnswerSensitivity(Factor: smallint);
Visual Basic:
Function SetAnswerSensitivity(Factor as integer)
Descrio: Este mtodo configura o nvel de sensibilidade da deteco de atendimento. Deve ser chamado no inicio da aplicao e afeta todos os canais ao mesmo tempo. Parmetros: Factor Fator de sensibilidade que varia de 1 (menos sensvel) at 10 (mais sensvel). No inicio, o valor padro 6 Retorno: Retorna Zero se executado com sucesso.
9.3.64 SetAnswerThreshold
Permite alterar o limiar para deteo de atendimento. Declaraes:
236
Delphi:
procedure SetAnswerThreshold(Port:smallint, Threshold: smallint);
Visual Basic:
Function SetAnswerThreshold(Port as integer, Threshlod as integer);
Descrio: O limiar de atendimento deve ser utilizado em conjunto com o fator de sensibilidade (SetAnswerSensitivity) para melhorar a deteco de atendimento em casos onde ela dificuldada pelas condies da rede pblica. Parmetros: Port - Canal Threshold - Pode variar de 1 a 30. O valor padrao 4. Quanto maior o valor, maior a sensibilidade, mais fcil de detectar o atendimento. Se o valor estiver muito alto, possvel que o atendimento seja detectado antes da hora.
9.3.65 SetCallAfterAnswer
Configura as opes aps a deteo de atendimento do mtodo MakeCall Declaraes: Delphi:
procedure SetCallAfterAnswer(Port: Smallint; FileName: string; Pause: SmallInt;
Guia de Referncia
237
AutoHangUp: Boolean);
Visual Basic:
Function SetCallAfterAnswer(Port As Integer,Filename as String, Pause as Integer, AutoHangUp as Boolean) As Integer
Descrio: Este mtodo configura uma frase para ser reproduzida aps a deteo de atendimento Parmetros: Port Indica o canal da Placa. FileName Indica o nome do arquivo de voz a ser reproduzido Pause Em milisegundos, indica a pausa aps o atendimento antes de reproduzir a mensagem. AutoHangUp Indica se, aps uma discagem do tipo Flash, desliga automaticamente quando detectado o atendimento. Retorno: Retorna Zero se executado com sucesso.
9.3.66 SetCallAfterPickup
Configura as opes aps o pickup do mtodo MakeCall Declaraes: Delphi:
procedure SetCallAfterPickup(Port: Smallint; Digiti: string; PauseAfter: SmallInt);
238
Visual Basic:
Function SetCallAfterPickup(Port As Integer,Digit as String, PauseAfter as Integer) As Integer
Descrio: Este mtodo configura os dgitos a serem discados aps o atendimento (ex. Para pegar linha externa) e uma pausa. Parmetros: Port Indica o canal da Placa. Digit Indica o(s) dgito(s) a serem discados PauseAfter Em milisegundos, indica a pausa aps o PickUp dado pelo mtodo MakeCall. Retorno: Retorna Zero se executado com sucesso.
9.3.67 SetCallBusyPhrase
Configura a frase a ser reproduzida em caso de ocupado. Declaraes: Delphi:
procedure SetCallBusyPhrase(Port: Smallint; FileName: string);
Visual Basic:
Function SetCallBusyPhrase (Port As Integer,Filename as String) As Integer
Descrio: Este mtodo configura uma frase para ser reproduzida em caso
Guia de Referncia
239
de ocupado. Parmetros: Port Indica o canal da Placa. FileName Indica o nome do arquivo de voz a ser reproduzido Retorno: Retorna Zero se executado com sucesso.
9.3.68 SetCallBusyReturnFlash
Configura o flash em caso de ocupado. Declaraes: Delphi:
procedure SetCallBusyReturnFlash(Port: Smallint; Count: smallint; Digit: String; PauseAfter: smallint): smallint;
Visual Basic:
Function SetCallBusyReturnFlash (Port As Integer, Count as Integer, Digit as String, PauseAfter as Integer) as integer
Descrio: Este mtodo configura as opes de flash de retomada em caso de ocupado. Parmetros: Port Indica o canal da Placa. Count Nmero de flashes Digit Digito aps o flash (se existir)
240
PauseAfter Pausa aps o flash Retorno: Retorna Zero se executado com sucesso.
9.3.69 SetCallFlashTime
Configura o flash geral do mtodo MakeCall Declaraes: Delphi:
procedure SetCallFlashTime(Port: Smallint; FlashTime:smallint): smallint;
Visual Basic:
Function SetCallFlashTime(Port As Integer, FlashTime as Integer) as integer
Descrio: Este mtodo configura o tempo de flash a ser utilizado em todas as situaes executadas pelo mtodo MakeCall. Parmetros: Port Indica o canal da Placa. FlashTime Tempo de flash em milisegundos. Retorno: Retorna Zero se executado com sucesso.
Guia de Referncia
241
9.3.70 SetCallNoAnswerPhrase
Configura a frase a ser reproduzida em caso de no atendimento. Declaraes: Delphi:
procedure SetCallNoAnswerPhrase(Port: Smallint; FileName: string);
Visual Basic:
Function SetCallNoAnswerPhrase(Port As Integer,Filename as String) As Integer
Descrio: Este mtodo configura uma frase para ser reproduzida em caso de no atendimento. Parmetros: Port Indica o canal da Placa. FileName Indica o nome do arquivo de voz a ser reproduzido Retorno: Retorna Zero se executado com sucesso.
9.3.71 SetCallNoAnswerReturnFlash
Configura o flash em caso de no atendimento. Declaraes:
242
Delphi:
procedure SetCallNoAnswerReturnFlash(Port: Smallint; Count: smallint; Digit: String; PauseAfter: smallint): smallint;
Visual Basic:
Function SetCallNoAnswerReturnFlash(Port As Integer, Count as Integer, Digit as String, PauseAfter as Integer) as integer
Descrio: Este mtodo configura as opes de flash de retomada em caso de no atendimento. Parmetros: Port Indica o canal da Placa. Count Nmero de flashes Digit Digito aps o flash (se existir) PauseAfter Pausa aps o flash Retorno: Retorna Zero se executado com sucesso.
9.3.72 SetCallNoAnswerRingCount
Configura a quantidade de rings a serem considerados como no atendimento Declaraes: Delphi:
procedure SetCallNoAnswerRingCount(Port: Smallint; RingCount:smallint): smallint;
Visual Basic:
Function SetCallNoAnswerRingCount (Port As Integer,
Guia de Referncia
243
RingCount as Integer) as integer
Descrio: Este mtodo configura o tempo de flash a ser utilizado em todas as situaes executadas pelo mtodo MakeCall. Parmetros: Port Indica o canal da Placa. RingCount Nmerod de rings. Retorno: Retorna Zero se executado com sucesso.
9.3.73 SetCallPauseBeforeAnalysis
Configura o tempo de pausa antes de iniciar a superviso do mtodo MakeCall Declaraes: Delphi:
procedure SetCallPauseBeforeAnalysis(Port: Smallint; PauseBefore:smallint): smallint;
Visual Basic:
Function SetCallPauseBeforeAnalysis(Port As Integer, PauseBefore as Integer) as integer
Descrio: Este mtodo configura o tempo de pausa antes de se iniciar a superviso. Pode ser utilizado para evitar false atendimento em
244
algumas situaes. Parmetros: Port Indica o canal da Placa. PauseBefore Tempo de flash em milisegundos. Retorno: Retorna Zero se executado com sucesso.
9.3.74 SetCallStartFlash
Configura o flash inicial em discagens com flash. Declaraes: Delphi:
procedure SetCallStartFlash(Port: Smallint; Count: smallint; Digit: String; PauseAfterFlash: smallint; ; PauseAfterDigit: smallint): smallint;
Visual Basic:
Function SetCallStartFlash(Port As Integer, Count as Integer, Digit as String, PauseAfterFlash as Integer, PauseAfterDigit as Integer) as integer
Descrio: Este mtodo configura as opes de flash inicial. utilizado quando o mtodo MakeCall chamado com o formato ctWithFlash. Parmetros: Port Indica o canal da Placa.
Guia de Referncia
245
Count Nmero de flashes Digit Digito aps o flash (se existir) PauseAfterFlash Pausa aps o flash PauseAfterDigit - Pausa aps o dgito Retorno: Retorna Zero se executado com sucesso.
9.3.75 SetCallWaitForDialTone
Indica se o tom de discagem dever ser aguardado. Declaraes: Delphi:
procedure SetCallWaitForDialTone(Port: Smallint; WaitForDialTone: boolean);
Visual Basic:
Function SetCallWaitForDialTone(Port As Integer, WaitForDialTone as boolean) as integer
Descrio: Este mtodo indica se o mtodo MakeCall dever esperar pelo tom de discagem antes de discar. Se no receber este tom, gera o evento OnAfterMakeCall indicando a situao. Parmetros: Port Indica o canal da Placa. WaitForDialTone True/False Retorno: Retorna Zero se executado com sucesso.
246
9.3.76 SetDetectionType
Determina o tipo de sinalizao que a placa dever interpretar para fins de identificao de assinante A ou tons de opes de menu em cada canal. Declaraes: Delphi:
procedure SetDetectionType(Port: Smallint; DetectionType: SmallInt);
Visual Basic:
Function SetDetectionType (Port As Integer, DetectionType as Integer) As Integer
Descrio: As companhias telefnicas sinalizao a Identificao do Assinante "A" (quem est discando) atravs de dois tipos de sinal: DTMF e MFP. Esta sinalizao ocorre antes do primeiro Ring. No caso de deteo dos tons do telefone para um atendedor com menu, utiliza-se a deteo DTMF.
9.3.77 SetDTMFAttenuatingHigh
Indicar o fator de atenuao para a freqncia alta na gerao de tons DTMF. Declaraes: Delphi:
procedure SetDTMFAttenuatingHigh(Value: integer);
Guia de Referncia
247
Visual Basic:
Function SetDTMFAttenuatingHigh(Value as Integer) As Integer
Descrio: Este mtodo pode receber valores entre 0 e 60 dB (decibis) para atenuao da freqencia alta. Normalmente, valores acima de 20 dB de atenuao j tornam o tom inaudvel. Quando um novo valor atribudo, todos os canais de todas as placas so afetados. Parmetros: Duration Durao em milissegundos Valor de Retorno: Retorna zero se for executada com sucesso.
9.3.78 SetDTMFAttenuatingLow
Indicar o fator de atenuao para a freqncia baixa na gerao de tons DTMF. Declaraes: Delphi:
procedure SetDTMFAttenuatingLow(Value: integer);
Visual Basic:
Function SetDTMFAttenuatingLow(Value as Integer) As Integer
Descrio:
248
Esta propriedade pode receber valores entre 0 e 60 dB (decibis) para atenuao da freqencia baixa. Normalmente, valores acima de 20 dB de atenuao j tornam o tom inaudvel. Quando um novo valor atribudo, todos os canais de todas as placas so afetados. Parmetros: Duration Durao em milissegundos Valor de Retorno: Retorna zero se for executada com sucesso.
9.3.79 SetDTMFDuration
Determina a durao do tom DTMF gerado pela biblioteca Declaraes: Delphi:
procedure SetDTMFDuration(Duration: integer);
Visual Basic:
Function SetDTMFDuration(Duration as Integer) As Integer
Descrio: O tom tem a durao de 100ms como padro mas poder ser alterado conforme a necessidade. Quando um novo valor atribudo, todos os canais de todas as placas so afetados. Parmetros: Duration Durao em milissegundos
Guia de Referncia
249
Valor de Retorno: Retorna zero se for executada com sucesso.
9.3.80 SetDTMFPause
Determina a durao, em milisegundos, da pausa interdigital em uma discagem por tom. Declaraes: Delphi:
procedure SetDTMFPause(Duration: integer);
Visual Basic:
Function SetDTMFPause(Duration as Integer) As Integer
Descrio: Se o metodo Dial tiver mais de um dgito como parmetro, uma pausa entre os dgitos acontece, respeitando o tempo determinado por esta propriedade. Quando um novo valor atribudo, todos os canais de todas as placas so afetados. Parmetros: Duration Durao em milissegundos Valor de Retorno: Retorna zero se for executada com sucesso.
250
9.3.81 SetDTMFTwist
Permite alterar fatores de sensibilidade para a deteco de dgitos. Declaraes: Delphi:
procedure SetDTMFTwist(Twist1: integer; Twist2: integer);
Visual Basic:
Function SetDTMFTwist(Twist1 as Integer, Twist2 as integer) As Integer
Descrio: Este mtodo deve ser utilizado somente quando for constatado que em situaes normais de operao, a deteco de DTMF esteja, ou muito sensvel ou pouco sensvel. O padro DTMF composto de um par de freqncias (tons) para cada dgito discado que chamaremos respectivamente de F1 e F2. Devido s caractersticas da linha telefnica e dos equipamentos a elas ligados, as amplitudes destes tons podem ter atenuaes diferentes na propagao pela rede telefnica. A presena de udio juntamente com o par de tons do DTMF (quando a placa est falando uma mensagem) pode prejudicar sua deteco pois gera novos tons F3, junto com F1 e F2. Parmetros: O parmetro TWIST1 diz respeito tolerncia na diferena de amplitude entre as duas freqncias do DTMF F1 e F2. Quanto maior o valor de TWIST, maior a tolerncia a
Guia de Referncia
251
variaes de amplitude entre as duas freqncias ou mais fcil ser a deteco de digitos (podendo at chegar em situaes de talk-off). Quando necessrio, o ajuste desta varivel deve ser feito sem que a placa esteja falando. O valor padro 10, podendo variar de 0 a 99. O parmetro TWIST2 diz respeito seletividade de uma terceira freqncia F3 com relao s duas freqncias, F1 e F2 presentes no udio recebido pela placa, isto quer dizer que quanto menor o valor de TWIST2, maiores podero ser as amplitudes das outras freqncias presentes no udio sem que seja rejeitada a deteco de DTMF, ou seja, os valores menores aumentam a sensibilidade de DTMF podendo chegar at situaes de talk-off. O valor padro 0, podendo variar de 0 a 99. Os dois valores devero ser ajustados empiricamente em situaes que os dgitos no estejam sendo detectados a contento ou, no outro extremo, em situaes de talk-off.
9.3.82 SetFirstFaxFrequency
Modificar a freqncia a ser detectada em caso de fax.
252
Declaraes: Delphi:
function SetFirstFaxFrequency(Frequency: Smallint): Smallint;
Visual Basic:
Function SetFirstFaxFrequency(Frequency As Integer) As Integer
Descrio: Esta frequencia deve ser alterada caso seja necessrio detectar alguma frequencia fora de padro. Neste caso o fax no ser mais detectado. Parmetros: Frequency Valor da freqncia. O padro 1100Hz. Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro.
9.3.83 SetFrequency
Modificar a freqncia padro de superviso Declaraes: Delphi:
function SetFrequency(Frequency: Smallint): Smallint;
Visual Basic:
Guia de Referncia
253
Function SetFrequency(Frequency As Integer) As Integer
Descrio: A freqncia base para deteco dos tons de chamada, ocupado, etc... 425hz. Algumas centrais trabalham com valores diferentes do padro. Alterando esta freqncia as placas Digivoice passaro a monitorar outra faixa de tons. Ao atribuir este valor, todos os canais de todas as placas so afetados. Parmetros: Frequency Valor da freqncia. O padro 400hz. Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro.
9.3.84 SetFrequencyTime
Altera o tempo mnimo para deteco do tom de discagem. Declaraes: Delphi:
function SetFrequencyTime(Duration: Smallint): Smallint;
Visual Basic:
Function SetFrequencyTime(Duration As Integer) As Integer
Descrio:
254
Especifica o tempo de mnimo de durao que o tom dever ocorrer para que a placa possa detect-lo. O valor padro 1500ms, tempo normalmente utilizado para centrais pblicas e privadas, por isso s dever ser alterado em casos de sinalizaes especficas do PABX. Parmetros: Duration Tempo de durao. O padro 1500ms. Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro.
9.3.85 SetImpedance
Atribui um valor de impedncia para as placas VoicerPhone ISA/PCI Declaraes: Delphi:
function SetImpedance(Impedance: Smallint): smallint;
Visual Basic:
Function SetImpedance(Impedance As Integer) As Integer
Descrio: As centrais PABX trabalham com impedncia de 600W ou 900W, dependendo do fabricante e modelo. As placas VoicerPhone devero utilizar a mesma impedncia do PABX para melhor qualidade de udio.
Guia de Referncia
255
Quando o mtodo chamado, todas as placas ISA habilitadas sero afetadas. No tem efeito algum sobre as placas VoicerBox PCI Parmetros: Impedance - Permite os valores it600 ou it900. Valor de Retorno: Retorna zero se for executada com sucesso.
9.3.86 SetPlayFormat
Especifica o formato de reproduo de um canal independente. Declaraes: Delphi:
function SetPlayFormat(Port: Smallint; FileFormat: Smallint): Sma lli nt;
Visual Basic:
Function SetPlayFormat(Port As Integer, FileFormat as Integer) As Integer
Descrio: O mtodo SetPlayFormat permite indicar formatos de reproduo diferentes por canal, os outros canais assumiro o formato especificado na propriedade FileFormat, que determina o formato para todos os canais. Como o novo formato GSM oferece uma qualidade de audio inferior ao Wave pode ser
256
necessrio gravar em GSM e reproduzir mensagens no formato Wave. Com este mtodo possvel manter formatos de reproduo diferentes no mesmo canal ou em canais distintos. O PlayFile agora detecta automaticamente o tipo de arquivo, baseado na extenso para .sig, .gsm e se for wave, detecta se PCM ou LeiMi. Isso permite uso de diversos formatos para reproduo sem preocupao para o programador. Se for utilizado uma extenso desconhecida, fica valendo o que est especificado no SetPlayFormat. Parmetros: Port Indica o canal da Placa. FileFormat Formato para reproduo. 0 - ffWave 1 - ffSig 2 - ffWavePCM 3 - ffGsm610 Valores de Retorno: 0 - Executado com sucesso 1 - Parmetro invlido. 2 - No altera o formato caso o canal esteja reproduzindo uma mensagem. Veja Tambm: SetRecordFormat.
9.3.87 SetRecordFormat
Especifica o formato de gravao de um canal independente. Declaraes:
Guia de Referncia
257
Delphi:
function SetRecordFormat(Port: Smallint; FileFormat: Smallint): Sma lli nt;
Visual Basic:
Function SetRecordFormat(Port As Integer, FileFormat as Integer) As Integer
Descrio: O mtodo SetRecordFormat permite indicar formatos de gravao diferentes por canal, os outros canais assumiro o formato especificado na propriedade FileFormat, que determina o formato para todos os canais. Como o novo formato GSM oferece uma qualidade de audio inferior ao Wave pode ser necessrio gravar em GSM e reproduzir mensagens no formato Wave. Com este mtodo possvel manter formatos de gravao diferentes no mesmo canal ou em canais distintos. Parmetros: Port Indica o canal da Placa. FileFormat Formato para gravao. 0 - ffWave 1 - ffSig 2 - ffWavePCM 3 - ffGsm610 Valores de Retorno: 0 - Executado com sucesso 1 - Parmetro invlido. 2 - No altera o formato caso o canal esteja gravando uma mensagem.
258
Veja Tambm: SetPlayFormat.
9.3.88 SetRecordGain
Especifica o ganho para a gravao. Declaraes: Delphi:
function SetRecordGain(Port: Smallint; Ganho: Smallint): Sma lli nt;
Visual Basic:
Function SetRecordFormat(Port As Integer, Ganho as Integer) As Integer
Descrio: Especifica o ganho para a gravao de um canal independente. O ganho pode variar de 1 a 10 e o padro 4. Caso o valor especificado seja menor que 1, o valor assumido ser 1 e caso o valor especificado seja maior que 10 o valor assumido ser 10. Parmetros: Port Indica o canal da Placa. Ganho Valores de 1 a 10, sendo o padrao 4 Valores de Retorno:
Guia de Referncia
259
0 - Executado com sucesso
9.3.89 SetSecondFaxFrequency
Modificar a freqncia a ser detectada em caso de fax. Declaraes: Delphi:
function SetSecondFaxFrequency(Frequency: Smallint): Smallint;
Visual Basic:
Function SetSecondFaxFrequency(Frequency As Integer) As Integer
Descrio: Esta frequencia deve ser alterada caso seja necessrio detectar alguma frequencia fora de padro. Neste caso o fax no ser mais detectado. Parmetros: Frequency Valor da freqncia. O padro 2100Hz. Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro.
260
9.3.90 SetToneTwist
Permite alterar fatores de sensibilidade para a deteco de tons. Declaraes: Delphi:
procedure SetToneTwist(Twist: integer);
Visual Basic:
Function SetToneTwist(Twist as Integer) As Integer
Descrio: Este mtodo deve ser utilizado somente quando for constatado que em situaes normais de operao, a deteco de tons esteja, ou muito sensvel ou pouco sensvel, principalmente em situaes que o tom gerado em cima da voz. Parmetro: TWIST: Na deteco de tons 425Hz e FAX a varivel TWIST3 diz respeito a rejeio de da freqncia do tom F1 a um segundo tom presente no udio. Quanto maior a varivel TWIST3 maior ser a rejeio. Em outras palavras, quanto maior o valor deste parmetro, menor ser a sensibilidade de deteco de tons em cima da voz. O valor padro 5 e poder variar de 0 a 99.
Guia de Referncia
261
9.3.91 SetVolume
Modificar o volume do headset da placa VoicerPhone (ISA/PCI). Declaraes: Delphi:
function SetVolume(Volume: Smallint): Smallint;
Visual Basic:
Function SetVolume(Volume As Integer) As Integer
Descrio: A placa VoicerPhone permite trs nveis de ganho (volume). Utilize esta propriedade para aumentar ou diminuir o ganho. Este volume pode ser alterado o qualquer momento durante a operao do sistema. O volume pode assimir os valores voOne, voTwo e voThree representando 3 nveis de ganho possveis. Parmetros: Volume O ganho a ser atribudo (voOne, voTwo e voThree) Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro.
9.3.92 ShutdownVoicerLib
Finaliza a comunicao da placa com a aplicao. Declaraes:
262
Delphi:
function ShutdownVoicerLib: Integer;
Visual Basic:
Function ShutdownVoicerLib() As Long
Descrio: Este mtodo faz com que se finalize a comunicao da placa com a aplicao. Logo, a sua chamada dever ser a ltima coisa que o programador dever fazer antes de sair da aplicao. Caso a aplicao seja encerrada sem que o este mtodo tenha sido chamado, o micro corre o risco de "travar" a qualquer momento. Ento, NUNCA FECHE A APLICAO ANTES DE CHAMAR ESTE MTODO. Valores de Retorno: Retorna 99 se executado com sucesso e diferente disso em caso de erro. Veja Tambm: StartVoicerLib
9.3.93 Sig2Wave
Converte do formato SIG para o formato Wave. Declaraes: Delphi:
function Sig2Wave(const Source:WideString;const Destination:WideString; Gain:Double):Smallint;
Visual Basic:
Function Sig2Wave(Source As String, Destination As String, Gain as Double) As Integer
Descrio:
Guia de Referncia
263
A placa VoicerPhone trabalha com arquivos no formato SIG (Lei - 8Khz). Para poder reproduzir um arquivo gerado pela placa em uma placa de som, necessrio converter o arquivo para um formato Wave conhecido. O mtodo Sig2Wave faz esta converso, bastando passar o nome do arquivo de origem, do arquivo de destino e o ganho em relao gravao original em sig. O ganho pode ser 0 indicando que no h ganho. Parmetros: Source String contendo o nome e caminho completo do arquivo SIG que ser convertido. File String contendo o nome e caminho completo do arquivo WAVE que ser gravado. Gain - Fator de ganho sobre o arquivo original em SIG. Pode ser utilizado valores maiores que zero para melhorar gravaes baixas. Valores de Retorno: 0 - Executado com sucesso 1 No foi encontrado o arquivo de origem (Source) 2 No foi possvel criar o arquivo de destino (Destination) 3 - Erro indeterminado Veja Tambm: Wave2Sig Obs.: As verses atuais trabalham tambm com formato nativo Wave (8bits, 8khz, mono) portanto d preferncia a trabalhar sempre com wave j que tem o mesmo tamanho do SIG.
9.3.94 StartVoicerLib
Inicializa a comunicao da placa com a aplicao. Declaraes:
264
Delphi:
function StartVoicerLib: Integer;
Visual Basic:
Function StartVoicerLib() As Long
Descrio: Este mtodo faz com que se inicie a comunicao da placa com a aplicao. Logo, a sua chamada dever ser a primeira coisa que o programador dever fazer na aplicao, pois at ento, a placa estar totalmente "morta", e nada ir funcionar. As placas ISA devero ser configuradas previamente atravs do programa utilitrio GeraINI. Valores de Retorno: 99 - executado com sucesso 0 - Erro Genrico Provavemente causado por falha na instalao. Recomenda-se desinstalar e repetir o processo de instalao. 1 - Driver j est inicializado 2 - Arquivo de configuracao inexistente (somente para placas ISA) 3 - Placas PCI nao foram encontradas 4 - Numero de Placas ISA invalido (arquivo de configurao com dados incorretos) 5 - Irq de placa ISA invlido (arquivo de configurao com dados incorretos) 6 - IO de placa ISA invalido (arquivo de configurao com dados incorretos) 7 - Erro de conferncia - provavelmente um conflito de endereos de I/O 8 - Falta do arquivo KPVPISA.VXD (Win9x) ou KPVPISA.SYS (NT/2000) 9 - Erro na abertura dos recursos da placa 10 - Erro na carga do programa - provavelmente um conflito de endereos de I/O
Guia de Referncia
265
Veja Tambm: ShutdownVoicerLib
9.3.95 StopPlayFile
Interrompe a reproduo de um arquivo SIG. Declaraes: Delphi:
function StopPlayFile(Port: Smallint): Smallint;
Visual Basic:
Function StopPlayFile(Port As Integer) As Integer
Descrio: Este mtodo interrompe a reproduo de um arquivo SIG. Neste caso, o evento OnPlayStop gerado e o parmetro Status receber o valor ssStopped. Parmetros: Port Indica o canal da Placa Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: PlayFile
9.3.96 StopRecordFile
Interrompe a gravao de um arquivo SIG.
266
Declaraes: Delphi:
function StopRecordFile(Port: Smallint): Smallint;
Visual Basic:
Function StopRecordFile(Port As Integer) As Integer
Descrio: Este mtodo interrompe a gravao de um arquivo SIG. Neste caso, o evento OnRecordStop gerado e o parmetro Status receber o valor ssStopped. Parmetros: Port Indica o canal da Placa Valor de Retorno: Retorna zero se foi executado com sucesso ou 1 no caso de erro. Veja Tambm: RecordFile
9.3.97 Wave2Sig
Converte do formato Wave para o formato SIG. Declaraes: Delphi:
function Wave2Sig(const Source, Destination: WideString): Sma lli nt;
Guia de Referncia
267
Visual Basic:
Function Wave2Sig(Source As String, Destination As String) As Int ege r
Descrio: A placa VoicerPhone trabalha com arquivos no formato SIG (Lei - 8Khz). Para poder reproduzir um arquivo gerado por um placa de som (tipo SoundBlaster), necessrio converter o arquivo WAVE para o formato SIG reconhecido. O mtodo Wave2Sig faz esta converso, bastando passar o nome do arquivo de origem e do arquivo de destino Parmetros: Source String contendo o nome e caminho completo do arquivo WAVE que ser convertido. File String contendo o nome e caminho completo do arquivo SIG que ser gravado. Valores de Retorno: 0 - Executado com sucesso 1 - No foi encontrado o arquivo de origem (Source) 2 - No foi possvel criar o arquivo de destino (Destination) 3 - Erro indeterminado Veja Tambm: Sig2Wave.
O arquivo Wave dever ser 8khz, 16bits, Mono para que a converso seja possvel
268
9.3.98 WaveToGsm
Converte do formato Wave para o formato GSM. Declaraes: Delphi:
function WaveToGsm(const Source:WideString; const Destination: WideString): Sma lli nt;
Visual Basic:
Function WaveToGsm(Source As String, Destination As String) As Int ege r
Parmetros: Source String contendo o nome e caminho completo do arquivo GSM que ser convertido. Destination String contendo o nome e caminho completo do arquivo Wave que ser gravado. Valores de Retorno: 0 - Executado com sucesso 1 - No foi encontrado o arquivo de origem (Source) 2 - No foi possvel criar o arquivo de destino (Destination) 3 - Erro indeterminado na converso Veja Tambm: GsmToWave.
O arquivo Wave dever ser 8khz,
Guia de Referncia
269
16bits, Mono para que a converso seja possvel
9.3.99 WriteSecurityWord
Permite gravar string de segurana na memria da placa. Declaraes: Delphi:
function WriteSecurityWord(Card: smallint; Data, Param:String):smallint;
Visual Basic:
Function WriteSecurityWord(Card as Integer, Data As String Param as String) as Integer
Descrio: A funo WriteSecurityWord permite gravar na memria da placa at 10 caracteres. sempre gravado do primeiro endereo em diante, ou seja, o programador no tem acesso a um endereo especfico de memria. Caso seja enviado mais de 10 caracteres, a string ser truncada e o restante ser descartado. OBS.: Esta funo s est disponvel em placas equipadas com memria EEPROM. Parmetros: Card A placa que dever ser gravada. De 1 a n. Data - O dado a ser gravado Param - Uso reservado, passar sempre nulo ("")
270
Valores de Retorno: 0 OK 1 - Erro de I/O 2 - String maior que 10 caracteres 3 - Driver desabilitado - Necessita executar StartVoicerLib
271
ndice Remissivo
-A-
estrutura de programao
42
-F-
Finalizao do driver Fone do Headset 61 Freqencia 45 58
44
Aparelho Telefnico AutoClearDigits 144
82
Atendendo e Desligando
-G-
-B-
Gravao
62
BINA
64
-H-
-C-
hardware
31
Cabo para Gravador Cabos 26 26 Conectores
26
-I-
Identificao de Chamadas Inicializao do Driver instalao 31 28 Instalao da Biblioteca 43
64
-D-
Descrio
27 51 45 Limpando Buffer de Dgitos 100 lgica 42 144
Deteco de Dgitos Deteco de Ring Discagem 56
-L-
Distribuindo sua Aplicao
-E-
-M-
Erros
77
Microfone
60
272
-N-
No Atendimento
46
-O-
Ocupado
46
-P-
Preparao do ambiente Proteo contra cpias
35 79
-R-
Reproduo
73 38
requisitos mnimos
-S-
Superviso de Linha
46
-V-
Volume
59

Voicer Lib 2

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Voicer Lib 2

Transféré par

Droits d'auteur :

Formats disponibles

Digi Voice

Digivoice Tecnologia em Eletrnica

Copyright 2005 Digivoice Eletrnica

Parte IV Tpicos de Programao

Parte V Utilizando um aparelho telefnico Parte VI Funes Especiais

Parte VII Distribuindo uma Aplicao

1 Introduo ......................................................................... 100 2 Preparando ......................................................................... o Ambiente 101

Parte VIII Aplicao Exemplo

Parte IX Guia de Referncia

1 Propriedades ......................................................................... 144

Digivoice VoicerLib2 2 Eventos ......................................................................... 155

3 Mtodos ......................................................................... 176

Copyright 2005 Digivoice Eletrnica

Verso 2.72- 20/12/2004

Copyright 2005 Digivoice Eletrnica

caso este tenha sido feito "em cima" do RING.

Verso 2.67 - 29/08/2003 Correo de erro no Windows98

Copyright 2005 Digivoice Eletrnica

Copyright 2005 Digivoice Eletrnica

Na biblioteca foram includos exemplos de aplicao para Delphi e Visual Basic.

Copyright 2005 Digivoice Eletrnica

Copyright 2005 Digivoice Eletrnica

Copyright 2005 Digivoice Eletrnica

Copyright 2005 Digivoice Eletrnica

Copyright 2005 Digivoice Eletrnica

Copyright 2005 Digivoice Eletrnica

VoicerLibX1.Dial(1,"202',1000) End Sub

ser atendida. Exemplo:

Chr$(voicerlibx1.ReadDig its(Port)) End Sub

Copyright 2005 Digivoice Eletrnica

VoicerLibX1.DelayComma = 1000 VoicerLibX1.Dial(1,"0,72952557",1000, dtPulse) End Sub

Copyright 2005 Digivoice Eletrnica

if x = 0 then 'Liga o fone VoicerLibX1.PhoneOff(1) End if End Sub

Gravando uma Conversa

Reproduzindo Lista de Mensagens

Copyright 2005 Digivoice Eletrnica

'remove o primeiro elemento da lista voice1.PlayListRemoveItem(Port,0)

Reproduzindo Nmeros Cardinais

Reproduzindo Nmeros Dgito a Dgito

Reproduzindo uma Mensagem

Reproduzindo Valores por Extenso

Status dos Canais

Protegendo sua Aplicao

Copyright 2005 Digivoice Eletrnica

Utilizando um aparelho telefnico

Quando o telefone colocado novamente do gancho, o evento OnLineOff gerado. Exemplo:

Utilizando um aparelho telefnico

Copyright 2005 Digivoice Eletrnica

Funes de Discagem e Transferncia

desabilitado na inicializao da VoicerLib.

Funes para Streaming de Audio

Copyright 2005 Digivoice Eletrnica

Distribuindo uma Aplicao

Distribuindo uma Aplicao

do Digivoice Driver aps o trmino da sua prpria instalao.

Copyright 2005 Digivoice Eletrnica

Distribuindo uma Aplicao

placa io=672 [ISA2] se houver irq=5 io=816

Endereo de I/O (em decimal) Informaes da segunda placa

Copyright 2005 Digivoice Eletrnica

Copyright 2005 Digivoice Eletrnica

Atendimento de uma ligao

Definindo Constantes para a Aplicao