Função WSCWriteNameSpaceOrder (sporder.h)
A função WSCWriteNameSpaceOrder altera a ordem dos provedores de namespace disponíveis do Windows Sockets (Winsock) 2. A ordem dos provedores de namespace determina a prioridade do namespace quando enumerado ou consultado para resolução de nomes.
Sintaxe
int WSCWriteNameSpaceOrder(
[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 |
|---|---|
| A matriz NSProviderId não está totalmente contida no espaço de endereço do processo. | |
| Um ou mais dos argumentos são parâmetros de entrada inválidos, nenhuma ação foi tomada. | |
| 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 outro aplicativo está gravando no catálogo do provedor de namespace no momento. | |
| Uma chamada do sistema que nunca deve falhar falhou. | |
| A função é chamada por outro thread ou processo. | |
| Memória insuficiente disponível para executar a operação. | |
|
A função pode retornar qualquer código de erro do Registro. |
Comentários
Os provedores de namespace são instalados usando a função WSCInstallNameSpace . A ordem na qual os provedores de namespace são instalados inicialmente rege a ordem padrão na qual eles são enumerados por meio de WSAEnumNameSpaceProviders. Mais importante, essa ordem também rege a ordem na qual os provedores de namespace são considerados quando um cliente solicita resolução de nomes. A ordem dos provedores de namespace pode ser alterada usando a função WSCWriteNameSpaceOrder . 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. Em plataformas de 64 bits, os provedores de namespace são instalados no catálogo de provedores de namespace de 32 bits usando a função WSCInstallNameSpace32 .
O catálogo do provedor de namespace atual é armazenado no registro sob a seguinte chave do Registro:HKEY_LOCAL_MACHINE\Os Parâmetros\Winsock2\ doSystem\Current Control Set\ 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 passada 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 (NS_DNS, por exemplo), os resultados de todos os provedores de namespace que correspondem ao dwNameSpace solicitado serão retornados, a menos que o membro lpNSProviderId seja 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 Windows Sockets 2 inclui o ws2_32.dll que exporta a função WSCWriteNameSpaceOrder para reordenar provedores de namespace no catálogo. 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 posteriores, o comando de catálogo do winsock show donetsh.exe exibirá os provedores de protocolo e namespace instalados no sistema.
WSCWriteNameSpaceOrder só pode ser chamado por um usuário conectado como membro do grupo Administradores. Se WSCWriteNameSpaceOrder 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 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 para exigirAdministrador. 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 aprimorado como Administrador (administrador RunAs) para que essa função tenha êxito.
A lista a seguir descreve cenários em que a função WSCWriteNameSpaceOrder 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 válidos do provedor de namespace exatamente uma vez.
- A função não pode acessar o registro (por exemplo, permissões de usuário insuficientes).
- Outro processo (ou thread) está chamando a função no momento.
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | sporder.h |
| Biblioteca | Sporder.lib |
| DLL | Ws2_32.dll |