Win32 API 日本語リファレンス
ホームStorage.FileSystem › DefineDosDeviceW

DefineDosDeviceW

関数
MS-DOSデバイス名とパスのマッピングを定義または削除する。
DLLKERNEL32.dll文字セットUnicode (-W)呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

// KERNEL32.dll  (Unicode / -W)
#include <windows.h>

BOOL DefineDosDeviceW(
    DEFINE_DOS_DEVICE_FLAGS dwFlags,
    LPCWSTR lpDeviceName,
    LPCWSTR lpTargetPath   // optional
);

パラメーター

名前方向説明
dwFlagsDEFINE_DOS_DEVICE_FLAGSin

DefineDosDevice 関数の動作を制御する側面を指定します。このパラメーターには、次の値のうち 1 つ以上を指定できます。

意味
DDD_EXACT_MATCH_ON_REMOVE
0x00000004
この値を DDD_REMOVE_DEFINITION と共に指定すると、関数は完全一致を使用して削除するマッピングを判断します。自分で定義していないものを削除しないようにするには、この値を使用してください。
DDD_NO_BROADCAST_SYSTEM
0x00000008
WM_SETTINGCHANGE メッセージをブロードキャストしません。既定では、このメッセージはシェルおよびアプリケーションに変更を通知するためにブロードキャストされます。
DDD_RAW_TARGET_PATH
0x00000001
lpTargetPath 文字列をそのまま使用します。指定しない場合は、MS-DOS パスからパスへ変換されます。
DDD_REMOVE_DEFINITION
0x00000002
指定したデバイスの指定した定義を削除します。どの定義を削除するかを判断するため、関数はデバイスのマッピング一覧をたどり、このデバイスに関連付けられた各マッピングのプレフィックスに対して lpTargetPath が一致するものを探します。最初に一致したマッピングが削除され、関数は処理を終了します。

lpTargetPathNULL または NULL 文字列へのポインターである場合、関数はそのデバイスに関連付けられた最初のマッピングを削除し、最後にプッシュされたものをポップします。ポップする対象が残っていない場合は、デバイス名が削除されます。

この値が指定されていない場合、lpTargetPath パラメーターが指す文字列がこのデバイスの新しいマッピングになります。

lpDeviceNameLPCWSTRin関数が定義、再定義、または削除するデバイスを指定する MS-DOS デバイス名文字列へのポインターです。ドライブ文字を定義、再定義、または削除する場合を除き、デバイス名文字列の末尾の文字をコロンにしてはなりません。たとえば、ドライブ C は文字列 "C:" になります。いかなる場合も末尾のバックスラッシュ (\) は使用できません。
lpTargetPathLPCWSTRinoptionalこのデバイスを実装するパス文字列へのポインターです。この文字列は MS-DOS パス文字列ですが、DDD_RAW_TARGET_PATH フラグが指定されている場合は通常のパス文字列になります。

戻り値の型: BOOL

公式ドキュメント

MS-DOS デバイス名を定義、再定義、または削除します。(DefineDosDeviceW)

戻り値

関数が成功した場合、戻り値は 0 以外の値になります。

関数が失敗した場合、戻り値は 0 になります。詳細なエラー情報を取得するには、GetLastError を呼び出してください。

解説(Remarks)

MS-DOS デバイス名は、オブジェクト名前空間内にジャンクションとして格納されます。MS-DOS パスを対応するパスに変換するコードは、これらのジャンクションを使用して MS-DOS デバイスおよびドライブ文字をマッピングします。DefineDosDevice 関数を使用すると、アプリケーションは MS-DOS デバイス名前空間を実装するために使用されるジャンクションを変更できます。

特定の MS-DOS デバイス名の現在のマッピングを取得したり、システムが認識しているすべての MS-DOS デバイスの一覧を取得したりするには、QueryDosDevice 関数を使用してください。

