WSAAdvertiseProvider function (ws2spi.h)

Article
10/13/2021

The WSAAdvertiseProvider function makes a specific namespace version-2 provider available for all eligible clients.

Syntax

INT WSAAPI WSAAdvertiseProvider(
  [in] const GUID             *puuidProviderId,
  [in] const LPCNSPV2_ROUTINE pNSPv2Routine
);

Parameters

[in] puuidProviderId

A pointer to the provider ID of the namespace provider to be advertised.

[in] pNSPv2Routine

A pointer to a NSPV2_ROUTINE structure with the namespace service provider version-2 entry points supported by the provider.

Return value

If no error occurs, WSAProviderCompleteAsyncCall returns zero.

If the function fails, the return value is SOCKET_ERROR. To get extended error information, call WSAGetLastError, which returns one of the following extended error values.

Error code	Meaning
WSA_NOT_ENOUGH_MEMORY	There was insufficient memory to perform the operation.
WSAEFAULT	An internal error occurred.
WSAEINVAL	A parameter was not valid. This error is returned if the puuidProviderId or pNSPv2Routine parameters were NULL. This error is also returned if the NSPv2LookupServiceBegin, NSPv2LookupServiceNextEx, or NSPv2LookupServiceEnd members of the NSPV2_ROUTINE structure pointed to by the pNSPv2Routine parameter are NULL. A namespace version-2 provider must at least support name resolution which this minimum set of functions.
WSAEINVALIDPROVIDER	The namespace provider could not be found for the specified puuidProviderId parameter.
WSANOTINITIALISED	The Ws2_32.dll has not been initialized. The application must first call WSAStartup before calling any Windows Sockets functions.

Remarks

The WSAAdvertiseProvider function is used as part of the namespace service provider version-2 (NSPv2) architecture available on Windows Vista and later.

On Windows Vista and Windows Server 2008, the WSAAdvertiseProvider function can only be used for operations on NS_EMAIL namespace providers.

The WSAAdvertiseProvider function advertises an instance of a NSPv2 provider for clients to find. If the instance to be advertised is an instance of an application-type provider (a namespace provider where the dwProvideType member of the NAPI_PROVIDER_INSTALLATION_BLOB structure is ProviderType_Application), the advertised provider instance will be visible to all the client processes running under the same user and in the same session as the caller of WSAAdvertiseProvider.

In general, NSPv2 providers are implemented in processes other than the calling applications. NSPv2 providers are not activated as a result of client activity. Each provider hosting application decides when to make a specific provider available or unavailable by calling the WSAAdvertiseProvider and WSAUnadvertiseProvider functions. The client activity only results in attempts to contact the provider, when available (when the namespace provider is advertised).

The WSAAdvertiseProvider function is called by any application that wants to make a specific provider available for all eligible clients (currently all the applications running with the same credentials as the hosting application, and in the same user session).

A process can implement and advertise multiple providers at the same time. Windows Sockets will manage the namespace providers by dispatching calls to the correct one. It will also hide RPC interface details and translates cross-process calls into in-process calls. So that the NSPv2 provider has only to implement a table of entry point functions similar to the NSP_ROUTINE structure used by an NSPv1 provider. A NSPv2 provider does not have to worry about RPC specific requirements (data marshalling and serialization, for example).

The WSAAdvertiseProvider caller passes a pointer to an NSPV2_ROUTINE structure in the pNSPv2Routine parameter with the NSPv2 entry points supported by the provider.

The WSAUnadvertiseProvider function makes a specific namespace provider no longer available for clients.

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