Introduction

Removing a USB drive using the Windows tray icon is easy, especially if you single left-click it, but sometimes, it's useful to do it from your program.

Background

There are some samples around, but the ones I saw were searching for the volume and then calling CM_Get_Parent twice to get the USB device to eject. This approach works only with drives which claim to have removable media. Such drives (drive type: DRIVE_REMOVABLE) are handled differently from basic disks (DRIVE_FIXED) under W2K and XP. Removable drives have a one-to-one relation between the volume and the disk, where the disk is the parent device of the volume. This is true for CDROM drives too.

USB drives without removable media are handled like basic disks, so they can have multiple partitions, and the volume's parent device is not the disk! Under Vista, this is the case for removable drives too, but multiple partitions are still not allowed. By the way, there are more differences resulting from the type of the USB disk. Here is some information.

The magic link between storage volumes and their disk is the device number. You can get it via DeviceIoControl called with IOCTL_STORAGE_GET_DEVICE_NUMBER. This call works with handles to storage volumes on one side, and disk, floppy, and CDROM drives on the other side.

Storage volumes can be spread over multiple disks. So, it is possible that for safe removal of a storage volume, more than one disk device has to be prepared for safe removal. Getting the list of device numbers of such a storage volume is done by IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. I have ignored this because I think that using a RAID on external drives is a strange idea.

The device number is unique within a device class only. When dealing with drive letters, we have to distinguish between the device interfaces GUID_DEVINTERFACE_DISK, GUID_DEVINTERFACE_FLOPPY, and GUID_DEVINTERFACE_CDROM. The floppies were not considered here until end of October 2006, so a USB floppy screwed up everything, in theory. In real life, a USB floppy has usually device number 0, while any other USB drive has a higher number, so there were no real problems.

By the way: in W2K and XP, legacy floppies are not part of the GUID_DEVINTERFACE_FLOPPY enumeration.

The Sample

This sample is a simplified version of my command-line tool RemoveDrive. It expects the drive letter as a parameter to prepare for safe removal. It opens the volume and gets its device number:

Depending on the volume's drive type and the DOS device name, it then enumerates either all disks, floppies, or CD-ROMs, using the setup API. The device numbers of the drives are matched with the device number mentioned above in order to get the device instance of the correct drive:

The parent device of the disk, floppy, or CD-ROM is the USB device to eject. CM_Request_Device_Eject shall be used for devices which have the SurpriseRemovalOK flag only. Otherwise, CM_Query_And_Remove_SubTree shall be used. See MSDN here and here.

As a result, the removed device is still present but has a problem code which is usually 47 (CM_PROB_HELD_FOR_EJECT). But if CM_Query_And_Remove_SubTree is used for a USB device (which has the SurpriseRemovalOK flag) then the problem code is 21 (CM_PROB_WILL_BE_REMOVED). This seems to be "safe" too since the USB device's drive and volume are gone then. The big difference here is that such a device can be reactivated! I have made a tool for this: RestartSrDev.

However, CM_Query_And_Remove_SubTree doesn't work for restricted users; it returns CR_ACCESS_DENIED in these cases, while the non-suggested CM_Request_Device_Eject works fine for restricted users. Surprisingly, CM_Request_Device_Eject does not work in a service or a GINA, here CM_Query_And_Remove_SubTree is the right choice.

When using CM_Query_And_Remove_SubTree, we have to add the flag CM_REMOVE_NO_RESTART because otherwise the just-removed device may be immediately redetected. This happens under Vista, but is also reported to happen under W2K and XP sometimes. It is documented as "Beginning with Windows XP" but the flag works (and is required) under W2K with SP4 too.

I take the easy way, and now use CM_Request_Device_Eject exclusively in this sample.

Discussion

If you use it for PATA drives, then both master and slave drives are removed! However, both can be brought back with a DEVCON RESCAN.

If the functions are called with NULL/0 for the veto parameters, then XP shows the "it's safe now" balloon tip, W2K shows a message box, and Vista shows nothing. As McCoy once said: "I know engineers. They love to change things."

