lineInitializeEx

9/19/2008

Essa função inicializa uso do aplicativo de TAPI para uso subseqüente de abstração de linha. Ele registra Mecanismo do aplicativo notificação especificada e retorna o número da linha de dispositivos disponível para o aplicativo. Um dispositivo de linha é qualquer dispositivo que fornece uma implementação para as funções line-prefixed na Telephony API.

Syntax

LONG WINAPI lineInitializeEx(
  LPHLINEAPP lphLineApp,
  HINSTANCE hInstance,
  LINECALLBACK lpfnCallback,
  LPCWSTR lpszFriendlyAppName,
  LPDWORD lpdwNumDevs,
  LPDWORD lpdwAPIVersion,
  LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);

Parameters

• lphLineApp
  Ponteiro para uma localidade que é preenchida com identificador de uso do aplicativo para TAPI.

• hInstance
  Identificador de instância do aplicativo cliente ou DLL. O aplicativo ou DLL pode transmitir NULL para esse parâmetro, na qual maiúsculas e minúsculas TAPI usa o identificador módulo do executável a raiz do processo (para fins de identificação prioridades modo destinos e mídia entrega chamar).

• lpfnCallback
  Endereço de uma função callback que é chamado para determinar status e Eventos no dispositivo de linha, endereços ou chamadas, quando o aplicativo está usando o método janela oculta do evento notificação (para obter mais informações consulte lineCallbackFunc). Este parâmetro é ignorado e deverá ser definido para NULL quando o aplicativo opta por usar o evento identificador evento notificação mecanismo.

• lpszFriendlyAppName
  Ponteiro para uma seqüência de caracteres NULL-Terminated texto contendo caracteres somente exibível. Se este parâmetro não for NULL, ele contém um nome aplicativo-fornecido para o aplicativo. Esse nome é fornecido na LINECALLINFO estrutura para indicar, em um amigável maneira, qual aplicativo se originou, originalmente aceito ou respondidas a chamar. Este informações podem ser útil para chamar-log fins. Se lpszFriendlyAppName é NULL, módulo arquivo Nome do aplicativo é usado em vez disso (como retornado pela Windows API GetModuleFileName).

• lpdwNumDevs
  Ponteiro para um DWORD-Tamanho localidade. Após bem-sucedido conclusão essa solicitação, esta localidade é preenchido com o número de dispositivos de linha disponível para o aplicativo.

• lpdwAPIVersion
  Ponteiro para um DWORD-Tamanho localidade. O aplicativo deve inicializar este DWORD, antes chamado essa função, para a versão mais alto API ele foi projetado para suporte (de exemplo, o mesmo valor que teria transmitir para o dwAPIHighVersion parâmetro da lineNegotiateAPIVersion função). Valores artificialmente altos não devem ser usados; o valor deve ser definida com precisão. TAPI converte as mensagens mais recentes ou estruturas em valores ou formatos com suporte pela versão do aplicativo. Após bem-sucedido conclusão essa solicitação, esta localidade é preenchida com a versão mais alto API com suporte, TAPI, permitindo o aplicativo para detecção e adaptar ter sido instalado em um sistema com uma versão diferente de TAPI.

• lpLineInitializeExParams
  Ponteiro para uma estrutura de tipo LINEINITIALIZEEXPARAMS contendo parâmetros adicionais usados para estabelecer a associação entre o aplicativo e TAPI (especificamente, do o aplicativo evento selecionado notificação mecanismo e associado parâmetros).

Return Value

Zero indica sucesso. Um número de erro negativa indica que ocorreu um erro. A seguinte tabela mostra os valores de retorno para esta função.

Valor	Descrição
LINEERR_INVALAPPNAME	Nome do aplicativo inválido
LINEERR_OPERATIONFAILED	A operação falhou
LINEERR_INIFILECORRUPT	O arquivo INI é corrompido
LINEERR_INVALPOINTER	Ponteiro inválido
LINEERR_REINIT	O aplicativo tentado inicializar TAPI duas vezes.
LINEERR_NOMEM	Não há memória disponível
LINEERR_INVALPARAM	Parâmetro inválido

