Preparing Hardware and Software for Use with AutoPlay

Several pieces of information need to appear in the registry for AutoPlay to function. These pieces of information interact and reference each other to form the full AutoPlay environment. This document presents the setup of each of these pieces of information as an individual stand-alone procedure.

This article contains the following sections.

• Specifying an Icon for a Device
• Specifying a Label for a Device
• Assigning a Device Handler to a Device
• Specifying an Icon, Label, or Device Handler for a Device Using a Device Group
• Specifying an Icon, Label, or Device Handler for a Device Using a Device Class
• Setting a Default Selection in the Single Content Type Dialog Box
• Preventing AutoPlay for a Component
• Registering a Handler for a Device Event
• Using AutoPlay Events in Running Applications
• Registering an Event Handler
• How AutoPlay Searches Media

Specifying an Icon for a Device

To specify an icon for a device, under the DeviceParameters key of the device instance, add a value named Icons as type REG_MULTI_SZ. The data entry for this value is the path to the file containing the default icon.

A separate value is defined for NoMediaIcons, which specifies a parallel set of device icons used to indicate the same device when no media is inserted. If more than one icon source is provided in the Icons value, the data entries in NoMediaIcons should be listed in the same order so that each icon under Icons has a corresponding entry under NoMediaIcons.

The following example shows an entry for a Vid_059&Pid_0031 device and DLL files that contain the "media inserted" and "no media" versions of the icon.

• HKEY_LOCAL_MACHINE
  • SYSTEM
    • CurrentControlSet
      • Enum
        • USB
          • Vid_059b&Pid_0031
            • 059B003112010E93
              • Device Parameters
                Icons [REG_MULTI_SZ] = %SystemRoot%/system32/mydll.dll,-103
                NoMediaIcons [REG_MULTI_SZ] = %SystemRoot%/system32/mydll.dll,-104

 

The numeric value following the name of the binary file (such as mydll.dll in the example) is the index of the icon in that binary file if zero or greater, or it is the icon resource ID if negative (as in the example). An .ico file does not require a value.

You can provide more than one icon, listed in order of preference with the preferred icon first, but Microsoft Windows XP uses only the first icon.

You can assign icons using device group or device class settings.

Specifying a Label for a Device

To specify a label for a device, under the DeviceParameters key of the device instance, add a value named Label as type REG_SZ. The data entry for this value is the friendly name for the device.

The following is an example entry for a Vid_059&Pid_0031 device.

• HKEY_LOCAL_MACHINE
  • SYSTEM
    • CurrentControlSet
      • Enum
        • USB
          • Vid_059b&Pid_0031
            • 059B003112010E93
              • Device Parameters
                Label [REG_SZ] = My Custom Device Label

 

Labels can also be assigned through device group or device class settings.

Assigning a Device Handler to a Device

To assign a device handler to a device, under the DeviceParameters key of the device instance, add a value named DeviceHandlers as type REG_SZ. The data entry for this value is the name of the device handler.

The following is an example entry for a fictitious Vid_059&Pid_0031 device.

• HKEY_LOCAL_MACHINE
  • SYSTEM
    • CurrentControlSet
      • Enum
        • USB
          • Vid_059b&Pid_0031
            • 059B003112010E93
              • Device Parameters
                DeviceHandlers [REG_SZ] = MyDeviceHandler

 

Device handlers can also be assigned through device group or device class settings.

Specifying an Icon, Label, or Device Handler for a Device Using a Device Group

Device groups allow the specification of the Icons, Label, or DeviceHandlers properties for any device declaring itself part of that group. If the device group is not a system-provided device group, a key defining the device group will be added under the AutoplayHandlers/DeviceGroups key. You do not need to set all three properties for each group, you can set only those properties that you want to customize.

The following example uses a system with several attached Zip drives. Without specifying the Icons, Label, and DeviceHandlers values for each drive individually, you create a device group called ZipDrive and define those values within it. Each Zip drive is then declared a member of the ZipDrive group.

First, define the device group by adding the following ZipDrive key and its values.

• HKEY_LOCAL_MACHINE
  • SOFTWARE
    • Microsoft
      • Windows
        • CurrentVersion
          • Explorer
            • AutoplayHandlers
              • DeviceGroups
                • ZipDrive
                  Icons [REG_MULTI_SZ] = %SystemRoot%/system32/mydll.dll,-103
                  NoMediaIcons [REG_MULTI_SZ] = %SystemRoot%/system32/mydll.dll,-104
                  Label [REG_SZ] = My Custom Device Label
                  DeviceHandlers [REG_SZ] = MyDeviceHandler

 

