Device File Names
Other versions of this page are also available for the following:
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
Applications can access peripheral devices through file system functions, such as CreateFile. The file I/O operations are redirected to the stream interface.
The following table shows descriptions and examples for the three device namespaces.
| Namespace description | Example |
|---|---|
Three letter prefix, followed by a number between 0 and 9, followed by a colon. |
"LPT2:" |
$bus mount point, followed by the bus name, bus number, device number, and function number. |
"\$bus\PCMCIA_0_0_0" |
$device mount point, followed by a three letter prefix representing the device, followed by a number. |
"\$device\COM7" |
In the example, COM7 is device 0, function 0 on PCMCIA bus 0. CreateFile can accept any of these names. Each name space returns handles with different properties.
The namespaces containing mount points support more than 10 instances of a device with the same three letter prefix. For example, COM23 can represent serial port 23.
Device File Name Prefixes
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.
Device File Name Indexes
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.
Device Handle and File Handle Operations
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.
| First parameter to CreateFile | Description |
|---|---|
"COM7:" |
Returns a normal file handle to the device. This is the legacy naming convention. |
"\$device\COM7" |
Returns a normal file handle, which might be for a device that cannot be named using the legacy naming convention. |
"\$bus\PCMCIA_0_0_0" |
Returns a device handle to device 0, function 0 on PCMCIA bus 0. Although this handle can be manipulated using the same APIs as a normal file handle, the operations it enables might be different and access to these handles might be secured differently by the OS. |
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.
Determining Device Handle Support
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.
See Also
Reference
Concepts
Device Interfaces
Resolving Race Conditions in Device Drivers