Visão geral da telefonia assistida

Um recurso valioso da telefonia é o pequeno conjunto de funções chamado Telefonia Assistida. A Telefonia Assistida foi projetada para disponibilizar o estabelecimento de chamadas de voz e de chamadas de mídia para qualquer aplicativo, não apenas aqueles dedicados à funcionalidade telefônica. Em outras palavras, a Telefonia Assistida permite que os aplicativos façam chamadas telefônicas sem precisar estar cientes dos detalhes dos serviços da API de Telefonia completa. Ele estende a telefonia a aplicativos de processamento de palavras, planilhas, bancos de dados, gerentes de informações pessoais e outros aplicativos que não são de telefonia.

Para obter uma lista das funções de telefonia assistida tapi 2.x da telefonia básica, consulte Referência de função rápida tapi. O TAPI 3.x dá suporte à telefonia assistida por meio da interface ITRequest .

A utilidade da Telefonia Assistida pode ser ilustrada pelo exemplo a seguir. Um aplicativo de planilha pode incorporar funções que discam um número de telefone para uma chamada de fala. Desde que o aplicativo não precise de nenhum controle de chamada detalhado fornecido pela API de Telefonia completa, a Telefonia Assistida é a maneira mais fácil e eficiente de fornecer a ele funcionalidade telefônica.

A Telefonia Assistida e a API de Telefonia completa são usadas e implementadas de diferentes maneiras, portanto, não é recomendável misturar chamadas de função de telefonia assistida e chamadas de função de API de Telefonia em um único aplicativo.

Usando telefonia assistida

Os aplicativos que usam serviços de telefonia assistida só iniciam solicitações de chamada que são temporariamente enfileiradas pelo TAPI. O aplicativo destinatário da solicitação recupera essas solicitações e as executa em nome do aplicativo de telefonia assistida. A função tapiRequestMakeCall solicita o estabelecimento de uma chamada de voz. O aplicativo solicitante não controla a chamada.

O TAPI permite que o usuário estabeleça aplicativos de destinatário de solicitação diferentes ou os mesmos para cada um desses serviços. Um aplicativo se torna um destinatário de solicitação registrando-se com lineRegisterRequestRecipient, no qual TRUE é especificado como o valor para o parâmetro bEnable. (Especificar false desregistros do aplicativo como um destinatário de solicitação, o que ele deve fazer quando tiver determinado que suas tarefas de destinatário são para a sessão atual.) O aplicativo seleciona os serviços que deseja manipular no parâmetro dwRequestMode de lineRegisterRequestRecipient. Um valor possível para uma solicitação é LINEREQUESTMODE_MAKECALL, para mostrar que o aplicativo lidará com solicitações tapiRequestMakeCall . Se vários aplicativos se registrarem para os mesmos serviços, um esquema de prioridade será usado para permitir que o usuário selecione qual aplicativo é preferencial para lidar com solicitações. Esse esquema de prioridade é idêntico ao usado para entrega de chamada e o roteamento de chamadas de entrada com base em uma lista de nomes de arquivo em HandoffPriorities no registro.

Solicitações de Chamada

A Telefonia Assistida fornece aplicativos habilitados para telefonia com um mecanismo fácil de usar para fazer chamadas telefônicas sem exigir que o desenvolvedor se torne totalmente alfabetizado em telefonia.

A função tapiRequestMakeCall solicita uma chamada de voz entre o usuário e uma parte remota especificada por seu número de telefone. A solicitação é feita ao TAPI, que a passa para um aplicativo registrado como destinatário dessas solicitações. Esse destinatário é um aplicativo do gerenciador de chamadas.

Depois que o aplicativo tiver feito a solicitação, a chamada será controlada inteiramente do aplicativo gerenciador de chamadas porque os aplicativos de telefonia assistida não podem gerenciar chamadas. Como os aspectos mais complexos da telefonia e de todas as operações de interface do usuário são tratados pelo aplicativo gerenciador de chamadas, os aplicativos habilitados para telefonia não precisam ser modificados de forma substancial. Na verdade, os aplicativos que permitem que essa operação seja invocada de sua linguagem de script interna podem não precisar ser modificados.

A função tapiGetLocationInfo retorna ao aplicativo o código de país ou região e o código da cidade (área) que o usuário definiu nos parâmetros de localização atuais no Painel de Controle de Telefonia. O aplicativo pode usar essas informações para ajudar o usuário a formar números de telefone canônicos adequados, como oferecendo-os como padrão quando novos números são inseridos em uma entrada de catálogo telefônico ou registro de banco de dados.

Solicitar destinatários

Dois tipos de aplicativos são necessários para executar a Telefonia Assistida. Clientes de telefonia assistida são aplicativos que usam Telefonia Assistida chamando as funções que têm o prefixo "tapi". Um exemplo desse aplicativo cliente seria uma planilha à qual um comando de menu Discar ou botão de barra de ferramentas é adicionado.

Servidores de telefonia assistida são aplicativos que podem executar funções de API de Telefonia resultantes da chamada de outro aplicativo para uma função prefixada "tapi". Para se tornar conhecido como um servidor de telefonia assistida, um aplicativo se registra como um usando a função lineRegisterRequestRecipient .

As funções da Telefonia Assistida (que começam com o prefixo "tapi") são conhecidas como funções de solicitação. Os aplicativos de telefonia assistida que processam essas solicitações — servidores de telefonia assistida — são chamados de destinatários de solicitação.

Processando solicitações de telefonia assistida

O processo com o qual as solicitações são entregues e atendidas é o seguinte:

