DefineDosDevice

The DefineDosDevice function defines, redefines, or deletes MS-DOS device names.

BOOL DefineDosDevice(
  DWORD dwFlags,         // options
  LPCTSTR lpDeviceName,  // device name
  LPCTSTR lpTargetPath   // path string
);

Parameters

dwFlags

[in] Specifies several controllable aspects of the DefineDosDevice function. This parameter can be one or more of the following values.

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, 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

[in] Pointer 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. In no case is a trailing backslash allowed.

lpTargetPath

[in] Pointer to a path string that will implement this device. The string is an MS-DOS path string unless the DDD_RAW_TARGET_PATH flag is specified, in which case this string is a path string.

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

MS-DOS device names are stored as symbolic links in the object name space. The code that converts an MS-DOS path into a corresponding path uses these symbolic links to map MS-DOS devices and drive letters. The DefineDosDevice function provides a mechanism whereby an application can modify the symbolic links used to implement the MS-DOS device name space.

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. After it is defined, an MS-DOS device name remains visible to all processes until either it is explicitly removed or the system restarts.

Windows 2000: To define a drive letter assignment that is persistent across boots and not a network share, use the SetVolumeMountPoint function. If the volume to be mounted already has a drive letter assigned to it, use the DeleteVolumeMountPoint function to remove the assignment.

Note  Drive letters and device names defined at system boot time are protected from redefinition and deletion unless the user is an administrator.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

File I/O Overview, File I/O Functions, DeleteVolumeMountPoint, QueryDosDevice, SetVolumeMountPoint