Função lineInitializeExA (tapi.h)

Artigo
03/08/2023

A função lineInitializeEx inicializa o uso do TAPI pelo aplicativo para o uso subsequente da abstração de linha. Ele 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 de linha na API de Telefonia.

Sintaxe

LONG lineInitializeExA(
  LPHLINEAPP               lphLineApp,
  HINSTANCE                hInstance,
  LINECALLBACK             lpfnCallback,
  LPCSTR                   lpszFriendlyAppName,
  LPDWORD                  lpdwNumDevs,
  LPDWORD                  lpdwAPIVersion,
  LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);

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. 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 (para fins de identificação de destinos de entrega de chamada e prioridades do modo de mídia).

lpfnCallback

Endereço de uma função de retorno de chamada invocada para determinar status e eventos no dispositivo de linha, endereços ou chamadas, quando o aplicativo estiver usando o método de notificação de evento "janela oculta" (para obter mais informações, consulte lineCallbackFunc). 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 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 lpszFriendlyAppName for NULL, o nome do arquivo de módulo do aplicativo será usado em vez disso (conforme retornado pela função GetModuleFileName).

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.

lpdwAPIVersion

Ponteiro para um local do tamanho DWORD. 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 o parâmetro dwAPIHighVersion de lineNegotiateAPIVersion). 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 da TAPI, permitindo assim que o aplicativo detecte e se adapte a ter sido instalado em um sistema com uma versão diferente do TAPI.

lpLineInitializeExParams

Ponteiro para uma estrutura do tipo LINEINITIALIZEEXPARAMS 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 possíveis valores retornados são:

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_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 LINEINITIALIZEEXOPTION_USEHIDDENWINDOW no membro dwOptions na estrutura LINEINITIALIZEEXPARAMS . 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 lineInitializeEx ou lineInitialize (para aplicativos TAPI versão 1.3 e 1.4) 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 lineCallbackProc, um ponteiro para o qual o aplicativo forneceu como um parâmetro em sua chamada para lineInitializeEx (ou lineInitialize). 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 lineShutdown .

O mecanismo do Identificador de Eventos é selecionado especificando LINEINITIALIZEEXOPTION_USEEVENT no membro dwOptions na estrutura LINEINITIALIZEEXPARAMS . Nesse mecanismo, TAPI cria um objeto de evento em nome do aplicativo e retorna um identificador para o objeto no membro hEvent em LINEINITIALIZEEXPARAMS. O aplicativo não deve manipular esse evento de forma alguma (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 lineGetMessage 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 lineShutdown . O aplicativo não é necessário para aguardar o identificador de evento que é criado; o aplicativo poderia optar por chamar lineGetMessage e bloqueá-lo aguardando uma mensagem ser enfileirada.

O mecanismo porta de conclusão é selecionado especificando LINEINITIALIZEEXOPTION_USECOMPLETION PORT no membro dwOptions na estrutura LINEINITIALIZEEXPARAMS . Nesse mecanismo, sempre que um evento de telefonia precisar ser enviado para o aplicativo, TAPI o envia usando PostQueuedCompletionStatus para a porta de conclusão especificada pelo aplicativo no membro hCompletionPort em LINEINITIALIZEEXPARAMS, marcada com a chave de conclusão especificada pelo aplicativo no membro dwCompletionKey em LINEINITIALIZEEXPARAMS. O aplicativo deve ter criado anteriormente a porta de conclusão usando CreateIoCompletionPort. O aplicativo recupera 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 LINEMESSAGE retornada ao local apontado por lpOverlapped. Depois que o aplicativo processar o evento, é responsabilidade do aplicativo chamar LocalFree para liberar a memória usada para conter a estrutura LINEMESSAGE . Como o aplicativo criou a porta de conclusão (permitindo assim 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 lineShutdown.

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 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 corte de tempo de threads ou pela execução de threads em processadores separados.

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 lineInitializeEx serão rejeitadas com esse erro até que o último aplicativo desligue o uso da API (usando lineShutdown), momento em que a nova configuração se torna eficaz e os aplicativos são novamente autorizados a chamar lineInitializeEx.

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 qualquer função TAPI específica sem primeiro consultar seus recursos de dispositivo por lineGetDevCaps e lineGetAddressCaps.

Observação

O cabeçalho tapi.h define lineInitializeEx 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.