再起動後も保持され、ネットワーク共有ではないドライブ文字の割り当てを定義するには、SetVolumeMountPoint 関数を使用してください。マウントするボリュームに既にドライブ文字が割り当てられている場合は、DeleteVolumeMountPoint 関数を使用して割り当てを削除してください。

システム起動時に定義されたドライブ文字およびデバイス名は、ユーザーが管理者でない限り、再定義および削除から保護されます。

Windows XP 以降、この関数は、"LocalSystem" コンテキストで実行されていない呼び出し元に対して、その呼び出し元自身のローカル MS-DOS デバイス名前空間にデバイス名を作成します。呼び出し元が "LocalSystem" コンテキストで実行されている場合、関数はグローバル MS-DOS デバイス名前空間にデバイス名を作成します。詳細については、Defining an MS DOS Device Name および File Names, Paths, and Namespaces を参照してください。

Windows 8 および Windows Server 2012 では、この関数は次のテクノロジでサポートされています。

テクノロジ サポート
Server Message Block (SMB) 3.0 プロトコル いいえ
SMB 3.0 透過的フェールオーバー (TFO) いいえ
スケールアウト ファイル共有を使用した SMB 3.0 (SO) いいえ
クラスター共有ボリューム ファイル システム (CsvFS) いいえ
回復性ファイル システム (ReFS) いいえ

SMB はボリューム管理関数をサポートしていません。CsvFs の場合、新しい名前はクラスター内の他のノードに複製されません。

例については、Editing Drive Letter Assignments を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// KERNEL32.dll  (Unicode / -W)
#include <windows.h>

