16.9.1 Making a Named Device Object Visible to User-mode Applications

To make a new device accessible from the Win32 subsystem, there must be a symbolic link object in the NT object namespace \??. Such a symbolic link object maps the NT generic name for a driver’s device object to the corresponding Win32 logical name for the same device. There are two alternative techniques to set up such a symbolic link:

• Use regedt32 (or a setup utility) to add a value entry under CurrentControlSet\Control\Session Manager\DOS equating the NT device object name to the Win32 logical name. For example:

      FaxDev:REG_SZ:\Device\Fax0 
   

• Set up the symbolic link when the driver initializes by calling IoCreateSymbolicLink.

When such a symbolic link object has been created in \??, a Win32 application or subsystem-level driver can get a handle for the file object that represents the \Device\Fax0 device object using \\ .\FaxDev as a parameter.

Note that a system administrator or end user must be very knowledgeable about using regedt32 and about the DOS Devices key in the registry in order to use the first technique of “installing” a new Win32 device in the registry.

Using regedt32 creates a nonvolatile subkey under \Session Manager\DOS Devices in the registry. As mentioned in Section 16.9, the Session Manager creates a symbolic link object in the \?? object namespace for each subkey. To the Session Manager, the creation of these symbolic link objects requires only that it process the value entries of the DOS Devices subkeys. Consequently, it can create a symbolic link for a device that is not actually available for user-mode I/O requests. For example, if a device driver fails its initialization or is unloaded dynamically, the Session Manager does not remove the corresponding DOS Devices subkey in the registry nor the corresponding symbolic link object in the \?? namespace.

For developers of new NT drivers, relying on the first technique for setting up a new device and retail driver can be very costly in terms of customer support.

Consequently, most NT driver writer are likely to prefer the second technique for making a new device visible to Win32 applications and end users. For example, the driver of a new fax device might do the following in order to make its device accessible to I/O requests from Win32 applications:

1. The driver forms a full path name string, including the \?? as the root of the path, for the user-visible name, such as FaxDev, and another full path name string for the corresponding device object name, such as \Device\Fax0. Each path name string must be a driver-buffered, zero-terminated Unicode string.

2. The driver calls IoCreateSymbolicLink with the strings that it set up in Step 1. (A parallel or serial driver should call IoCreateUnprotectedSymbolicLink, rather than IoCreateSymbolicLink.)

While using the first technique to make a driver’s device visible within the Win32 subsystem environment is a simple way to get an under-development NT driver loaded so it can be debugged and tested, retail drivers should create symbolic links between the NT names for their device objects and the corresponding Win32 logical device names in the NT object namespace \??.

Any NT driver that has an Unload routine is responsible for releasing the symbolic link objects it has created. Such a driver’s Unload routine must call IoDeleteSymbolicLink for each symbolic link that the DriverEntry routine set up.