Função phoneInitializeExA (tapi.h)

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 podem 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 o status e os 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 um cadeia de caracteresterminada nula que contém apenas caracteres exibicionáveis. Se esse parâmetro não for NULL, ele conterá um nome fornecido pelo 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 do arquivo do módulo do aplicativo será usado em vez disso (conforme retornado pela função GetModuleFileName).

lpdwNumDevs

Ponteiro para umDWORD . 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 umDWORD . O aplicativo deve inicializar esse DWORD, antes de chamar essa função, para a versão mais alta da API que ele foi projetado para dar suporte (por exemplo, o mesmo valor que passaria para 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 de API mais alta com suporte da 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 contendo 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).

Valor de retorno

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

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

Observações

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 de de Janela Oculta é selecionado especificando PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW no membro dwOptions na estrutura PHONEINITIALIZEEXPARAMS . Nesse mecanismo (que é o único mecanismo disponível para o 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 o Windows função GetMessage), 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 (o 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 do Identificador de Eventos é 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 forma alguma (por exemplo, não deve chamar SetEvent, ResetEvent, CloseHandlee 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 é necessário para aguardar o identificador de evento que é criado; o aplicativo poderia optar por chamar phoneGetMessage e bloqueá-lo aguardando que uma mensagem seja enfileirada.
• O mecanismo de de 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 envia-o para o aplicativo usando PostQueuedCompletionStatus para a porta de conclusão especificada pelo aplicativo no membro hCompletionPort em PHONEINITIALIZEEXPARAMS, marcado 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 retornada para o 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 do Identificador de Eventos e mais de um thread está aguardando no identificador ou o mecanismo de notificação da Porta de Conclusão e mais de um thread está aguardando na porta, é possível que os eventos de telefonia sejam processados fora da sequência. Isso não se deve à sequência de entrega de eventos do TAPI, mas seria causado pelo intervalo 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), 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 phoneGetDevCaps.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
da Plataforma de Destino	Windows
cabeçalho	tapi.h
biblioteca	Tapi32.lib
de DLL	Tapi32.dll

Consulte também

PHONEINITIALIZEEXPARAMS

PHONEMESSAGE

PHONESTATUS

funções de serviço telefônico suplementar

visão geral de referência do TAPI 2.2

phoneCallbackFunc

phoneGetDevCaps

phoneGetMessage

phoneNegotiateAPIVersion

phoneShutdown