The device file name prefix consists of three uppercase letters that identify which device file name corresponds to a particular stream interface. When you implement the stream interface, you designate the three-letter prefix. The prefix can be any three letters, although you should use a common prefix if your driver is the same class of device as other drivers. For example, drivers for serial devices, such as modems, could use the common prefix COM, even though other drivers might already be using that prefix. Your driver can distinguish itself from other drivers by using a different index.

The prefix serves two purposes. First, the prefix identifies all possible device file names that can access the stream interface driver. Second, the prefix tells the operating system what entry-point file names to expect in the stream interface DLL. For example, to implement a device driver for a PC Card pager, you could choose PGR as the three-letter prefix, which in turn would dictate entry-point names, such as PGR_Init, PGR_IOControl, and so on.

The prefix is stored in a registry value called Prefix, which is located within the key for the driver. Typically, the setup utility that installs a driver creates this registry value, along with other values that the driver needs. If the Prefix subkey does not exist, then there must be initialization and de-initialization entry points.

The index differentiates similar devices that the stream interface manages. The index is the digit that follows the prefix. By default, Device Manager indexes logically from 1 through 9, with 1 corresponding to the first device file name. If you require a tenth device file name, use 0 as the index.

If you must number your device file names starting at an index other than 1, specify a starting index in a registry value called Index within the registry key for your driver. This is often necessary if your stream interface driver serves a device that should use a common prefix, such as COM. For example, COM1:, COM2:, and COM3: usually correspond to built-in serial port hardware. If your driver is for a serial device, such as a packet-radio modem, it should appear as a COM port because modem software often assumes that modems are connected to COM ports. You could specify an Index value of 4 to differentiate your serial device from ones that are built into the hardware.

If you specify Index, rather than letting Device Manager assign indexes, by default, your driver will support only one device because Device Manager can register only one device file name. If you need to specify Index but need more than one device file name, you have two options. The initialization function can register additional device file names with the ActivateDeviceEx function, or the setup utility can create additional sets of registry keys, each with a different index, when your driver is installed.

Accesses to device drivers in the $device and $bus namespaces are automatically routed to the CreateFile entry point registered with RegisterAFSEx.

Device handles allow direct requests to the bus driver. For example, a control panel application might want to unload a device driver or force the bus driver to re-enumerate its child devices.

Calls to CreateFile implicitly call the device driver's XXX_Open (Device Manager) function. Device Manager can notify the driver that a particular handle will be used for device-level operations by adding a bit to the access rights mask passed into the driver's XXX_Init (Device Manager) function. This bit is added based on the namespace used to open the handle and cannot be one of the parameters to CreateFile. For reference, the driver can associate the access bit with the open data it returns from its XXX_Open function when processing other APIs.

The following table shows how to obtain a device handle or a file handle.

All three device paths might be implemented by the same driver. Paths 1 and 2 are equivalent. Path 3 can be used for power management, but not for data traffic.

The appropriate method for determining which devices support the new handle is to rely on advertised interfaces. A bus driver can advertise a specified GUID to indicate that the bus driver supports unloading and reloading drivers. A bus driver can also advertise another GUID to indicate that the bus driver supports power management on child devices. Similarly, a new GUID might indicate that Power Manager IOCTLs should use device handles.

Reference

Concepts

Other Resources