Função WSCUpdateProvider (ws2spi.h)

Artigo
08/28/2023

A função WSCUpdateProvider modifica o provedor de transporte especificado no banco de dados de configuração do sistema.

Sintaxe

int WSCUpdateProvider(
  [in]  LPGUID                    lpProviderId,
  [in]  const WCHAR               *lpszProviderDllPath,
  [in]  const LPWSAPROTOCOL_INFOW lpProtocolInfoList,
  [in]  DWORD                     dwNumberOfEntries,
  [out] LPINT                     lpErrno
);

Parâmetros

[in] lpProviderId

Um ponteiro para um GUID (identificador global exclusivo) para o provedor.

[in] lpszProviderDllPath

Um ponteiro para uma cadeia de caracteres Unicode que contém o caminho de carga para a DLL de 64 bits do provedor. Essa cadeia de caracteres observa as regras usuais para resolução de caminho e pode conter cadeias de caracteres de ambiente inseridas (como %SystemRoot%). Essas cadeias de caracteres de ambiente são expandidas quando o Ws2_32.dll deve carregar posteriormente a DLL do provedor em nome de um aplicativo. Depois que as cadeias de caracteres de ambiente inseridas são expandidas, o Ws2_32.dll passa a cadeia de caracteres resultante para a função LoadLibrary que carrega o provedor na memória. Para obter mais informações, consulte LoadLibrary.

[in] lpProtocolInfoList

Um ponteiro para uma matriz de estruturas de WSAProtocol_Info . Cada estrutura especifica ou modifica um protocolo, uma família de endereços e um tipo de soquete com suporte do provedor.

[in] dwNumberOfEntries

O número de entradas na matriz lpProtocolInfoList .

[out] lpErrno

Um ponteiro para o código de erro se a função falhar.

Valor retornado

Se nenhum erro ocorrer, WSCUpdateProvider retornará 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
WSAEFAULT	Um ou mais argumentos não estão em uma parte válida do espaço de endereço do usuário.
WSAEINVAL	Um ou mais argumentos são inválidos.
WSANO_RECOVERY	Ocorreu um erro não detectável. Esse erro é retornado sob várias condições, incluindo o seguinte: o usuário não tem os privilégios administrativos necessários para gravar no registro winsock ou ocorreu uma falha ao abrir ou gravar uma entrada de catálogo.
WSA_NOT_ENOUGH_MEMORY	Memória insuficiente disponível. Esse erro é retornado quando não há memória suficiente para alocar uma nova entrada de catálogo.

Comentários

A função WSCUpdateProvider modifica as informações de configuração do Windows Sockets 2 para o provedor especificado. Ela é aplicável a protocolos base, protocolos em camadas e cadeias de protocolo.

Winsock 2 acomoda protocolos em camadas. Um protocolo em camadas é aquele que implementa apenas funções de comunicação de nível mais alto, enquanto 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 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. Em seguida, 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.

Com êxito, o WSCUpdateProvider tentará alertar todos os aplicativos interessados que se registraram para notificação da alteração chamando WSAProviderConfigChange.

A função WSCUpdateProvider só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se WSCUpdateProvider for chamado por um usuário que não é membro do grupo Administradores, a chamada de função falhará.

Para computadores em execução no Windows Vista ou no 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 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 para exigirAdministrator. 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 avançado como administrador interno (administrador de RunAs) para que essa função tenha êxito.

Qualquer instalação de arquivo ou configuração específica do provedor de serviços deve ser executada pelo chamador.

Requisitos


Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ws2spi.h
Biblioteca	Ws2_32.lib
DLL	Ws2_32.dll