Função WSCInstallProviderAndChains (ws2spi.h)
Observação
Os Provedores de Serviços em Camadas foram preteridos. Começando com Windows 8 e Windows Server 2012, use a Plataforma de Filtragem do Windows. A função WSCInstallProviderAndChains instala o provedor de transporte de 32 bits especificado, bem como suas cadeias de protocolo específicas no banco de dados de configuração do sistema Winsock 2 em um computador de 32 bits. Essa função garante que as cadeias de protocolo sejam ordenadas no início das informações de configuração do provedor de transporte, garantindo que uma chamada separada para WSCWriteProviderOrder não seja necessária.
Sintaxe
int WSCInstallProviderAndChains(
[in] LPGUID lpProviderId,
[in] const LPWSTR lpszProviderDllPath,
[in] const LPWSTR lpszLspName,
[in] DWORD dwServiceFlags,
[in] LPWSAPROTOCOL_INFOW lpProtocolInfoList,
[in] DWORD dwNumberOfEntries,
[out, optional] LPDWORD lpdwCatalogEntryId,
[out] LPINT lpErrno
);
Parâmetros
[in] lpProviderId
Um ponteiro para um GUID (identificador global exclusivo) específico do provedor.
[in] lpszProviderDllPath
Um ponteiro para uma cadeia de caracteres Unicode que contém o caminho de carga para a DLL do provedor. Essa cadeia de caracteres observa as regras usuais para resolução de caminho e pode conter cadeias de caracteres de ambiente inseridas (%SystemRoot%, por exemplo). Essas cadeias de caracteres de ambiente são expandidas sempre que Ws2_32.dll posteriormente carrega a DLL do provedor em nome de um aplicativo. Depois que qualquer cadeia de caracteres de ambiente inserida for expandida, Ws2_32.dll passa a cadeia de caracteres resultante para a função LoadLibrary para carregar o provedor na memória. Para obter mais informações, consulte LoadLibrary.
[in] lpszLspName
Um ponteiro para uma cadeia de caracteres Unicode que contém o nome do provedor de soquete.
[in] dwServiceFlags
Os sinalizadores de serviço para o tipo de entrada de catálogo "fictício" a ser criado.
Uma entrada fictícia é uma estrutura WSAProtocol_Info com o membro ChainLen definido como 0. A entrada de catálogo LSP real fará referência à ID dessa entrada fictícia em seu membro ProtocolChain .
Os possíveis sinalizadores que podem ser definidos para esse parâmetro são os seguintes:
[in] lpProtocolInfoList
Um ponteiro para uma matriz de estruturas WSAProtocol_Info . Cada estrutura define um protocolo, família de endereços e tipo de soquete com suporte do provedor. Os membros da estrutura WSAPROTOCOL_INFO que são examinados são iProtocol, iAddressFamily e iSocketType.
[in] dwNumberOfEntries
O número de entradas na matriz lpProtocolInfoList .
[out, optional] lpdwCatalogEntryId
Recebe um ponteiro para a entrada "fictícia" recém-instalada para o provedor de transporte no banco de dados de configuração do sistema Winsock 2. Essa ID é usada para instalar as entradas de catálogo para o LSP.
[out] lpErrno
Um ponteiro que recebe um código de erro gerado pela chamada se a função falhar.
Retornar valor
If
WSCInstallProviderAndChains é bem-sucedido, ele retorna zero. Caso contrário, ele retornará SOCKET_ERROR e um código de erro específico será retornado no parâmetro lpErrno .
| Código do erro | Significado |
|---|---|
| Um ou mais argumentos não estão em uma parte válida do espaço de endereço do usuário. | |
| Um ou mais argumentos são inválidos. Esse erro é retornado para as seguintes condições: o parâmetro lpProviderId é **NULL**, o parâmetro lpszProviderDllPath é inválido ou o comprimento do caminho é muito grande (**MAX_PATH** foi excedido), o parâmetro lpszLspName é inválido ou o comprimento do nome é muito grande (**WSAPROTOCOL_LEN** é excedido), o lpProtocolInfoList é definido como um non-**NULL** e dwNumberOfEntries O parâmetro é zero, uma ID de provedor duplicada ou o nome do provedor de serviços em camadas já existe no catálogo ou uma correspondência não pode ser encontrada para o protocolo, a família de endereços e o tipo de soquete especificados. | |
| Uma instalação do provedor já está em andamento. | |
| O provedor não tem a funcionalidade necessária. | |
| A memória não pode ser alocada para buffers. | |
| Ocorreu um erro não recuperável. Esse erro é retornado em várias condições, incluindo o seguinte: o provedor já está instalado, o parâmetro lpProtocolInfoList era **NULL** e não foi encontrado nenhum provedor base, o comprimento máximo da cadeia de protocolo (**MAX_PROTOCOL_CHAIN**) foi atingido, o usuário não tem os privilégios administrativos necessários para gravar no registro winsock ou ocorreu uma falha ao criar ou instalar uma entrada de catálogo. | |
| Falha em uma chamada do sistema que nunca deve falhar. |
Comentários
WSCInstallProviderAndChains é uma versão aprimorada da função básica WSCInstallProvider usada para instalar um único provedor de serviços de transporte. Se um provedor de serviços em camadas estiver sendo instalado, o WSCInstallProviderAndChains deverá ser usado. WSCInstallProviderAndChains pode instalar um protocolo em camadas e uma ou mais cadeias de protocolo com uma única chamada de função. Para realizar o mesmo trabalho usando O WSCInstallProvider exigiria várias chamadas de função.
O Winsock 2 acomoda protocolos em camadas. Um protocolo em camadas é aquele que implementa apenas funções de comunicação de nível mais alto, ao mesmo tempo em que depende de uma pilha de transporte subjacente para a troca real de dados com um ponto de extremidade remoto. Um exemplo de um protocolo em camadas seria uma camada de segurança que adiciona um protocolo ao processo de estabelecimento de conexão para executar a autenticação e estabelecer um esquema de criptografia mutuamente acordado. Esse protocolo de segurança geralmente exigiria os serviços de um protocolo de transporte confiável subjacente, como TCP ou SPX. O termo protocolo base refere-se a um protocolo como TCP ou SPX que é capaz de executar comunicações de dados com um ponto de extremidade remoto. O termo protocolo em camadas é usado para descrever um protocolo que não pode ficar sozinho. Uma cadeia de protocolos seria definida como um ou mais protocolos em camadas amarrados e ancorados por um protocolo base. Um protocolo base tem o membro ChainLen da estrutura WSAProtocol_Info definido como BASE_PROTOCOL que é definido como 1. Um protocolo em camadas tem o membro ChainLen da estrutura WSAPROTOCOL_INFO definido como LAYERED_PROTOCOL que é definido como zero. Uma cadeia de protocolos tem o membro ChainLen da estrutura WSAPROTOCOL_INFO definido como maior que 1.
Se lpProtocolInfoList for definido como NULL, essa função criará cadeias de protocolo em que o provedor está em camadas sobre o protocolo base para cada tipo de protocolo exclusivo, conforme definido pela família de endereços, tipo de soquete e protocolo. Isso elimina a criação de entradas de provedor duplicadas inacessíveis.
Se lpProtocolInfoList for definido como um valor não NULL , essa função criará cadeias de protocolo obtendo a entrada mais alta nas informações de configuração que correspondem à família de endereços, ao tipo de soquete e ao protocolo de cada elemento na matriz fornecida. Novamente, somente a família de endereços, o tipo de soquete e o protocolo são considerados; todos os outros membros e duplicatas são ignorados.
Após a conclusão bem-sucedida dessa chamada, todas as chamadas subsequentes para WSAEnumProtocols ou WSCEnumProtocols retornarão as entradas de cadeia de protocolo recém-criadas. Lembre-se de que, em ambientes windows, somente instâncias de Ws_32.dll criadas chamando WSAStartup após a conclusão bem-sucedida de WSCInstallProviderAndChains incluirão as novas entradas quando WSAEnumProtocols e WSCEnumProtocols retornarem.
Em caso de êxito, WSCInstallProviderAndChains tentará alertar todos os aplicativos interessados que se registraram para notificação da alteração chamando WSAProviderConfigChange.
A função WSCInstallProviderAndChains só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se WSCInstallProviderAndChains for chamado por um usuário que não é membro do grupo Administradores, a chamada de função falhará e WSANO_RECOVERY será retornado no parâmetro lpErrno . Para computadores que executam o Windows Vista ou o Windows Server 2008, essa função também pode falhar devido ao UAC (controle de conta de usuário). Se um aplicativo que contém essa função for executado por um usuário conectado como um membro do grupo Administradores diferente do Administrador interno, essa chamada falhará, a menos que o aplicativo tenha sido marcado no arquivo de manifesto com um requestedExecutionLevel definido como requireAdministrator. Se o aplicativo no Windows Vista ou no Windows Server 2008 não tiver esse arquivo de manifesto, um usuário conectado como membro do grupo Administradores que não seja o Administrador interno deverá executar o aplicativo em um shell aprimorado como administrador interno (administrador RunAs) para que essa função tenha êxito.
Qualquer instalação de arquivo ou configuração específica do provedor deve ser executada pelo aplicativo de chamada.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | ws2spi.h |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |
Confira também
Configuração e instalação do transporte