Each Zip drive device is then declared as part of the ZipDrive group, inheriting the properties of that group. Under the DeviceParameters key of the device instance, add a value named DeviceGroup as type REG_SZ. The data entry for this value is the name of the device group.

• HKEY_LOCAL_MACHINE
  • SYSTEM
    • CurrentControlSet
      • Enum
        • USB
          • Vid_059b&Pid_0031
            • 059B003112010E93
              • Device Parameters
                DeviceGroup [REG_SZ] = ZipDrive

 

You can also add custom device properties other than Icons, Label, and DeviceHandlers under the device group's key and then apply them to all devices belonging to that device group.

Note  Properties defined at the device instance level take precedence over properties defined at the device group level.

Specifying an Icon, Label, or Device Handler for a Device Using a Device Class

Device classes allow the specification of the Icons, Label, and DeviceHandlers properties for any device of that class. This is similar to the use of device groups, but device classes and their memberships are determined by the hardware rather than being created or assigned. Each class key name, which is the Plug and Play device interface GUID, is found under the DeviceClasses key. Under the individual class key, assign the values for Icons, Label, and DeviceHandlers.

The following example shows the class key and DeviceHandlers values for the volume interface.

• HKEY_LOCAL_MACHINE
  • SOFTWARE
    • Microsoft
      • Windows
        • CurrentVersion
          • Explorer
            • AutoplayHandlers
              • DeviceClasses
                • {53f5630d-b6bf-11d0-94f2-00a0c91efb8b}
                  DeviceHandlers [REG_SZ] = GenericVolumeHandler

 

You can also add custom device properties under the device class key. The custom device properties then apply to all devices in that class.

Note  Properties defined at the device instance level take precedence over properties defined at the device group level which in turn takes precedence over properties defined at the device class level.

Setting a Default Selection in the Single Content Type Dialog Box

The following example shows the key and value used to set the default selection (the selection highlighted when the dialog box is presented) for the single content type dialog box.

• HKEY_CURRENT_USER
  • SOFTWARE
    • Microsoft
      • Windows
        • CurrentVersion
          • Explorer
            • AutoplayHandlers
              • EventHandlersDefaultSelection
                Event = Event Handler

 

"Event" is the name of one of the AutoPlay event handler keys registered under the EventHandlers key, for instance ShowPicturesOnArrival. "Event Handler" is one of the values for that event, for instance MSOpenFolder.

Preventing AutoPlay for a Component

To prevent AutoPlay from launching in response to an event, add the following REG_SZ value, as shown in this example.

• HKEY_LOCAL_MACHINE
  • SOFTWARE
    • Microsoft
      • Windows
        • CurrentVersion
          • Explorer
            • AutoplayHandlers
              • CancelAutoplay
                • CLSID
                  00000000-0000-0000-0000-000000000000

 

The value is the class identifier (CLSID) that the component generating the event is known by in the running object table (ROT). The value has no data.

Important  Under this key, the CLSIDs are not enclosed in braces ( {} ).

Registering a Handler for a Device Event

Handlers define the software portion of AutoPlay. They define the software's icon and friendly name, as well as the Component Object Model (COM) component to instantiate and how to initialize the component in response to an event. Each handler for a specific event registers as a value under the appropriate EventHandler key. When that event is detected, the user is prompted to choose a handler from a list of all the handlers registered for that event.

Handlers and their associated values are defined under the AutoplayHandlers/Handlers key. Subkeys differ depending on whether the system can read device contents directly or whether the device provides contents to the system through a proprietary interface.

The following example shows the subkeys and values used for a device such as a digital video camera or .mp3 player that provides its contents to the system through a proprietary interface. The example handler is called MyHandler.

• HKEY_LOCAL_MACHINE
  • SOFTWARE
    • Microsoft
      • Windows
        • CurrentVersion
          • Explorer
            • AutoplayHandlers
              • Handlers
                • MyHandler
                  Action [REG_SZ] = Play music
                  CLSID [REG_SZ] = {a51f2ed3-634e-4a97-9d55-efcf08e7b32f}
                  DefaultIcon [REG_EXPAND_SZ] = %ProgramFiles%/Windows Media Player/wmplayer.exe,0
                  InitCmdLine [REG_SZ] = /Play
                  ProgID [REG_SZ] = WMP.PlayMusicFiles
                  Provider [REG_SZ] = Windows Media Player

 

