Microsoft KB Archive/298504

{|
 * width="100%"|

HOWTO: Avoid Unsafe Removal Dialog Box

 * }

Q298504

-

The information in this article applies to:


 * Microsoft Windows 2000 Driver Development Kit (DDK)
 * the operating system: Microsoft Windows 2000 SP1

-

SUMMARY
This article describes how a function or filter driver for a device can report its ability to tolerate surprise removal. Even if the bus driver indicates that the device is capable of tolerating surprise removal, NDIS always clears the SurpriseRemoval field.

MORE INFORMATION
In Microsoft Windows 2000, you can avoid the Unsafe Removal dialog box. To avoid the Unsafe Removal dialog box, stop the device by selecting the Unplug/Eject icon in the Taskbar tray, and then unplug the hardware. However, if you have a device that can be safely surprise-removed, this process is unnecessary. Instead, drivers for hot plug-in/unplug devices that do not maintain a persistent state should inform the operating systems that they are able to safely tolerate a surprise removal by setting the SurpriseRemovalOK field in the DeviceCapabilities structure to TRUE in response to the IRP_MN_QUERY_CAPABILITIES Plug and Play IRP.

According to the Plug and Play rule, drivers should set the SurpriseRemovalOK field in the IRP_MN_QURERY_CAPABILITIES IRP before passing the IRP to the lower drivers in the device stack. Because the Windows 2000 USB hub driver erroneously resets this field to FALSE, Windows 2000 drivers for USB devices must set the SurpriseRemovalOK field on the way up, as demonstrated in the sample code that follows. This code snippet is adapted for the toaster function driver sample in the DDK (src\general\toaster\func\toaster.c).

   case IRP_MN_QUERY_CAPABILITIES: { //        // Set the SurpiseremovalOK capability to true because this device // can safely tolerate surprise remove, and we want to avoid the unsafe device // removal UI       //

stack->Parameters.DeviceCapabilities.Capabilities->SurpriseRemovalOK = TRUE;

if (!IoIsWdmVersionAvailable(1, 0x20) /* & this is a for USB device */) { //            // Reset the SurpriseRemovalOK capability back to TRUE when the IRP is on            // the way back up to work around a bug in Windows 2000 USB hub driver that // incorrectly sets this capability to FALSE //            // NOTE: IoIsWdmVersionAvailable(1, 0x20) returns TRUE on o/s after // Windows 2000 & Windows Millennium Edition //            //             // This function defined in toaster.c basically sends the Irp to the lower // driver and waits for it complete. //            status = ToasterSendIrpSynchronously(fdoData->NextLowerDriver, Irp); if (NT_SUCCESS (status)) {

stack->Parameters.DeviceCapabilities.Capabilities->SurpriseRemovalOK=TRUE; }       } else {

//            // WDM version is 2.0 or newer (or this is not a USB driver) // so assume the bus driver will not erroneously reset the SurpiseRemovalOK // capability and just pass the IRP down //

IoSkipCurrentIrpStackLocation (Irp); status = IoCallDriver (fdoData->NextLowerDriver, Irp); ToasterIoDecrement(fdoData); //this function is defined in toaster.c           return status; }   }    break;

Additionally, there are cases where devices that do not use persistent storage are not as safe to surprise remove. An example of this is surprise removing a PCMCIA card; in rare cases hardware limitations may cause this removal to cause the PCI bus to fail. For this reason, the PCMCIA bus driver sets the SurpiseRemovalOK field to FALSE for all PCMCIA cards.

NDIS miniport drivers cannot avoid the surprise removal dialog box by following the preceding approach because:


 * All the PnP IRPs are handled by the NDIS driver.
 * Even if the bus driver shows that the device is capable of tolerating surprise removal, NDIS always clears the SurpriseRemoval field.

Currently, there is no other documented interface to work around this problem.

Additional query words:

Keywords : kbDDK kbKMode kbNDIS kbDSupport kbGrpDSNTDDK kbUSB kbWDM

Issue type : kbhowto

Technology : kbwin2000Search kbwin2000DDK kbOSWin2000 kbAudDeveloper kbOSWinSearch kbWinDDKSearch kbOSWin2000SP1