função TSPI_providerInit (tspi.h)

Artigo
08/26/2023

A função TSPI_providerInit inicializa o provedor de serviços e fornece os parâmetros necessários para operações subsequentes.

Sintaxe

LONG TSPIAPI TSPI_providerInit(
  DWORD            dwTSPIVersion,
  DWORD            dwPermanentProviderID,
  DWORD            dwLineDeviceIDBase,
  DWORD            dwPhoneDeviceIDBase,
  DWORD_PTR        dwNumLines,
  DWORD_PTR        dwNumPhones,
  ASYNC_COMPLETION lpfnCompletionProc,
  LPDWORD          lpdwTSPIOptions
);

Parâmetros

dwTSPIVersion

A versão da definição de TSPI sob a qual essa função deve operar. O chamador pode usar TSPI_lineNegotiateTSPIVersion com a INITIALIZE_NEGOTIATIONdwDeviceID especial para negociar uma versão que tem a garantia de ser aceitável para o provedor de serviços.

dwPermanentProviderID

O identificador permanente, exclusivo dentro dos provedores de serviços nesse sistema, do provedor de serviços que está sendo inicializado.

dwLineDeviceIDBase

O identificador de dispositivo mais baixo para os dispositivos de linha compatíveis com esse provedor de serviços.

dwPhoneDeviceIDBase

O identificador de dispositivo mais baixo para os dispositivos de telefone compatíveis com esse provedor de serviços.

dwNumLines

O número de dispositivos de linha compatíveis com esse provedor de serviços. O valor retornado é o número de dispositivos de linha relatados em TSPI_providerEnumDevices.

dwNumPhones

O número de dispositivos de telefone aos quais esse provedor de serviços dá suporte. O valor retornado é o número de dispositivos de telefone relatados em TSPI_providerEnumDevices.

lpfnCompletionProc

O procedimento que o provedor de serviços chama para relatar a conclusão de todos os procedimentos operacionais de forma assíncrona em dispositivos de linha e telefone.

lpdwTSPIOptions

Um ponteiro para um local de memória do tamanho DWORD, no qual o provedor de serviços pode gravar um valor especificando valores LINETSPIOPTIONS_. Esse parâmetro permite que o provedor de serviços retorne bits indicando comportamentos opcionais desejados do TAPI. O TAPI define as opções DWORD como 0 antes de chamar TSPI_providerInit, portanto, se o provedor de serviços não quiser nenhuma dessas opções, ele poderá simplesmente deixar o DWORD definido como 0.

Neste momento, apenas um bit é definido para ser retornado por meio deste ponteiro: LINETSPIOPTION_NONREENTRANT. O provedor de serviços define esse bit se ele não for projetado para uma operação totalmente preemptiva, multithreaded, multitarefa, multiprocessador (por exemplo, atualização de dados globais protegidos por mutexes). Quando esse bit é definido, o TAPI faz apenas uma chamada de cada vez para o provedor de serviços; ele não chama nenhum outro ponto de entrada, nem esse ponto de entrada novamente, até que o provedor de serviços retorne da chamada de função original. Sem esse conjunto de bits, o TAPI pode chamar vários pontos de entrada do provedor de serviços, incluindo várias vezes para o mesmo ponto de entrada, simultaneamente (na verdade, simultaneamente em um sistema multiprocessador).

ObservaçãoImportante: é necessário enfatizar que a configuração desse bit degrada o desempenho. É altamente recomendável que isso seja usado apenas para desenvolvimento, mas não para um provedor de serviços de produção enviado.

O TAPI não serializa o acesso a funções TSPI que exibem uma caixa de diálogo ( TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall TUISPI_providerRemove) para que não bloqueiem a chamada de outras funções TSPI; o provedor de serviços deve incluir proteção interna nessas funções.

Valor retornado

Retornará zero se a função for bem-sucedida ou um número de erro se ocorrer um erro. Os valores retornados possíveis são os seguintes:

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT, LINEERR_NOMULTIPLEINSTANCE.

Comentários

Essa função é garantida para ser chamada antes de qualquer uma das outras funções prefixadas com TSPI_line ou TSPI_phone , exceto TSPI_lineNegotiateTSPIVersion. Ele é estritamente emparelhado com uma chamada subsequente para TSPI_providerShutdown Esses pares podem se sobrepor, por exemplo, quando o utilitário de telefonia Painel de Controle fornecido com a Telefonia do Windows nas versões 1.4 e anteriores é usado enquanto as operações de telefonia estão em andamento. A chamada para essa função deverá ser ignorada (retornando êxito) se já houver um par pendente.

Um provedor de serviços deve executar quantas verificações de consistência forem práticas no momento. TSPI_providerInit é chamado para garantir que ele esteja pronto para ser executado. Alguns erros de consistência ou instalação, no entanto, não podem ser detectados até que a operação seja tentada. O erro LINEERR_NODRIVER pode ser usado para relatar esses erros não específicos no momento em que são detectados.

Não há nenhuma função diretamente correspondente no nível tapi. Nesse nível, várias instâncias de uso diferentes podem ser pendentes, com um "identificador de aplicativo" retornado para identificar a instância em operações subsequentes. No nível do TSPI, a arquitetura de interface dá suporte apenas a uma única instância de uso para cada provedor de serviços distinto.