1. Quando o TAPI recebe uma solicitação de telefonia assistida, ele verifica se há um destinatário da solicitação, ou seja, um aplicativo registrado no momento para processar esse tipo de solicitação. Se houver um destinatário da solicitação, a solicitação será enfileirada e o aplicativo de prioridade mais alta registrado para o serviço dessa solicitação será enviado uma mensagem LINE_REQUEST . A mensagem notifica o destinatário da solicitação de que uma nova solicitação chegou e ela carrega uma indicação do modo da solicitação.

2. Se a TAPI não encontrar um aplicativo em execução no momento para processar essa solicitação, ele tentará iniciar um aplicativo que foi registrado como capaz de fazer isso. Essas informações de registro são registradas em HandoffPriorities no registro. O TAPI tenta iniciar aplicativos na ordem em que eles estão listados na seção HandoffPriorities . (Confira a etapa a seguir.)

   Se nenhum aplicativo estiver registrado no momento, o TAPI examinará a lista de aplicativos de processamento de solicitação na entrada associada em HandoffPriorities. Se a linha associada estiver ausente do arquivo, se não houver nenhum aplicativo listado nele ou se nenhum dos aplicativos na lista puder ser iniciado, a solicitação será rejeitada com o erro TAPIERR_NOREQUESTRECIPIENT.

   Quando um destinatário de solicitação é iniciado (se foi ou não iniciado pela TAPI), é seu dever chamar lineRegisterRequestRecipient durante o processo de inicialização e registrar-se como um destinatário da solicitação.

3. Se um ou mais aplicativos estiverem listados na entrada, o TAPI começará com o primeiro aplicativo listado (prioridade mais alta) e tentará iniciá-lo usando a função CreateProcess . Se a tentativa de iniciar o aplicativo falhar, o TAPI tentará iniciar o próximo aplicativo na lista. Quando qualquer aplicativo é iniciado com êxito, o TAPI simplesmente enfileira a solicitação e retorna uma indicação de êxito para o aplicativo, mesmo que a solicitação ainda não tenha sido sinalizada para o destinatário da solicitação.

   Depois que o aplicativo destinatário da solicitação é iniciado, ele chama lineRegisterRequestRecipient, o que faz com que uma mensagem LINE_REQUEST seja enviada, sinalizando que a solicitação está na fila. Se, por algum motivo, o aplicativo iniciado nunca se registrar, a solicitação permanecerá na fila e permanecerá na fila indefinidamente até que um aplicativo se registre para esse tipo de solicitação.

4. Se a TAPI encontrar esse aplicativo registrado já em execução ou iniciar com êxito um, ele enfileira a solicitação, enviando uma mensagem LINE_REQUEST para o aplicativo servidor e retorna uma indicação de êxito para a chamada de função para o aplicativo de Telefonia Assistida. Essa mensagem de êxito afirma apenas que a solicitação foi aceita e enfileirada, não que ela tenha sido executada com êxito.

Quando o aplicativo de servidor está pronto para processar uma solicitação, ele chama a função lineGetRequest . Isso permite que ele receba todas as informações necessárias, como um endereço para discar. Em seguida, ele processa a solicitação, usando as funções TAPI (como lineMakeCall e lineDrop) que, de outra forma, seriam usadas para fazer a chamada. Invocar lineGetRequest remove a solicitação do TAPI e os parâmetros de solicitação são copiados em um buffer de solicitação alocado pelo aplicativo. O tamanho e a interpretação do conteúdo do buffer dependem do modo de solicitação.

O servidor deve garantir que ele use os parâmetros corretos ao executar solicitações. Ao fazer isso, estas etapas são seguidas:

1. Primeiro, o destinatário da solicitação recebe uma mensagem LINE_REQUEST informando que as solicitações podem existir para ele na fila de solicitações. Isso informa ao aplicativo para chamar lineGetRequest e continuar chamando-o até que a fila seja drenada (se a solicitação for para fazer uma nova chamada) ou para descartar uma chamada existente. Essa mensagem não contém os parâmetros da solicitação, exceto no caso de uma solicitação para remover uma chamada existente.
2. Se a solicitação for fazer uma nova chamada, o servidor de Telefonia Assistida usará a função lineGetRequest para recuperar a solicitação completa, que inclui os parâmetros da solicitação. O servidor agora tem todas as informações necessárias, como o número para discar ou a identificação do criador da solicitação. Primeiro, no entanto, o servidor deve alocar a memória necessária para armazenar essas informações.
3. Por fim, o servidor executa a solicitação invocando a função TAPI apropriada ou o conjunto de funções.

Se a TAPI não puder iniciar um aplicativo capaz de servir como um destinatário de solicitação, a chamada de telefonia assistida falhará e retornará o erro TAPIERR_NOREQUESTRECIPIENT.

Anotações sobre operações de destinatário de solicitação

As informações a seguir dizem respeito a sistemas nos quais as solicitações de telefonia assistida são processadas:

• O registro padrão deve listar um aplicativo do gerenciador de chamadas na lista de prioridades para tapiRequestMakeCall. Seria útil, mas não essencial, que o aplicativo gerenciador de chamadas tivesse uma opção de menu que permite que os usuários o definam como a prioridade mais alta.
• Quando um aplicativo destinatário de Telefonia Assistida é iniciado automaticamente pelo TAPI e, se for o único aplicativo TAPI no sistema, essa ação inicializará o TAPI. Se o aplicativo destinatário de Telefonia Assistida inicializar e desligar o dispositivo de linha antes de se registrar para solicitações de Telefonia Assistida, o TAPI também será desligado e a solicitação de Telefonia Assistida será perdida. As solicitações de telefonia assistida também podem ser perdidas quando outro aplicativo TAPI iniciado executa um desligamento e inicialização.