BOOL DefineDosDeviceW(
    DEFINE_DOS_DEVICE_FLAGS dwFlags,
    LPCWSTR lpDeviceName,
    LPCWSTR lpTargetPath   // optional
);
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern bool DefineDosDeviceW(
    uint dwFlags,   // DEFINE_DOS_DEVICE_FLAGS
    [MarshalAs(UnmanagedType.LPWStr)] string lpDeviceName,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] string lpTargetPath   // LPCWSTR optional
);
<DllImport("KERNEL32.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function DefineDosDeviceW(
    dwFlags As UInteger,   ' DEFINE_DOS_DEVICE_FLAGS
    <MarshalAs(UnmanagedType.LPWStr)> lpDeviceName As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> lpTargetPath As String   ' LPCWSTR optional
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function
' dwFlags : DEFINE_DOS_DEVICE_FLAGS
' lpDeviceName : LPCWSTR
' lpTargetPath : LPCWSTR optional
Declare PtrSafe Function DefineDosDeviceW Lib "kernel32" ( _
    ByVal dwFlags As Long, _
    ByVal lpDeviceName As LongPtr, _
    ByVal lpTargetPath As LongPtr) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

DefineDosDeviceW = ctypes.windll.kernel32.DefineDosDeviceW
DefineDosDeviceW.restype = wintypes.BOOL
DefineDosDeviceW.argtypes = [
    wintypes.DWORD,  # dwFlags : DEFINE_DOS_DEVICE_FLAGS
    wintypes.LPCWSTR,  # lpDeviceName : LPCWSTR
    wintypes.LPCWSTR,  # lpTargetPath : LPCWSTR optional
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
DefineDosDeviceW = Fiddle::Function.new(
  lib['DefineDosDeviceW'],
  [
    -Fiddle::TYPE_INT,  # dwFlags : DEFINE_DOS_DEVICE_FLAGS
    Fiddle::TYPE_VOIDP,  # lpDeviceName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # lpTargetPath : LPCWSTR optional
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"
#[link(name = "kernel32")]
extern "system" {
    fn DefineDosDeviceW(
        dwFlags: u32,  // DEFINE_DOS_DEVICE_FLAGS
        lpDeviceName: *const u16,  // LPCWSTR
        lpTargetPath: *const u16  // LPCWSTR optional
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern bool DefineDosDeviceW(uint dwFlags, [MarshalAs(UnmanagedType.LPWStr)] string lpDeviceName, [MarshalAs(UnmanagedType.LPWStr)] string lpTargetPath);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_DefineDosDeviceW' -Namespace Win32 -PassThru
# $api::DefineDosDeviceW(dwFlags, lpDeviceName, lpTargetPath)
#uselib "KERNEL32.dll"
#func global DefineDosDeviceW "DefineDosDeviceW" wptr, wptr, wptr
; DefineDosDeviceW dwFlags, lpDeviceName, lpTargetPath   ; 戻り値は stat
; dwFlags : DEFINE_DOS_DEVICE_FLAGS -> "wptr"
; lpDeviceName : LPCWSTR -> "wptr"
; lpTargetPath : LPCWSTR optional -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "KERNEL32.dll"
#cfunc global DefineDosDeviceW "DefineDosDeviceW" int, wstr, wstr
; res = DefineDosDeviceW(dwFlags, lpDeviceName, lpTargetPath)
; dwFlags : DEFINE_DOS_DEVICE_FLAGS -> "int"
; lpDeviceName : LPCWSTR -> "wstr"
; lpTargetPath : LPCWSTR optional -> "wstr"
; BOOL DefineDosDeviceW(DEFINE_DOS_DEVICE_FLAGS dwFlags, LPCWSTR lpDeviceName, LPCWSTR lpTargetPath)
#uselib "KERNEL32.dll"
#cfunc global DefineDosDeviceW "DefineDosDeviceW" int, wstr, wstr
; res = DefineDosDeviceW(dwFlags, lpDeviceName, lpTargetPath)
; dwFlags : DEFINE_DOS_DEVICE_FLAGS -> "int"
; lpDeviceName : LPCWSTR -> "wstr"
; lpTargetPath : LPCWSTR optional -> "wstr"
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	kernel32 = windows.NewLazySystemDLL("KERNEL32.dll")
	procDefineDosDeviceW = kernel32.NewProc("DefineDosDeviceW")
)

// dwFlags (DEFINE_DOS_DEVICE_FLAGS), lpDeviceName (LPCWSTR), lpTargetPath (LPCWSTR optional)
r1, _, err := procDefineDosDeviceW.Call(
	uintptr(dwFlags),
	uintptr(unsafe.Pointer(windows.StringToUTF16Ptr(lpDeviceName))),
	uintptr(unsafe.Pointer(windows.StringToUTF16Ptr(lpTargetPath))),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // BOOL
function DefineDosDeviceW(
  dwFlags: DWORD;   // DEFINE_DOS_DEVICE_FLAGS
  lpDeviceName: PWideChar;   // LPCWSTR
  lpTargetPath: PWideChar   // LPCWSTR optional
): BOOL; stdcall;
  external 'KERNEL32.dll' name 'DefineDosDeviceW';
result := DllCall("KERNEL32\DefineDosDeviceW"
    , "UInt", dwFlags   ; DEFINE_DOS_DEVICE_FLAGS
    , "WStr", lpDeviceName   ; LPCWSTR
    , "WStr", lpTargetPath   ; LPCWSTR optional
    , "Int")   ; return: BOOL
●DefineDosDeviceW(dwFlags, lpDeviceName, lpTargetPath) = DLL("KERNEL32.dll", "bool DefineDosDeviceW(dword, char*, char*)")
# 呼び出し: DefineDosDeviceW(dwFlags, lpDeviceName, lpTargetPath)
# dwFlags : DEFINE_DOS_DEVICE_FLAGS -> "dword"
# lpDeviceName : LPCWSTR -> "char*"
# lpTargetPath : LPCWSTR optional -> "char*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
# ※-W(Unicode)関数。なでしこ1はANSIのため -A 版の利用を推奨。
const std = @import("std");

extern "kernel32" fn DefineDosDeviceW(
    dwFlags: u32, // DEFINE_DOS_DEVICE_FLAGS
    lpDeviceName: [*c]const u16, // LPCWSTR
    lpTargetPath: [*c]const u16 // LPCWSTR optional
) callconv(std.os.windows.WINAPI) i32;
// Unicode(-W): UTF-16LE のヌル終端バッファ([*c]const u16)を渡す。
proc DefineDosDeviceW(
    dwFlags: uint32,  # DEFINE_DOS_DEVICE_FLAGS
    lpDeviceName: WideCString,  # LPCWSTR
    lpTargetPath: WideCString  # LPCWSTR optional
): int32 {.importc: "DefineDosDeviceW", stdcall, dynlib: "KERNEL32.dll".}
# Unicode(-W): WideCString は newWideCString("...") で生成。
pragma(lib, "kernel32");
extern(Windows)
int DefineDosDeviceW(
    uint dwFlags,   // DEFINE_DOS_DEVICE_FLAGS
    const(wchar)* lpDeviceName,   // LPCWSTR
    const(wchar)* lpTargetPath   // LPCWSTR optional
);
ccall((:DefineDosDeviceW, "KERNEL32.dll"), stdcall, Int32,
      (UInt32, Cwstring, Cwstring),
      dwFlags, lpDeviceName, lpTargetPath)
# dwFlags : DEFINE_DOS_DEVICE_FLAGS -> UInt32
# lpDeviceName : LPCWSTR -> Cwstring
# lpTargetPath : LPCWSTR optional -> Cwstring
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
# Unicode(-W): Cwstring には transcode(UInt16, "...") 等で UTF-16 を渡す。
local ffi = require("ffi")
ffi.cdef[[
int32_t DefineDosDeviceW(
    uint32_t dwFlags,
    const uint16_t* lpDeviceName,
    const uint16_t* lpTargetPath);
]]
local kernel32 = ffi.load("kernel32")
-- kernel32.DefineDosDeviceW(dwFlags, lpDeviceName, lpTargetPath)
-- dwFlags : DEFINE_DOS_DEVICE_FLAGS
-- lpDeviceName : LPCWSTR
-- lpTargetPath : LPCWSTR optional
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
-- Unicode(-W): uint16_t* には UTF-16LE のバッファ(ffi.new("uint16_t[?]", ...))を渡す。
const koffi = require('koffi');
const lib = koffi.load('KERNEL32.dll');
const DefineDosDeviceW = lib.func('__stdcall', 'DefineDosDeviceW', 'int32_t', ['uint32_t', 'str16', 'str16']);
// DefineDosDeviceW(dwFlags, lpDeviceName, lpTargetPath)
// dwFlags : DEFINE_DOS_DEVICE_FLAGS -> 'uint32_t'
// lpDeviceName : LPCWSTR -> 'str16'
// lpTargetPath : LPCWSTR optional -> 'str16'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("KERNEL32.dll", {
  DefineDosDeviceW: { parameters: ["u32", "buffer", "buffer"], result: "i32" },
});
// lib.symbols.DefineDosDeviceW(dwFlags, lpDeviceName, lpTargetPath)
// dwFlags : DEFINE_DOS_DEVICE_FLAGS -> "u32"
// lpDeviceName : LPCWSTR -> "buffer"
// lpTargetPath : LPCWSTR optional -> "buffer"
// 文字列は "buffer"。Unicode(-W) は new TextEncoder() ではなく UTF-16LE のバイト列(末尾に \x00\x00)を Uint8Array で渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int32_t DefineDosDeviceW(
    uint32_t dwFlags,
    const uint16_t* lpDeviceName,
    const uint16_t* lpTargetPath);
C, "KERNEL32.dll");
// $ffi->DefineDosDeviceW(dwFlags, lpDeviceName, lpTargetPath);
// dwFlags : DEFINE_DOS_DEVICE_FLAGS
// lpDeviceName : LPCWSTR
// lpTargetPath : LPCWSTR optional
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Kernel32 extends StdCallLibrary {
    Kernel32 INSTANCE = Native.load("kernel32", Kernel32.class, W32APIOptions.UNICODE_OPTIONS);
    boolean DefineDosDeviceW(
        int dwFlags,   // DEFINE_DOS_DEVICE_FLAGS
        WString lpDeviceName,   // LPCWSTR
        WString lpTargetPath   // LPCWSTR optional
    );
}
// Unicode(-W): WString(入力)/char[](出力)で UTF-16 をマーシャリング。
@[Link("kernel32")]
lib LibKERNEL32
  fun DefineDosDeviceW = DefineDosDeviceW(
    dwFlags : UInt32,   # DEFINE_DOS_DEVICE_FLAGS
    lpDeviceName : UInt16*,   # LPCWSTR
    lpTargetPath : UInt16*   # LPCWSTR optional
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef DefineDosDeviceWNative = Int32 Function(Uint32, Pointer<Utf16>, Pointer<Utf16>);
typedef DefineDosDeviceWDart = int Function(int, Pointer<Utf16>, Pointer<Utf16>);
final DefineDosDeviceW = DynamicLibrary.open('KERNEL32.dll')
    .lookupFunction<DefineDosDeviceWNative, DefineDosDeviceWDart>('DefineDosDeviceW');
// dwFlags : DEFINE_DOS_DEVICE_FLAGS -> Uint32
// lpDeviceName : LPCWSTR -> Pointer<Utf16>
// lpTargetPath : LPCWSTR optional -> Pointer<Utf16>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function DefineDosDeviceW(
  dwFlags: DWORD;   // DEFINE_DOS_DEVICE_FLAGS
  lpDeviceName: PWideChar;   // LPCWSTR
  lpTargetPath: PWideChar   // LPCWSTR optional
): BOOL; stdcall;
  external 'KERNEL32.dll' name 'DefineDosDeviceW';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "DefineDosDeviceW"
  c_DefineDosDeviceW :: Word32 -> CWString -> CWString -> IO CInt
-- dwFlags : DEFINE_DOS_DEVICE_FLAGS -> Word32
-- lpDeviceName : LPCWSTR -> CWString
-- lpTargetPath : LPCWSTR optional -> CWString
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let definedosdevicew =
  foreign "DefineDosDeviceW"
    (uint32_t @-> (ptr uint16_t) @-> (ptr uint16_t) @-> returning int32_t)
(* dwFlags : DEFINE_DOS_DEVICE_FLAGS -> uint32_t *)
(* lpDeviceName : LPCWSTR -> (ptr uint16_t) *)
(* lpTargetPath : LPCWSTR optional -> (ptr uint16_t) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library kernel32 (t "KERNEL32.dll"))
(cffi:use-foreign-library kernel32)

(cffi:defcfun ("DefineDosDeviceW" define-dos-device-w :convention :stdcall) :int32
  (dw-flags :uint32)   ; DEFINE_DOS_DEVICE_FLAGS
  (lp-device-name (:string :encoding :utf-16le))   ; LPCWSTR
  (lp-target-path (:string :encoding :utf-16le)))   ; LPCWSTR optional
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $DefineDosDeviceW = Win32::API::More->new('KERNEL32',
    'BOOL DefineDosDeviceW(DWORD dwFlags, LPCWSTR lpDeviceName, LPCWSTR lpTargetPath)');
# my $ret = $DefineDosDeviceW->Call($dwFlags, $lpDeviceName, $lpTargetPath);
# dwFlags : DEFINE_DOS_DEVICE_FLAGS -> DWORD
# lpDeviceName : LPCWSTR -> LPCWSTR
# lpTargetPath : LPCWSTR optional -> LPCWSTR
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。
# Unicode(-W): LPCWSTR/LPWSTR は Win32::API が UTF-16 変換を行う。

関連項目

文字セット違い
公式の関連項目
使用する型