Função WSCWriteNameSpaceOrder32 (sporder.h)

Artigo
08/26/2023

A função WSCWriteNameSpaceOrder32 altera a ordem dos provedores de namespace do Windows Sockets (Winsock) 2 disponíveis em um catálogo de 32 bits. A ordem dos provedores de namespace determina a prioridade do namespace quando enumerado ou consultado para resolução de nomes.

Nota Essa chamada é uma versão estritamente de 32 bits do WSCWriteNameSpaceOrder para uso em plataformas de 64 bits. Ele é fornecido para permitir que processos de 64 bits reordenem o catálogo do provedor de namespace de 32 bits.

Sintaxe

int WSCWriteNameSpaceOrder32(
  [in] LPGUID lpProviderId,
  [in] DWORD  dwNumberOfEntries
);

Parâmetros

[in] lpProviderId

Uma matriz de elementos NSProviderId , conforme encontrado na estrutura WSANAMESPACE_INFO . A ordem dos elementos NSProviderId é a nova ordenação de prioridade para os provedores de namespace.

[in] dwNumberOfEntries

O número de elementos na matriz NSProviderId .

Valor retornado

A função retornará ERROR_SUCCESS (zero) se a rotina for bem-sucedida. Caso contrário, ele retornará um código de erro específico.

Código do erro	Significado
WSAEFAULT	A matriz NSProviderId não está totalmente contida no espaço de endereço do processo.
WSAEINVAL	Os parâmetros de entrada eram inválidos, nenhuma ação foi tomada.
WSANO_RECOVERY	Ocorreu um erro não recuperável. Esse erro é retornado sob várias condições, incluindo o seguinte: o registro Winsock não pôde ser aberto, o usuário não tem os privilégios administrativos necessários para gravar no registro Winsock ou outro aplicativo está gravando no catálogo do provedor de namespace.
WSASYSCALLFAILURE	Falha em uma chamada do sistema que nunca deve falhar.
WSATRY_AGAIN	A função é chamada por outro thread ou processo.
WSA_NOT_ENOUGH_MEMORY	Memória insuficiente disponível para executar a operação.
(outro)	A função pode retornar qualquer código de erro do Registro.

Comentários

Os provedores de namespace são instalados em plataformas de 64 bits em um catálogo de provedores de namespace de 32 bits usando a função WSCInstallNameSpace32 . A ordem na qual os provedores de namespace em um catálogo de 32 bits são instalados inicialmente rege a ordem padrão na qual eles são enumerados por meio de WSCEnumNameSpaceProviders32. Mais importante, essa ordem também rege a ordem na qual os provedores de namespace são considerados quando um cliente solicita a resolução de nomes. Em plataformas de 64 bits, a função WSCWriteNameSpaceOrder32 é fornecida para permitir que processos de 64 bits alterem a ordem dos provedores de namespace no catálogo do provedor de namespace de 32 bits. A ordem dos provedores de namespace no catálogo nativo pode ser alterada usando a função WSCWriteNameSpaceOrder .

O catálogo do provedor de namespace atual é armazenado no registro sob a seguinte chave do Registro: HKEY_LOCAL_MACHINE\\ SystemCurrent Control Set\Services\Winsock2\Parameters\NameSpace_Catalog5

Uma solicitação de cliente para resolução de nomes usa as rotinas WSALookupServiceBegin, WSALookupServiceNext e WSALookupServiceEnd . O membro dwNameSpace da estrutura WSAQUERYSET passado para WSALookupServiceBegin é definido como o identificador de um único namespace (NS_DNS, por exemplo) no qual restringir a pesquisa ou NS_ALL incluir todos os namespaces. Se vários provedores de namespace derem suporte a um namespace específico (por exemplo, NS_DNS), os resultados de todos os provedores de namespace que correspondem ao dwNameSpace solicitado serão retornados, a menos que o membro lpNSProviderId esteja definido como um provedor de namespace específico. Os resultados de todos os provedores de namespace serão retornados se NS_ALL for especificado para o membro dwNameSpace . A ordem em que os resultados são retornados depende da ordem do provedor de namespace no catálogo.

O SDK do Windows inclui um aplicativo chamado SpOrder.exe que permite que o catálogo de provedores de namespace instalados seja exibido. O Winsock 2 inclui o ws2_32.DLL em plataformas de 64 bits que exporta a função WSCWriteNameSpaceOrder32 para reordenar provedores de namespace no catálogo do provedor de namespace de 32 bits. Essa interface pode ser importada vinculando-se a WS2_32.lib. Para computadores em execução no Windows XP com Service Pack 2 (SP2) e Windows Server 2003 com Service Pack 1 (SP1) e posterior, o comando netsh.exe winsock show catalog exibirá o protocolo e os provedores de namespace instalados. O catálogo nativo de 64 bits é exibido primeiro seguido pelos catálogos de provedores de 32 bits (indicados com um 32 após seu nome).

WSCWriteNameSpaceOrder32 só pode ser chamado por um usuário conectado como membro do grupo Administradores. Se WSCWriteNameSpaceOrder32 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 em execução no Windows Vista e no Windows Vista, 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, 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 e no Windows Vista não tiver essa configuração no arquivo de manifesto usado para compilar o arquivo executável, um usuário conectado como membro do grupo Administradores que não seja o Administrador deverá executar o aplicativo em um shell avançado como Administrador (administrador RunAs) para que essa função tenha êxito.

A lista a seguir descreve cenários em que a função WSCWriteNameSpaceOrder32 pode falhar:

O parâmetro dwNumberOfEntries não é igual ao número de provedores de namespace registrados.
A matriz NSProviderId contém um identificador de provedor de namespace inválido.
A matriz NSProviderId não contém todos os identificadores de provedor de namespace válidos exatamente uma vez.
A função não é capaz de acessar o registro por algum motivo (permissões de usuário insuficientes, por exemplo).
Outro processo, ou thread, está chamando a função no momento.

Requisitos


Cliente mínimo com suporte	Windows Vista, Windows XP Professional x64 Edition [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008, Windows Server 2003 x64 Edition [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	sporder.h
Biblioteca	Sporder.lib
DLL	Ws2_32.dll