Note  While the example shows both a ProgID and a CLSID value, in practice they are mutually exclusive so that only one or the other is present. The ProgID value is preferred. Whichever is used, it should point to a COM component that implements the IHWEventHandler interface.

You can enter the Action value as a literal value, for example "Play music" as shown in this example, or as a file name with a resource string. You can also enter the Provider value as a literal value or as a file name with a resource string. AutoPlay combines the Action value and the Provider value with the word "using" to create a friendly caption that displays in the user interface (UI). In the example, the resulting caption is "Play music using Windows Media Player."

The DefaultIcon value points to either an .ico file or a resource in a binary file. If the numeric value that follows the binary file name is zero or greater, then it is the index value of the icon in that binary file. If it is is a negative value, then it is the icon resource ID. Negative index values are recommended. No value is necessary in the case of an .ico file. It is recommended that you use environment variables in the path.

The InitCmdLine value passes unaltered through the IHWEventHandler::Initialize method before any other methods are called.

This example shows the subkeys and values used for a device that can be read directly such as a CD-ROM drive or other removable disk. Again, the example handler is called MyHandler.

• HKEY_LOCAL_MACHINE
  • SOFTWARE
    • Microsoft
      • Windows
        • CurrentVersion
          • Explorer
            • AutoplayHandlers
              • Handlers
                • MyHandler
                  Action [REG_SZ] = @%systemroot%/System32/wiaacmgr.exe,-276
                  DefaultIcon [REG_EXPAND_SZ] = %systemroot%/System32/wiaacmgr.exe,-2
                  InvokeProgID [REG_SZ] = WIA.AutoPlayDropHandler
                  InvokeVerb [REG_SZ] = open
                  Provider [REG_SZ] = @%systemroot%/System32/wiaacmgr.exe,-101

 

In this example, the Action and Provider values are shown as a file name with a resource string rather than literal values, but the strings that they reference are used in the same manner. They are combined with the word "using" to form a friendly caption as explained earlier.

InvokeProgID and InvokeVerb values replace CLSID, InitCmdLine, and ProgID. The InvokeProgID and InvokeVerb values match key names found under HKEY_CLASSES_ROOT as shown in the following registry entry. This set of example keys corresponds to the specific Handler example described earlier.

• HKEY_CLASSES_ROOT
  • WIA.AutoplayDropHandler
    • shell
      • open
        • DropTarget
          Clsid = {F1ABE2B5-C073-4dba-B6EB-FD7A5111DD8F}

CoCreateInstance uses the CLSID to implement the appropriate application.

 

After you define the handler in either of these two ways, you need to register it for a specific event. You do this by providing the handler name as a value for that event's key under EventHandlers . The following example shows how to register MyHandler as a handler for the GenericVolumeArrival event. It has no assigned data value.

• HKEY_LOCAL_MACHINE
  • SOFTWARE
    • Microsoft
      • Windows
        • CurrentVersion
          • Explorer
            • AutoplayHandlers
              • EventHandlers
                • GenericVolumeArrival
                  MyHandler [REG_SZ]

 

Using AutoPlay Events in Running Applications

The IHWEventHandler interface can be registered in the ROT so that running applications have access to AutoPlay events. To use AutoPlay events in running applications, first create a new component implementing the IHWEventHandler interface. Initialize it with the InitCmdLine value from the particular handler's entry under the Handlers key, because Autoplay does not call the Initialize method.

Call CreateHardwareEventMoniker to get a moniker that represents your component and the event handler you want to called. Finally, use the ppmoniker parameter to register your component in the ROT as shown in the example.

Note   LoadLibrary can pose security risks. Refer to the LoadLibrary documentation for information on how to correctly load DLLs with different versions of Windows

Show Example

typedef HRESULT (*CREATEHARDWAREEVENTMONIKER)(REFCLSID clsid, LPCWSTR pszEventHandler, IMoniker **ppmoniker);

