WSCInstallNameSpaceEx function (ws2spi.h)

The WSCInstallNameSpaceEx function installs a namespace provider. For providers that are able to support multiple namespaces, this function must be called for each namespace supported, and a unique provider identifier must be supplied each time.

Syntax

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

Parameters

[in] lpszIdentifier

A pointer to a string that identifies the provider associated with the globally unique identifier (GUID) passed in the lpProviderId parameter.

[in] lpszPathName

A pointer to a Unicode string that contains the load path to the provider DLL. This string observes the usual rules for path resolution and can contain embedded environment strings (such as %SystemRoot%). Such environment strings are expanded when the Ws2_32.dll must subsequently load the provider DLL on behalf of an application. After any embedded environment strings are expanded, the Ws2_32.dll passes the resulting string to the LoadLibrary function which loads the provider into memory. For more information, see LoadLibrary.

[in] dwNameSpace

The namespace supported by this provider.

[in] dwVersion

The version number of the provider.

[in] lpProviderId

A pointer to a GUID for the provider. This GUID should be generated by Uuidgen.exe.

[in] lpProviderSpecific

A provider-specific data blob associated with namespace entry.

Return value

If no error occurs, the WSCInstallNameSpaceEx function returns NO_ERROR (zero). Otherwise, it returns SOCKET_ERROR if the function fails, and you must retrieve the appropriate error code using the WSAGetLastError function.

Error code Meaning
WSAEACCES
The calling routine does not have sufficient privileges to install a namespace.
WSAEINVAL
One or more of the arguments are invalid.
WSANO_RECOVERY
A nonrecoverable error occurred. This error is returned under several conditions including the following: the provider is already installed, the user lacks the administrative privileges required to write to the Winsock registry, or a failure occurred when creating or installing a catalog entry.
WSASYSCALLFAILURE
A system call that should never fail has failed.
WSA_NOT_ENOUGH_MEMORY
Insufficient memory was available. This error is returned when there is insufficient memory to allocate a new catalog entry.

Remarks

The namespace–configuration functions do not affect applications that are already running. Newly installed name-space providers will not be visible to applications nor will the changes in a name-space provider's activation state. Applications launched after the call to WSCInstallNameSpaceEx will see the changes.

The provider-specific data blob associated with namespace entry passed in the lpProviderInfo parameter can be queried using the WSAEnumNameSpaceProvidersEx function.

Currently, the only namespace provider included with Windows that uses the lpProviderInfo parameter is the NS_EMAIL provider. The format of the buffer pointed to by the lpProviderInfo parameter for an NS_EMAIL namespace provider is a NAPI_PROVIDER_INSTALLATION_BLOB structure.

The WSCInstallNameSpaceEx function can only be called by a user logged on as a member of the Administrators group. If WSCInstallNameSpaceEx is called by a user that is not a member of the Administrators group, the function call will fail. For computers running on Windows Vista or Windows Server 2008, this function can also fail because of user account control (UAC). If an application that contains this function is executed by a user logged on as a member of the Administrators group other than the built-in Administrator, this call will fail unless the application has been marked in the manifest file with a requestedExecutionLevel set to requireAdministrator. If the application on Windows Vista or Windows Server 2008 lacks this manifest file, a user logged on as a member of the Administrators group other than the built-in Administrator must then be executing the application in an enhanced shell as the built-in Administrator (RunAs administrator) for this function to succeed.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header ws2spi.h
Library Ws2_32.lib
DLL Ws2_32.dll

See also

NAPI_PROVIDER_INSTALLATION_BLOB

WSAEnumNameSpaceProviders

WSAEnumNameSpaceProvidersEx

WSCInstallNameSpace

WSCInstallNameSpaceEx32

WSCUnInstallNameSpace