Expand Minimize

WSAProviderConfigChange function

The WSAProviderConfigChange function notifies the application when the provider configuration is changed.

Syntax


int WSAAPI WSAProviderConfigChange(
  _Inout_  LPHANDLE lpNotificationHandle,
  _In_     LPWSAOVERLAPPED lpOverlapped,
  _In_     LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

Parameters

lpNotificationHandle [in, out]

Pointer to notification handle. If the notification handle is set to NULL (the handle value not the pointer itself), this function returns a notification handle in the location pointed to by lpNotificationHandle.

lpOverlapped [in]

Pointer to a WSAOVERLAPPED structure.

lpCompletionRoutine [in]

Pointer to the completion routine called when the provider change notification is received.

Return value

If no error occurs the WSAProviderConfigChange returns 0. Otherwise, a value of SOCKET_ERROR is returned and a specific error code may be retrieved by calling WSAGetLastError. The error code WSA_IO_PENDING indicates that the overlapped operation has been successfully initiated and that completion (and thus change event) will be indicated at a later time.

Error codeMeaning
WSANOTINITIALISED

A successful WSAStartup call must occur before using this function.

WSAENETDOWN

The network subsystem has failed.

WSA_NOT_ENOUGH_MEMORY

Not enough free memory available to complete the operation.

WSA_INVALID_HANDLE

Value pointed by lpNotificationHandle parameter is not a valid notification handle.

WSAEOPNOTSUPP

Current operating system environment does not support provider installation or removal without restart.

 

Remarks

The WSAProviderConfigChange function notifies the application of provider (both transport and namespace) installation or removal in Windows operating environments that support such configuration change without requiring a restart. When called for the first time (lpNotificationHandle parameter points to NULL handle), this function completes immediately and returns notification handle in the location pointed by lpNotificationHandle that can be used in subsequent calls to receive notifications of provider installation and removal. The second and any subsequent calls only complete when provider information changes since the time the call was made It is expected (but not required) that the application uses overlapped I/O on second and subsequent calls to WSAProviderConfigChange, in which case the call will return immediately and application will be notified of provider configuration changes using the completion mechanism chosen through specified overlapped completion parameters.

Notification handle returned by WSAProviderConfigChange is like any regular operating system handle that should be closed (when no longer needed) using Windows CloseHandle call.

The following sequence of actions can be used to guarantee that application always has current protocol configuration information:

  • Call WSAProviderConfigChange
  • Call WSAEnumProtocols and/or WSAEnumNameSpaceProviders
  • Whenever WSAProviderConfigChange notifies application of provider configuration change (through blocking or overlapped I/O), the whole sequence of actions should be repeated.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.

Requirements

Minimum supported client

Windows 8.1, Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winsock2.h

Library

Ws2_32.lib

DLL

Ws2_32.dll

See also

CloseHandle
Winsock Reference
Winsock Functions
WSAEnumProtocols
WSAEnumNameSpaceProviders

 

 

Community Additions

ADD
Show:
© 2014 Microsoft