HRESULT RegisterComponent(IUnknown* punk, DWORD* dpwToken)
{
    HRESULT hr = E_FAIL;
    HINSTANCE hinstShSvcs = LoadLibrary(TEXT("shsvcs.dll"));
	
    if (hinstShSvcs)
    {	
        CREATEHARDWAREEVENTMONIKER fct = (CREATEHARDWAREEVENTMONIKER)GetProcAddress(hinstShSvcs, "CreateHardwareEventMoniker");
        if (fct)
        {
            IMoniker* pmoniker;
			
            hr = fct(CLSID_App, TEXT("VideoCameraArrival"), &pmoniker);

            if (SUCCEEDED(hr))
            {
                IRunningObjectTable *prot;
					
                if (SUCCEEDED(GetRunningObjectTable(0, &prot)))
                {
                    hr = prot->Register(ROTFLAGS_ALLOWANYCLIENT | ROTFLAGS_REGISTRATIONKEEPSALIVE, punk, pmoniker, &_dwRegisterROT);
                    prot->Release();
                }
                pmoniker->Release();
            }
            CoRegisterClassObject(CLSID_App, static_cast<IClassFactory *>(this), CLSCTX_LOCAL_SERVER, REGCLS_MULTIPLEUSE, &_dwRegisterClass;
        }
        FreeLibrary(hinstShSvcs);
    }
    return hr;
}
				

The call to IRunningObjectTable::Register requires that the component have the following AppID information in the registry.

• HKEY_CLASSES_ROOT
  • AppID
    • MyApp.exe
      (Default) = MyApplication
      AppID [REG_SZ] = {Your GUID here}

• HKEY_CLASSES_ROOT
  • AppID
    • {The same GUID here}
      (Default) = MyApplication
      RunAs = Interactive User

 

Registering an Event Handler

A device can potentially generate many events, and each event can have the option of being handled by one of a number of different handlers. In Windows XP, the following events are defined.

• DeviceArrival
• DeviceRemoval
• MediaArrival
• MediaRemoval

Event handlers are defined under the EventHandlers key. An event handler key's values are the names of each handler that the user must choose from when the event is detected. There is no data value associated with these entries. Following is an example definition for a custom event handler called MyNewRemovalEventHandler, which presents these handler possibilities to the user.

• A handler to use if the event is detected on a device made by the company named Contoso, Inc.
• A handler to use if the event is detected on a device made by the company named Fabrikam, Inc.
• A handler to use in all other cases.

 

• HKEY_LOCAL_MACHINE
  • SOFTWARE
    • Microsoft
      • Windows
        • CurrentVersion
          • Explorer
            • AutoplayHandlers
              • EventHandlers
                • MyNewRemovalEventHandler
                  CompanyContosoHandler [REG_SZ]
                  CompanyFabrikamHandler [REG_SZ]
                  MyRemovalHandler [REG_SZ]

 

After an event handler is defined, it must be registered with a device handler for one of the event possibilities—DeviceArrival, DeviceRemoval, MediaArrival, or MediaRemoval. MyNewRemovalEventHandler, defined earlier, is used for DeviceRemoval under a custom device handler named MyDeviceHandler and is defined for that purpose in the following example. Again, the registry value has no data component.

• HKEY_LOCAL_MACHINE
  • SOFTWARE
    • Microsoft
      • Windows
        • CurrentVersion
          • Explorer
            • AutoplayHandlers
              • DeviceHandlers
                • EventHandlers
                  • DeviceRemoval
                    MyNewRemovalEventHandler

 

Windows XP predefines the following set of EventHandlers.

EventHandlers key	Media or file type
HandleCDBurningOnArrival	Blank CD-R/CD-RW
ShowPicturesOnArrival	Picture files
PlayMusicFilesOnArrival	Music files
PlayVideoFilesOnArrival	Video files
PlayCDAudioOnArrival	Audio CD (REDBOOK format CD with Audio tracks)
PlayDVDMovieOnArrival	DVD movies

Windows Vista predefines the following set of EventHandlers in addition to those above.

EventHandlers key	Media or file type
PlaySuperVideoCDMovieOnArrival	Super VideoCD movies
PlayVideoCDMovieOnArrival	VideoCD movies

How AutoPlay Searches Media

AutoPlay searches for media four directory levels below the root directory to find known file types. It uses the PerceivedType value associated with a file extension in the registry to determine the file category, whether it is an image, an audio file, or a video file. With this information, AutoPlay launches the appropriate handler for that device and file type. For more information, see PerceivedTypes, SystemFileAssociations, and Application Registration.