Função phoneInitialize (tapi.h)

Artigo
08/26/2023

A função phoneInitialize está obsoleta. Ele continua a ser exportado por Tapi.dll e Tapi32.dll para compatibilidade com versões anteriores com aplicativos que usam as versões TAPI 1.3 e 1.4.

Em vez disso, os aplicativos que usam TAPI versão 2.0 ou posterior devem usar phoneInitializeEx .

Para as versões 1.4 e anteriores do TAPI: A função phoneInitialize inicializa o uso do TAPI pelo aplicativo para o uso subsequente das funções de telefone na API de Telefonia. Ele registra o mecanismo de notificação especificado do aplicativo e retorna o número de dispositivos de telefone disponíveis para o aplicativo.

Sintaxe

LONG phoneInitialize(
  LPHPHONEAPP   lphPhoneApp,
  HINSTANCE     hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR        lpszAppName,
  LPDWORD       lpdwNumDevs
);

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.

lpfnCallback

Endereço de uma função de retorno de chamada que é invocada para determinar status e eventos no dispositivo de telefone.

lpszAppName

Ponteiro para uma cadeia de caracteres terminada em nulo que contém 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 é o proprietário atual do dispositivo de telefone. Essas informações podem ser úteis para fins de registro em log e relatório de status. Se lpszAppName for NULL, o nome do arquivo do aplicativo será usado.

lpdwNumDevs

Ponteiro para DWORD. Esse local é carregado com o número de dispositivos de telefone disponíveis para o aplicativo.

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_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_REINIT, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODEVICE, PHONEERR_NODRIVER, PHONEERR_INVALPARAM

Comentários

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 coisa além do que é especificado pelo subconjunto de Telefonia Assistida sem primeiro consultar seus recursos de dispositivo com a função phoneGetDevCaps .

Os aplicativos não devem invocar phoneInitialize sem abrir posteriormente um telefone (pelo menos para monitoramento). Se o aplicativo não estiver monitorando e não estiver usando nenhum dispositivo, ele deverá chamar phoneShutdown para que os recursos de memória alocados pelo TAPI possam ser liberados se desnecessários, e o próprio TAPI possa ser descarregado da memória enquanto não for necessário.

Outro motivo para executar um phoneShutdown é que, se um usuário alterar a configuração do dispositivo (adiciona ou remove uma linha ou telefone), não há como o TAPI notificar um aplicativo que tenha uma linha ou identificador de telefone aberto no momento. Depois que uma reconfiguração tiver ocorrido, fazendo com que uma mensagem de PHONESTATE_REINIT seja enviada, nenhum aplicativo poderá abrir um dispositivo até que todos os aplicativos tenham executado um phoneShutdown.

Se algum provedor de serviços não for inicializado corretamente, a função phoneInitialize falhará e retornará o erro indicado pelo provedor de serviços. Se o valor de erro PHONEERR_INVALPARAM for retornado, o parâmetro hInstance especificado será inválido.