I remember that I've seen CM_Query_And_Remove_SubTree and CM_Request_Device_Eject returning CR_SUCCESS even when the call failed with a veto under XP. I cannot reproduce it, but I'm sure I've seen this, maybe it was under XP RTM or SP1. Therefore, it seems to be better to check the veto values the functions return.

Under Windows 2000, the ANSI versions of both functions are not implemented. They return CR_CALL_NOT_IMPLEMENTED, so we use the Unicode versions instead.

Both functions usually take several seconds until they return, so it's a good idea to put them into their own thread. In fact, the delay can be up to 30 seconds under XP, and up to 15 seconds since Vista. This happens when a process has registered for receiving the removal request and does not return it. To keep this sample simple, there is no extra thread created for calling CM_Request_Device_Eject:

It's often seen that the removal fails on the first attempt but works on the second attempt. Therefore, I just try it three times.

What Makes the Removal Fail

The preparation for safe removal fails as long as there is one open handle to the disk or to the storage volume. And, of course, you cannot run this EXE from the drive to remove. To do that, you would need a temporary copy on another drive. ProcessExplorer is great for discovering which process holds an open handle to a drive. Press Ctrl+F and enter the drive letter, like U:. It's often seen that it cannot resolve drive letters, so you have to search for the DOS device name of the drive. It should be something like \Device\Harddisk4\DP(1)0-0+11. A significant part, such as 'disk4', is usually good enough. On occasions, however, even the driver-driven ProcessExplorer isn't able to find the nasty handle.

Reactivate a USB Drive after Safe Removal

When prepared for safe removal and having the problem code 47 (CM_PROB_HELD_FOR_EJECT), a USB device cannot be reactivated. The only way out is to deactivate and then reactivate the USB hub which it is connected to. This works with both standard hubs and root hubs. Of course, this cycles all USB devices attached to this hub.

The Demo Project

The demo project is made with VS6. It requires LIBs and headers from the Microsoft Windows Platform SDK and DDK/WDK. If you are using a newer Visual Studio, just try to compile it. If it complains about missing includes or LIBs, just get the latest SDK. If someting is still missing, it might come with the Windows Driver Kit (WDK): here.

Using Visual Studio 6.0

Many users still love to use VS6, me too. This is because it is slim, snappy, and installed in no time. In fact, for simple Win32 applications it's good enough to copy its folder and import its Registry settings. The disadvantages are the old compiler, missing x64 support, and the incompatibility with the new SDKs and DDKs/WDKs.

The latest SDK version that integrates and works perfectly with VS6 is from February 2003. It's called "Platform SDK for Windows Server 2003" (February 2003 Edition, Build 3790.0), and is still available for download at Microsoft, see here. Unfortunately, cfg.h and cfgmgr32.lib do not come with this SDK, even cfgmgr32.h has an include for cfg.h. cfg.h and the also missing cfgmgr32.lib are found in the Windows DDK. Both can be used from any DDK or WDK, even new versions, e.g., from WDK Build 6000. When building more complex projects, you will run into trouble since other header and lib files from newer SDKs and DDKs/WDKs will not work with VS6! The oldest DDK available for download is the "Windows Server 2003 SP1 DDK" (Build 3790.1830): 1830_usa_ddk.iso. Most files are compatible with VS6, but some lib files are not when compiling debug versions, for instance, uuid.lib. uuid.lib is no problem, since a compatible one comes with VS6. In such cases, just rename the new file to make VS6 use the old one from its own LIB folder. The right DDK for VS6 is the "Windows XP SP1 DDK" (Build 2600.1106), but this is not available for download at Microsoft.

If you don't want to download a whole DDK for a single file, then you can use CFG.h from the ReactOS project, which is at least compatible for this demo. Just put the downloaded cfg.h into the folder where the cfgmgr32.h is found.

The integration of the SDK+DDK headers and libs is usually done manually by entering them into the include and lib folder list.

I had tried it with my tool RemoveDrive and here it worked. I've checked the code and there is indeed a trick involved. First perform the silent removal, then call CM_Request_Device_Eject to get the balloon. The device's problem code remains 21, so reactivating still works.

