The RestoreMediaSense function restores the media sensing capability of the TCP/IP stack on a local computer on which the DisableMediaSense function was previously called.
DWORD RestoreMediaSense( OVERLAPPED *pOverlapped, LPDWORD lpdwEnableCount );
A pointer to an OVERLAPPED structure. Except for the hEvent member, all members of this structure must be set to zero. The hEvent member should contain a handle to a valid event object. Use the CreateEvent function to create this event object.
An optional pointer to a DWORD variable that receives the number of references remaining if the RestoreMediaSense function succeeds. The variable is also used by the EnableRouter and UnenableRouter functions.
If the function succeeds, the return value is NO_ERROR.
If the function fails, the return value is one of the following error codes.
||An invalid parameter was passed to the function. This error is returned if an pOverlapped parameter is a bad pointer. This error is also returned if the DisableMediaSense function was not called prior to calling the RestoreMediaSense function.|
||The operation is in progress. This value may be returned by a successful asynchronous call to RestoreMediaSense.|
||An internal handle to the driver was invalid.|
||The request is not supported.|
||Use FormatMessage to obtain the message string for the returned error.|
If the pOverlapped parameter is NULL, the RestoreMediaSense function is executed synchronously.
If the pOverlapped parameter is not NULL, the RestoreMediaSense function is executed asynchronously using the OVERLAPPED structure pointed to by the pOverlapped parameter.
The DisableMediaSense function does not complete until the RestoreMediaSense function is called later to restore the media sensing capability. Until then, an I/O request packet (IRP) remains queued up. Alternatively, when the process that called DisableMediaSense exits, the IRP is canceled and a cancel routine is called that would again restore the media sensing capability.
To call RestoreMediaSense synchronously, an application needs to pass a NULL pointer in the pOverlapped parameter. When RestoreMediaSense is called synchronously, the function returns when the I/O request packet (IRP) to restore the media sense has completed.
To call RestoreMediaSense asynchronously, an application needs to allocate an OVERLAPPED structure. Except for the hEvent member, all members of this structure must be set to zero. The hEvent member requires a handle to a valid event object. Use the CreateEvent function to create this event. When called asynchronously, RestoreMediaSense can return return ERROR_IO_PENDING. The IRP completes when the media sensing capability has been restored. Use the CloseHandle function to close the handle to the event object when it is no longer needed. The system closes the handle automatically when the process terminates. The event object is destroyed when its last handle has been closed.
If DisableMediaSense was not called prior to calling RestoreMediaSense, then RestoreMediaSense returns ERROR_INVALID_PARAMETER.
On Windows Server 2003and Windows XP, the TCP/IP stack implements a policy of deleting all IP addresses on an interface in response to a media sense disconnect event from an underlying network interface. If a network switch or hub that the local computer is connected to is powered off, or a network cable is disconnected, the network interface will deliver disconnection events. IP configuration information associated with the network interface is lost. As a result, the TCP/IP stack implements a policy of hiding disconnected interfaces so these interfaces and their associated IP addresses do not show up in configuration information retrieved through IP helper. This policy prevents some applications from easily detecting that a network interface is merely disconnected, rather than removed from the system.
This behavior does not normally impact a local client computer if it is using DHCP requests to a DHCP server for IP configuration information. But this can have a serious impact on server computers, particularly computers used as part of clusters. The DisableMediaSense function can be used to temporarily disable the media sense capability for these cases. At some later time, the RestoreMediaSense function would be called to restore the media sensing capability.
The following registry setting is related to the DisableMediaSense and RestoreMediaSense functions:
There is an internal flag in Windows that is set if this registry key exists when the machine first boots up. The same internal flag also gets set and reset by calling DisableMediaSense and RestoreMediaSense. However with registry setting, you need to reboot the machine for the changes to take place.
The TCP/IP stack on Windows Vista and later was changed to not hide disconnected interfaces when a disconnect event occurs. So on Windows Vista and later, the DisableMediaSense and RestoreMediaSense functions don't do anything and always returns NO_ERROR.
The following example shows how to call the DisableMediaSense and RestoreMediaSense functions synchronously. This sample is only useful on Windows Server 2003and Windows XP where the DisableMediaSense and RestoreMediaSense functions do something useful.
The sample first creates a separate thread that calls the DisableMediaSense function synchronously, the main thread sleeps for 60 seconds to allow the user to disconnect a network cable, retrieves the IP address table and prints some members of the IP address entries in the table, calls the RestoreMediaSense function synchronously, retrieves the IP address table again, and prints some members of the IP address entries in the table. The impact of disabling the media sensing capability can be seen in the difference in the IP address table entries.
For an example that shows how to call the DisableMediaSense and RestoreMediaSense functions asynchronously, see the DisableMediaSense function reference.
#include <winsock2.h> #include <ws2tcpip.h> #include <iphlpapi.h> #include <stdio.h>
|Windows version||Windows XP [desktop apps only] Windows Server 2003 [desktop apps only]|