Determing the correct symbolic link to pass to CreateFile.

0 Likes

Problem:

I want to open my driver from the user application. I know I need to call CreateFile with the symbolic name of the driver. How do I know what that will be.

Resolution:

Understanding NT Symbolic Links

Many device drivers communicate with applications. Typically, an application uses CreateFile to open a device, and then uses ReadFile, WriteFile, and DeviceIoControl to exchange information with the driver. The name that an application passes to CreateFile is neither the name of the driver nor the name of the device object to be opened. Instead, it is the name of a symbolic link to the device object, with a special prefix to designate it as such.

To understand what a symbolic link is, you need to know that Windows NT maintains a hierarchical directory of objects. Device objects are just one type of object in the hierarchy, and reside in the \Device branch of the object directory. For example, \Device\Serial0 names the device object created by SERIAL.SYS to control COM1. The system uses the object directory structure as a repository for information that is common to a variety of different kinds of objects, such as security data and reference counts.

A symbolic link is a special type of object whose purpose is to refer to another object in the object directory. The system stores symbolic links to devices that applications may open in branch \?? of the object directory. Prior to NT 4.0, the branch was named \DosDevices, which is still valid. Each symbolic link contains a string that specifies another object in the hierarchy. Most often, that object is a device object. For example, \??\COM1 refers to \Device\Serial0.

Sometimes a symbolic link refers to another symbolic link. For example, \??\PRN is an alias for \??\LPT1.

When calling CreateFile, an application tells the system to search for a device in the \?? branch of the object directory by prefixing the symbolic link name with the special string "\\.\". In C/C , the quoted string looks like "\\\\.\\". For example, if the symbolic link name is MyDevice0, then the name passed to CreateFile is "\\\\.\\MyDevice0". An application can't open a device for which there is no symbolic link in the \?? branch.

You can download symlinks.zip (68kb), a very simple utility program that quickly shows you the symbolic links currently defined on your system. To view the entire object directory, get Winobj from the NT Internals web site.

Creating Symbolic Links

There are three ways to create symbolic links:

By adding special registry entries under \HKLM\CurrentControlSet\Control\Session Manager\DOS. This approach is rarely used, and not recommended.

By calling DefineDosDevice from an application. This API is documented in the Win32 SDK.

By calling IoCreateSymbolicLink or IoCreateUnprotectedSymoblicLink from a kernel mode driver.

If you are using DriverWorks, the constructor for class KDevice automatically creates the symbolic link if a link name is supplied. The link name is the third parameter to the constructor of KDevice. Here's an example, the constructor for class RamdiskDevice, which implements a ram disk:

RamdiskDevice::RamdiskDevice(

PCWSTR DriveLetter,

ULONG nRootDirs,

ULONG nSectorsPerCluster,

ULONG DiskSize

) :

KDevice(

L"RAMDISK0", // Device name

FILE_DEVICE_VIRTUAL_DISK,

DriveLetter, // Symbolic Link name

FILE_REMOVABLE_MEDIA,

DO_DIRECT_IO

),

m_Image(NULL),

m_OpenCount(0)

{

. . .

Note: In the above that string DriveLetter passed to the constructor of RamdiskDevice becomes the symbolic link to the device object. In other words, the device is known to applications by its drive letter, not by "RAMDISK0", its actual name. DriverWorks™ automatically prefixes \Device and \?? to the device and link names, respectively.

Old KB# 11296
Comment List
Anonymous
Related Discussions
Recommended