Função WSCWriteProviderOrder (sporder.h)

  • Artigo

A função WSCWriteProviderOrder é usada para reordenar os provedores de transporte disponíveis. A ordem dos protocolos determina a prioridade de um protocolo ao ser enumerado ou selecionado para uso.

Sintaxe

int WSCWriteProviderOrder(
  [in] LPDWORD lpwdCatalogEntryId,
  [in] DWORD   dwNumberOfEntries
);

Parâmetros

[in] lpwdCatalogEntryId

Um ponteiro para uma matriz de elementos CatalogEntryId encontrados na estrutura WSAPROTOCOL_INFO . A ordem dos elementos CatalogEntryId é a nova ordenação de prioridade para os protocolos.

[in] dwNumberOfEntries

O número de elementos na matriz lpwdCatalogEntryId .

Retornar valor

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
WSAEINVAL
 Um ou mais argumentos são 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 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.
(outro)
 A rotina pode retornar qualquer código de erro do Registro.

Comentários

A ordem na qual os provedores de serviços de transporte são instalados inicialmente rege a ordem na qual eles são enumerados por meio de WSCEnumProtocols na interface do provedor de serviços ou por meio de WSAEnumProtocols na interface do aplicativo. Mais importante, essa ordem também rege a ordem na qual os protocolos e provedores de serviços são considerados quando um cliente solicita a criação de um soquete com base em sua família de endereços, tipo e identificador de protocolo.

O Windows Sockets 2 inclui um aplicativo chamado Sporder.exe que permite que o catálogo de protocolos instalados seja reordenado interativamente após a instalação dos protocolos. O Windows Sockets 2 também inclui uma DLL auxiliar ,Sporder.dll que exporta essa interface de procedimento para reordenar protocolos. Essa interface pode ser importada vinculando-se a Sporder.lib.

Veja a seguir cenários em que a função WSCWriteProviderOrder pode falhar:

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

Em caso de êxito, WSCWriteProviderOrder tentará alertar todos os aplicativos interessados que se registraram para notificação da alteração chamando WSAProviderConfigChange.

A função WSCWriteProviderOrder só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se WSCWriteProviderOrder for chamado por um usuário que não seja membro do grupo Administradores, a chamada de função falhará e WSANO_RECOVERY será retornado. 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 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.

Requisitos

Requisito Valor
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

Confira também

Wsaenumprotocols

WSAPROTOCOL_INFO

WSAProviderConfigChange

WSCEnumProtocols