DefineDosDevice
The DefineDosDevice
function lets an application define, redefine, or delete MS-DOS device names.
MS-DOS device
names are stored as symbolic links in the object name space in 32-bit versions
of Windows. The code that converts an MS-DOS path into a corresponding path in
32-bit versions of Windows uses these symbolic links to map MS-DOS devices and
drive letters. The DefineDosDevice function provides a mechanism whereby
a Win32-based application can modify the symbolic links used to implement the
MS-DOS device name space.
BOOL DefineDosDevice(
|
DWORD dwFlags, |
// flags specifying
aspects of device definition |
|
LPCTSTR lpDeviceName, |
// pointer to
MS-DOS device name string |
|
LPCTSTR lpTargetPath |
// pointer to
MS-DOS or path string for 32-bit Windows
|
|
); |
|
Parameters
dwFlags
Specifies
several controllable aspects of the DefineDosDevice function. One or
more of the following values can be used:
|
Value |
Meaning |
|
DDD_RAW_TARGET_PATH |
If this
value is specified, the function does not convert the lpTargetPath
string from an MS-DOS path to a path for a 32-bit version of Windows, but
takes it as is. |
|
DDD_REMOVE_DEFINITION |
If this
value is specified, the function removes the specified definition for the
specified device. To determine which definition to remove, the function walks
the list of mappings for the device, looking for a match of lpTargetPath
against a prefix of each mapping associated with this device. The first
mapping that matches is the one removed, and then the function returns. If lpTargetPath
is NULL or a pointer to a NULL string, the function will remove the first
mapping associated with the device and pop the most recent one pushed. If
there is nothing left to pop, the device name will be removed. If this
value is NOT specified, the string pointed to by the lpTargetPath
parameter will become the new mapping for this device. |
|
DDD_EXACT_MATCH_ON_REMOVE |
If this
value is specified along with DDD_REMOVE_DEFINITION, the function will use an
exact match to determine which mapping to remove. Use this value to insure
that you do not delete something that you did not define. |
lpDeviceName
Points to an
MS-DOS device name string specifying the device the function is defining,
redefining, or deleting. The device name string must not have a trailing colon,
unless a drive letter (C or D, for example) is being defined, redefined, or
deleted.
lpTargetPath
Points to a
path string that will implement this device. Points to an MS-DOS path string
unless the DDD_RAW_TARGET_PATH flag is specified, in which case this parameter
points to a path string for a 32-bit version of Windows.
Return Values
If the
function succeeds, the return value is nonzero.
If the
function fails, the return value is zero. To get extended error information,
call GetLastError.
Remarks
As stated in
this function s introductory summary, the DefineDosDevice function
provides a means whereby a Win32-based application can create and modify the
symbolic links used to implement the MS-DOS device namespace. To retrieve the
current mapping for a particular MS-DOS device name or to obtain a list of all
MS-DOS devices known to the system, use the QueryDosDevice function.
MS-DOS Device
names are global. Once defined, an MS-DOS device name remains visible to all
processes until either it is explicitly removed or the system reboots.
Note that
drive letters and device names defined at system boot time are protected from
redefinition and deletion unless a user is running in administrative mode
(ADMIN).
See Also