Função lineInitializeExA (tapi.h)

A função lineInitializeEx inicializa o uso do TAPI pelo aplicativo para 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 por 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 de modo de mídia).

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 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 um cadeia de caracteres de textoterminada em nulo que contém apenas caracteres exibiveis. Se esse parâmetro não for NULL, ele conterá um nome fornecido pelo aplicativo. Esse nome é fornecido na estrutura LINECALLINFO para indicar, de forma 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 deDWORD . 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 deDWORD . 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 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 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 diferente do TAPI.

lpLineInitializeExParams

Ponteiro para uma estrutura do tipo LINEINITIALIZEEXPARAMS 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:

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM, LINEERR_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 janela oculta é selecionado especificando LINEINITIALIZEEXOPTION_USEHIDDENWINDOW no membro dwOptions na estrutura de 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 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 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 de 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, 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 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 pela 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 que uma mensagem seja enfileirada.

O mecanismo porta de conclusão é selecionado especificando LINEINITIALIZEEXOPTION_USECOMPLETION PORT no membro dwOptions na estrutura de LINEINITIALIZEEXPARAMS. Nesse mecanismo, sempre que um evento de telefonia precisar ser enviado para o aplicativo, O TAPI envia-o usando PostQueuedCompletionStatus para a porta de conclusão especificada pelo aplicativo no membro hCompletionPort em LINEINITIALIZEEXPARAMS, marcado com a chave de conclusão especificada 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 para o local apontado por lpOverlapped. Depois que o aplicativo tiver processado o evento, é responsabilidade do aplicativo chamar LocalFree para liberar a memória usada para conter a estrutura de LINEMESSAGE. 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 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 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 LINEERR_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 lineInitializeEx sã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 do 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 lineGetDevCaps e lineGetAddressCaps.

Nota

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 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

Referência dos Serviços básicos de telefonia

LINECALLINFO

LINEINITIALIZEEXPARAMS

LINEMESSAGE

visão geral de referência do TAPI 2.2

lineCallbackFunc

lineGetAddressCaps

lineGetDevCaps

lineGetMessage

lineInitialize

lineNegotiateAPIVersion

lineShutdown