Função phoneInitializeExA (tapi.h)

Artigo
03/02/2024

A função phoneInitializeEx inicializa o uso do TAPI pelo aplicativo para uso subsequente da abstração do telefone. Ele registra o mecanismo de notificação especificado do aplicativo e retorna o número de dispositivos de telefone disponíveis para o aplicativo. Um dispositivo de telefone é qualquer dispositivo que fornece uma implementação para as funções prefixadas por telefone na API de Telefonia.

Sintaxe

LONG phoneInitializeExA(
  LPHPHONEAPP               lphPhoneApp,
  HINSTANCE                 hInstance,
  PHONECALLBACK             lpfnCallback,
  LPCSTR                    lpszFriendlyAppName,
  LPDWORD                   lpdwNumDevs,
  LPDWORD                   lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

Parâmetros

lphPhoneApp

Ponteiro para um local preenchido com o identificador de uso do aplicativo para TAPI.

hInstance

Identificador de instância do aplicativo cliente ou DLL. O aplicativo ou a DLL pode passar NULL para esse parâmetro; nesse caso, o TAPI usa o identificador de módulo do executável raiz do processo.

lpfnCallback

Endereço de uma função de retorno de chamada que é invocada para determinar status e eventos no dispositivo de linha, endereços ou chamadas, quando o aplicativo está usando o método "janela oculta" de notificação de evento (para obter mais informações, consulte phoneCallbackFunc). Esse parâmetro é ignorado e deve ser definido como NULL quando o aplicativo optar por usar os mecanismos de notificação de evento "identificador de evento" ou "porta de conclusão".

lpszFriendlyAppName

Ponteiro para uma cadeia de caracteres terminada em nulo que contém apenas caracteres exibicionáveis. Se esse parâmetro não for NULL, ele conterá um nome fornecido pelo aplicativo para o aplicativo. Esse nome é fornecido na estrutura PHONESTATUS para indicar, de maneira amigável, qual aplicativo tem a propriedade do dispositivo de telefone. Se lpszFriendlyAppName for NULL, o nome de arquivo do módulo do aplicativo será usado em vez disso (conforme retornado pela função GetModuleFileName).

lpdwNumDevs

Ponteiro para um DWORD. Após a conclusão bem-sucedida dessa solicitação, esse local é preenchido com o número de dispositivos de telefone disponíveis para o aplicativo.

lpdwAPIVersion

Ponteiro para um DWORD. O aplicativo deve inicializar esse DWORD, antes de chamar essa função, para a versão mais alta da API à qual foi projetado para dar suporte (por exemplo, o mesmo valor que passaria para o parâmetro dwAPIHighVersion de phoneNegotiateAPIVersion). Valores artificialmente altos não devem ser usados; o valor deve ser definido com precisão. O TAPI converte quaisquer mensagens ou estruturas mais recentes em valores ou formatos compatíveis com a versão do aplicativo. Após a conclusão bem-sucedida dessa solicitação, esse local é preenchido com a versão mais alta da API com suporte pelo TAPI, permitindo que o aplicativo detecte e se adapte a ter sido instalado em um sistema com uma versão mais antiga do TAPI.

lpPhoneInitializeExParams

Ponteiro para uma estrutura do tipo PHONEINITIALIZEEXPARAMS que contém parâmetros adicionais usados para estabelecer a associação entre o aplicativo e o TAPI (especificamente, o mecanismo de notificação de eventos selecionado do aplicativo e os parâmetros associados).

Retornar valor

Retornará zero se a solicitação for bem-sucedida ou um número de erro negativo se ocorrer um erro. Os valores retornados possíveis são:

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

Comentários

Os aplicativos devem selecionar um dos três mecanismos pelos quais o TAPI notifica a aplicação de eventos de telefonia: Janela Oculta, Identificador de Evento ou Porta de Conclusão.

O mecanismo janela oculta é selecionado especificando PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW no membro dwOptions na estrutura PHONEINITIALIZEEXPARAMS . Nesse mecanismo (que é o único mecanismo disponível para TAPI versão 1.x aplicativos), o TAPI cria uma janela no contexto do aplicativo durante a função phoneInitializeEx e subclasse a janela para que todas as mensagens postadas nela sejam tratadas por um WNDPROC no próprio TAPI. Quando o TAPI tem uma mensagem para entregar ao aplicativo, o TAPI posta uma mensagem na janela oculta. Quando a mensagem é recebida (o que só pode acontecer quando o aplicativo chama a função GetMessage do Windows), o Windows alterna o contexto do processo para o do aplicativo e invoca o WNDPROC no TAPI. Em seguida, o TAPI entrega a mensagem ao aplicativo chamando o phoneCallbackFunc, um ponteiro para o qual o aplicativo forneceu como um parâmetro em sua chamada para phoneInitializeEx (ou phoneInitialize, para aplicativos TAPI versão 1.3 e 1.4). Esse mecanismo exige que o aplicativo tenha uma fila de mensagens (que não é desejável para processos de serviço) e para atender a essa fila regularmente para evitar atrasar o processamento de eventos de telefonia. A janela oculta é destruída pelo TAPI durante a função phoneShutdown .
O mecanismo identificador de evento é selecionado especificando PHONEINITIALIZEEXOPTION_USEEVENT no membro dwOptions na estrutura PHONEINITIALIZEEXPARAMS. Nesse mecanismo, TAPI cria um objeto de evento em nome do aplicativo e retorna um identificador para o objeto no membro hEvent em PHONEINITIALIZEEXPARAMS. O aplicativo não deve manipular esse evento de nenhuma maneira (por exemplo, não deve chamar SetEvent, ResetEvent, CloseHandle e assim por diante) ou resultados de comportamento indefinidos; o aplicativo só pode aguardar esse evento usando funções como WaitForSingleObject ou MsgWaitForMultipleObjects. O TAPI sinaliza esse evento sempre que uma notificação de evento de telefonia está pendente para o aplicativo; o aplicativo deve chamar phoneGetMessage para buscar o conteúdo da mensagem. O evento é redefinido pelo TAPI quando nenhum evento está pendente. O identificador de evento é fechado e o objeto de evento destruído pelo TAPI durante a função phoneShutdown . O aplicativo não precisa aguardar o identificador de evento que é criado; em vez disso, o aplicativo pode optar por chamar phoneGetMessage e fazer com que ele bloqueie a espera de uma mensagem ser enfileirada.
O mecanismo porta de conclusão é selecionado especificando PHONEINITIALIZEEXOPTION_USECOMPLETION PORT no membro dwOptions na estrutura PHONEINITIALIZEEXPARAMS . Nesse mecanismo, sempre que um evento de telefonia precisar ser enviado para o aplicativo, o TAPI o enviará ao aplicativo usando PostQueuedCompletionStatus para a porta de conclusão especificada pelo aplicativo no membro hCompletionPort em PHONEINITIALIZEEXPARAMS, marcada com a chave de conclusão especificada pelo aplicativo no membro dwCompletionKey em PHONEINITIALIZEEXPARAMS. O aplicativo deve ter criado anteriormente a porta de conclusão usando CreateIoCompletionPort. Os aplicativos recuperam eventos usando GetQueuedCompletionStatus. Após o retorno de GetQueuedCompletionStatus, o aplicativo tem o dwCompletionKey especificado gravado no DWORD apontado pelo parâmetro lpCompletionKey e um ponteiro para uma estrutura PHONEMESSAGE retornado ao local apontado por lpOverlapped. Depois que o aplicativo tiver processado o evento, o aplicativo deverá chamar LocalFree para liberar a memória usada para conter a estrutura PHONEMESSAGE . Como o aplicativo criou a porta de conclusão (permitindo que ela seja compartilhada para outras finalidades), o aplicativo deve fechá-la; o aplicativo não deve fechar a porta de conclusão até depois de chamar phoneShutdown.

Quando um aplicativo multithread está usando o mecanismo de Identificador de Evento e mais de um thread está aguardando o identificador ou o mecanismo de notificação porta de conclusão e mais de um thread está aguardando na porta, é possível que os eventos de telefonia sejam processados fora de sequência. Isso não se deve à sequência de entrega de eventos do TAPI, mas seria causado pela divisão de tempo de threads ou pela execução de threads em processadores separados.

Se PHONEERR_REINIT for retornado e a reinicialização do TAPI tiver sido solicitada (por exemplo, como resultado da adição ou remoção de um provedor de serviços de telefonia), as solicitações phoneInitializeEx serão rejeitadas com esse erro até que o último aplicativo desligue o uso da API (usando phoneShutdown). Nesse momento, a nova configuração se torna eficaz e os aplicativos têm mais uma vez permissão para chamar phoneInitializeEx.

Se o valor de erro PHONEERR_INVALPARAM for retornado, o parâmetro hInstance especificado será inválido.

O aplicativo pode se referir a dispositivos de telefone individuais usando identificadores de dispositivo de telefone que variam de zero a dwNumDevs menos um. Um aplicativo não deve assumir que esses dispositivos de telefone são capazes de qualquer função TAPI específica sem primeiro consultar seus recursos de dispositivo por phoneGetDevCaps.

Observação

O cabeçalho tapi.h define phoneInitializeEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.