Função lineInitialize (tapi.h)

Artigo
08/26/2023

A função lineInitialize 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 de API 1.3 e 1.4.

Os aplicativos que usam a API versão 2.0 ou posterior devem usar lineInitializeEx .

Para as versões 1.4 e Anteriores do TAPI: A função lineInitialize inicializa o uso do aplicativo de Tapi.dll para uso subsequente da abstração de linha. A função registra o mecanismo de notificação especificado do aplicativo e retorna o número de dispositivos de linha disponíveis para o aplicativo. Um dispositivo de linha é qualquer dispositivo que fornece uma implementação para as funções prefixadas por linha no TAPI.

Sintaxe

LONG lineInitialize(
  LPHLINEAPP   lphLineApp,
  HINSTANCE    hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR       lpszAppName,
  LPDWORD      lpdwNumDevs
);

Parâmetros

lphLineApp

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 linha, endereços ou chamadas. Para obter mais informações, consulte lineCallbackFunc.

lpszAppName

Ponteiro para uma cadeia de caracteres de texto 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 LINECALLINFO para indicar, de maneira amigável, qual aplicativo se originou ou originalmente aceitou ou atendeu à chamada. Essas informações podem ser úteis para fins de registro em log de chamadas. Se lpszAppName for NULL, o nome do arquivo do aplicativo será usado.

lpdwNumDevs

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

Valor retornado

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:

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NODRIVER, LINEERR_NODEVICE, LINEERR_NOMEM, LINEERR_NOMULTIPLEINSTANCE.

Comentários

Se LINEERR_REINIT for retornado e a reinicialização 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 lineInitialize serão rejeitadas com esse erro até que o último aplicativo desligue o uso da API (usando lineShutdown). Nesse momento, a nova configuração se torna eficaz e os aplicativos têm mais uma vez permissão para chamar lineInitialize. Se o valor de erro LINEERR_INVALPARAM for retornado, o parâmetro hInstance especificado será inválido.

O aplicativo pode se referir a dispositivos de linha individuais usando identificadores de dispositivo de linha que variam de zero a dwNumDevs menos um. Um aplicativo não deve assumir que esses dispositivos de linha são capazes de algo além do especificado pelo subconjunto de Telefonia Básica sem primeiro consultar seus recursos de dispositivo usando lineGetDevCaps e lineGetAddressCaps.

Os aplicativos não devem invocar lineInitialize sem abrir uma linha posteriormente (pelo menos para monitoramento). Se o aplicativo não estiver monitorando e não estiver usando nenhum dispositivo, ele deverá chamar lineShutdown para que os recursos de memória alocados por Tapi.dll possam ser liberados se desnecessários e Tapi.dll em si possam ser descarregados da memória enquanto não forem necessários.

Outro motivo para executar um lineShutdown é que, se um usuário alterar a configuração do dispositivo (adiciona ou remove uma linha ou telefone), não há como a TAPI notificar um aplicativo que tenha uma alça de telefone ou linha aberta no momento. Depois que uma reconfiguração tiver ocorrido, fazendo com que uma mensagem de LINEDEVSTATE_REINIT seja enviada, nenhum aplicativo poderá abrir um dispositivo até que todos os aplicativos tenham executado um lineShutdown. Se algum provedor de serviços não for inicializado corretamente, essa função falhará e retornará o erro indicado pelo provedor de serviços.

Em todas as plataformas TAPI, lineInitialize é equivalente a lineInitializeEx usando a opção LINEINITIALIZEEXOPTION_USEHIDDENWINDOW.