Remarks

Aplicativos devem selecionar um dos dois mecanismos pelo qual TAPI notifica o aplicativo de telefonia eventos: Oculto da janela ou identificador de eventos.

O mecanismo Windows ocultos é selecionado por especificando LINEINITIALIZEEXOPTION_USEHIDDENWINDOW in a dwOptions membro na estrutura de LINEINITIALIZEEXPARAMS. Nesse mecanismo (que é o único mecanismo disponível para aplicativos 1.x TAPI), TAPI cria uma janela no contexto do aplicativo durante a lineInitializeEx Ou lineInitialize (Para TAPI 1.3 e aplicativos 1.4) função e as subclasses de janela para que todas as mensagens postadas ele sejam manipuladas por um WNDPROC em TAPI próprio. Quando uma mensagem entregar o aplicativo tem TAPI, TAPI remete uma mensagem para a janela oculta. Quando a mensagem é recebida (que pode ocorrer apenas quando o aplicativo chama o Windows GetMessage função), Windows alterna o contexto processo para que o aplicativo e chama o WNDPROC em TAPI. TAPI, em seguida, envia a mensagem para o aplicativo por chamado de lineCallbackFunc, um ponteiro para o qual o aplicativo fornecido como um parâmetro no seu chamar para lineInitializeEx (ou lineInitialize). Esse mecanismo requer o aplicativo para ter uma fila de mensagens (que não é desejável para processos serviço) e ao serviço que fila regularmente para evitar atrasar processamento de telefonia eventos. A janela oculta é destruída por TAPI durante a lineShutdown função.

O mecanismo de identificador de eventos é selecionado por especificando LINEINITIALIZEEXOPTION_USEEVENT in a dwOptions membro in a LINEINITIALIZEEXPARAMS estrutura. Nesse mecanismo, TAPI cria um objeto evento on Behalf Of o aplicativo e retorna um identificador para o objeto na hEvent membro no LINEINITIALIZEEXPARAMS. O aplicativo não deve manipular esse evento de qualquer maneira (de exemplo, deve não chamar o SetEvent, ResetEvent, e CloseHandle funções) ou indefinido comportamento resultados; o aplicativo só pode esperar sobre este evento usando funções such as WaitForSingleObject Ou MsgWaitForMultipleObjects. TAPI sinais este evento sempre que uma notificação evento telefonia está pendente para o aplicativo; o aplicativo deve chamar o lineGetMessage função para buscar o conteúdo de mensagem. O evento é redefinir por TAPI quando nenhuma eventos estão pendente. Identificador de evento é fechada e o objeto evento destruídos por TAPI durante a lineShutdown função. O aplicativo não é exigido para aguardar no identificador de evento que é criado; o aplicativo poderia escolher em vez disso, para chamar lineGetMessage e ainda bloco aguardando uma mensagem seja enfileirado.

Se o valor de erro LINEERR_INVALPARAM for retornado, especificado hInstance parâmetro é inválido.

O aplicativo pode referir ao individual linha dispositivos usando identificadores dispositivo de linha desse intervalo de zero para dwNumDevs menos um. Um aplicativo não deve presumir que esses dispositivos de linha são capazes de qualquer função TAPI específica sem primeiro consultar suas capacidades dispositivo usando o lineGetDevCaps função.

Requirements

Header	tapi.h
Library	coredll.lib
Windows Embedded CE	Windows CE 3.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

See Also

Reference

lineCallbackFunc
lineCallbackFunc
lineGetDevCaps
lineGetMessage
lineInitialize
lineNegotiateAPIVersion
lineShutdown
LINECALLINFO
LINEINITIALIZEEXPARAMS
LINEMESSAGE

Other Resources

CloseHandle
GetModuleFileName
ResetEvent
SetEvent
WaitForSingleObject