Função WSCInstallNameSpaceEx (ws2spi.h)

Artigo
03/13/2024

A função WSCInstallNameSpaceEx instala um provedor de namespace. Para provedores que são capazes de dar suporte a vários namespaces, essa função deve ser chamada para cada namespace com suporte e um identificador de provedor exclusivo deve ser fornecido sempre.

Sintaxe

INT WSCInstallNameSpaceEx(
  [in] LPWSTR lpszIdentifier,
  [in] LPWSTR lpszPathName,
  [in] DWORD  dwNameSpace,
  [in] DWORD  dwVersion,
  [in] LPGUID lpProviderId,
  [in] LPBLOB lpProviderSpecific
);

Parâmetros

[in] lpszIdentifier

Um ponteiro para uma cadeia de caracteres que identifica o provedor associado ao GUID (identificador global exclusivo) passado no parâmetro lpProviderId .

[in] lpszPathName

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 (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] dwNameSpace

O namespace compatível com esse provedor.

[in] dwVersion

O número de versão do provedor.

[in] lpProviderId

Um ponteiro para um GUID para o provedor. Esse GUID deve ser gerado por Uuidgen.exe.

[in] lpProviderSpecific

Um blob de dados específico do provedor associado à entrada de namespace.

Retornar valor

Se nenhum erro ocorrer, a função WSCInstallNameSpaceEx retornará NO_ERROR (zero). Caso contrário, ele retornará SOCKET_ERROR se a função falhar e você deverá recuperar o código de erro apropriado usando a função WSAGetLastError .

Código do erro	Significado
WSAEACCES	A rotina de chamada não tem privilégios suficientes para instalar um namespace.
WSAEINVAL	Um ou mais argumentos são inválidos.
WSANO_RECOVERY	Ocorreu um erro não detectável. Esse erro é retornado em várias condições, incluindo o seguinte: o provedor já está instalado, 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.
WSASYSCALLFAILURE	Uma chamada do sistema que nunca deve falhar falhou.
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

As funções namespace–configuration não afetam os aplicativos que já estão em execução. Os provedores de espaço de nome recém-instalados não ficarão visíveis para aplicativos nem as alterações no estado de ativação de um provedor de espaço de nome. Os aplicativos iniciados após a chamada para WSCInstallNameSpaceEx verão as alterações.

O blob de dados específico do provedor associado à entrada de namespace passada no parâmetro lpProviderInfo pode ser consultado usando a função WSAEnumNameSpaceProvidersEx .

Atualmente, o único provedor de namespace incluído no Windows que usa o parâmetro lpProviderInfo é o provedor NS_EMAIL. O formato do buffer apontado pelo parâmetro lpProviderInfo para um provedor de namespace NS_EMAIL é uma estrutura NAPI_PROVIDER_INSTALLATION_BLOB .

A função WSCInstallNameSpaceEx só pode ser chamada por um usuário conectado como membro do grupo Administradores. Se WSCInstallNameSpaceEx 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.

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