The DisableMediaSense function disables the media sensing capability of the TCP/IP stack on a local computer.
DWORD DisableMediaSense( HANDLE *pHandle, OVERLAPPED *pOverLapped );
A pointer to a variable that is used to store a handle. If the pOverlapped parameter is not NULL, this variable will be used internally to store a handle required to call the IP driver and disable the media sensing capability.
An application should not use the value pointed to by this variable. This handle is for internal use and should not be closed.
A pointer to 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 object.
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.|
||The operation is in progress. This value is returned by a successful asynchronous call to DisableMediaSense.|
||The handle pointed to by the pHandle parameter was invalid.|
||The request is not supported.|
||Use FormatMessage to obtain the message string for the returned error.|
If the pHandle or pOverlapped parameters are NULL, the DisableMediaSense function is executed synchronously.
If both the pHandle and pOverlapped parameters are not NULL, the DisableMediaSense 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 DisableMediaSense synchronously, an application needs to create a separate thread for this call. Otherwise it would keep waiting for IRP completion and the function will block.
To call DisableMediaSense 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, DisableMediaSense always returns ERROR_IO_PENDING. The IRP will be completed only when RestoreMediaSense is called later. 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.
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 sensing 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 asynchronously. This sample is only useful on Windows Server 2003and Windows XP where the DisableMediaSense and RestoreMediaSense functions do something useful.
The sample first calls the DisableMediaSense function, 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, 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 synchronously, see the RestoreMediaSense function reference.
#include <winsock2.h> #include <ws2tcpip.h> #include <iphlpapi.h> #include <stdio.h>
|Minimum supported client||Windows XP [desktop apps only]|
|Minimum supported server||Windows Server 2003 [desktop apps only]|