função TSPI_providerRemove (tspi.h)

Artigo
03/13/2024

A função TSPI_providerRemove está obsoleta. Os provedores de serviços TAPI versão 1.4 ou anteriores podem implementar essa função TSPI. Os TSPs tapi versão 2.0 ou posterior implementam TUISPI_providerRemove.

A função TSPI_providerRemove solicita que o usuário confirme a eliminação do provedor de serviços. É responsabilidade do provedor de serviços remover todas as entradas do Registro que o provedor de serviços adicionou no momento addProvider , bem como quaisquer outros módulos e arquivos que não são mais necessários.

Sintaxe

LONG TSPIAPI TSPI_providerRemove(
  HWND  hwndOwner,
  DWORD dwPermanentProviderID
);

Parâmetros

hwndOwner

O identificador da janela pai na qual a função pode criar qualquer janela de caixa de diálogo necessária durante a remoção.

dwPermanentProviderID

O identificador de provedor permanente do provedor de serviços.

Retornar valor

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_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_NOMEM, LINEERR_INVALPARAM.

Comentários

Essa função deve garantir que a seção do provedor de serviços e as informações definidas de modo privado para o provedor de serviços sejam removidas do registro se retornarem êxito. Em particular, a seção [PROVIDER<PPID>] cujo <PPID> corresponde a dwPermanentProviderID deve ser removida, incluindo suas entradas NumLines e NumPhones . Se a função retornar êxito, é responsabilidade do chamador remover as entradas ProviderIDx e ProviderFilenamex correspondentes da seção [Provedores] e renumerar as entradas restantes na seção [Provedores] adequadamente.

Esse procedimento deve deixar o sistema em um estado consistente. Ele deve ser executado até a conclusão, não permitindo que o usuário anule a remoção quando ela for parcialmente concluída. Se a remoção falhar, é responsabilidade do provedor "recuar" o que foi feito e retornar um erro. Isso pode implicar a pré-verificação para verificar se uma remoção completa é possível, antes do início da remoção.

Essa função pode ser chamada enquanto o provedor de serviços está em uso (ou seja, entre TSPI_providerInit e TSPI_providerShutdown). Se isso acontecer, o provedor de serviços deverá fazer uma combinação apropriada de exibir uma caixa de diálogo do usuário para anunciar qualquer conflito e confirmar a remoção, restringindo as opções de remoção para aqueles que podem ser executados de forma transparente ou emitindo mensagens LINE_CLOSE e PHONE_CLOSE para informar ao TAPI e aos aplicativos que os dispositivos afetados foram fechados à força para remoção. De qualquer forma, todas as alterações que afetam o comportamento visível por meio do TSPI devem entrar em vigor somente quando o provedor de serviços for desligado no próximo TSPI_providerShutdown.

Essa função não deve retornar LINEERR_INUSE ou outros erros que possam ocorrer porque o provedor está em uso por um aplicativo; Em vez disso, o provedor deve conferir ao usuário diretamente sobre esse problema e, em seguida, retornar LINEERR_OPERATIONFAILED se o usuário decidir anular a operação.

Esse procedimento é chamado apenas uma vez, no momento da remoção do provedor de serviços, até que haja uma chamada para TSPI_providerInstall. É responsabilidade do chamador garantir isso.

O utilitário Painel de Controle telefonia fornecido com o Windows Telephony nas versões 1.4 e anteriores chama essa função (com requisitos de sequência externos atendidos conforme descrito aqui) quando o comando "remove" é invocado.

Não há nenhuma função correspondente no nível tapi. Nesse nível, os aplicativos esperam ter provedores de serviços já instalados; caso contrário, suas linhas e telefones não aparecem dentro da sequência disponível de identificadores de dispositivo. Os aplicativos em execução são informados sobre a reconfiguração dinâmica, incluindo a remoção de provedores de serviços, por meio do valor LINEDEVSTATE_REINIT ou PHONESTATE_REINIT na mensagem LINE_LINEDEVSTATE ou PHONE_STATE.