hi Uwe:I used the codes you posted and made some necessary changes,but i found out that under WIN7 X64 is not working ,the error message i got is:the "drect memory access controller" device is not removable and can not be ejected or unplugged.why?can you give me a basic direction about why is message appeared?thanks ~FYI: the device i want to eject is a calculaor.

Finally it's the device's driver which grants or rejects the request, so the driver of your device just does not support safe removal. I think it is not specific to Win7 x64, it is specific to the driver of the device.

i change the parameters in the cm_request_device_eject like this:cr = CM_Request_Device_EjectW(DeviceInfoData.DevInst,&amp;pnpvietotype,NULL,0,0);wheni start to do eject the device ,it pop a messagebox include the message i said before .so that is not a peoblem of system, it's the driver ,i need to make the driver can suppot safe removal .but how to ?can you give me a example ?I'm a new learner of usb field.thank very very much~

It would be very convenient to tell user which processes block safely removal. Sometimes let say Firefox opens some file and disable safely removal.

Btw. I had problems translating your code in Delphi cause lots of functions in setupapi.pas (interface) file are not good mapped. I thought that my code is not working, but actually both code worked excellent and thanks to your sample I found out problems!!

If someone knows if it's possible to map processes that locked files or entire drive I would be very thankful.

I've tried this in my tools RemoveDrive and EjectMedia using some undocumented ntdll.dll calls.

Google for NtQuerySystemInformation, NtQueryObject.

The main problem is that you don't know the type of handle before calling NtQueryObject. But NtQueryObject does not return if you hit a handle of a waiting sync object e.g. a mutex. If this happens then the calling thread is stuck in the kernel, TermitateThread cannot kill it, even killing the process does not work.

Tools as the Sysinternal ProcessExplorer or Cedrick Collomb's Unlocker use a kernel driver to get around this problem.

Yes, I tried it, and it works fine for me.The drive does not rattle, but I don't know if some sort of "cache" is involved in this...I'm not exactly a "Windows internals" expert... but my opinion is that the call is actually querying the geometry of the *drive* rather than the geometry of the *disk*.I'm looking for some old 720k single sided floppy, I'm sure I have some in my loft. Let's see what the OS reports: this should tell us if the disk is phisically accesed or not, do you agree?ciao - Lorenzo -

ok I made some tests with a 720K diskette.1) the call to IOCTL_DISK_GET_DRIVE_GEOMETRY reports MediaType = F3_720_512 so it is reporting the geometry of the disk, not that of the drive (what on earth is "drive geometry", afterall? maybe I drank too much whisky );2) the drive is phisically accessed only if it wasn't accessed previously; I think there is some sensor in the drive that detects media change, so phisical access is unnecessary unless disk geometry wasn't read yet since the last media change;3) ok, the drive actually "rattles" in the described circumstances;4) anyway, I observe that Windows itself has the same behaviour when asked to remove the USB floppy through the tray icon.in conclusion, I think we're on the right track.by the way: I'm (also) a Delphi fan, so I ported your code to Delphi. are you interested in publishing it alongside the C++ one?ciao - Lorenzo -

I have used the above code to remove the PCI drive and found the following errors. 1. If CM_Query_And_Remove_SubTreeW function is used , it returns PNP_VetoOutstandingOpen when tried to remove the device. 2. If CM_Request_Device_EjectW function is used , it returns PNP_VetoIllegalDeviceRequest when tried to remove the device.

1. I tried CM_Query_And_Remove_SubTreeW with drive's DevInst and observed the following state.

The drive has been disappeared from the Disk Management. But in DeviceManager the drive is displayed with yellow icon(the properties of the drive displays that "Windows is uninstalling this device. (Code 21)"). What to do to completely remove the drive from DeviceManager.

2. I tried CM_Request_Device_EjectW with drive's DevInst, it displays the PNP_VetoIllegalDeviceRequest "The device does not support the specified operation". What has to be done from driver to support safe removal ?

You use CM_Request_Device_Eject to eject the drive, which should logically and physically eject the drive.

It physically ejects the drive in XP, but not in Windows 7. The drive cable must be manually removed for the USB device to register a disconnect. How can I send a physical disconnect in Windows 7 to the USB drive?