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

SetFileShortNameW

関数
開いているファイルの短い名前(8.3名)を設定する(Unicode版)。
DLLKERNEL32.dll文字セットUnicode (-W)呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

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

BOOL SetFileShortNameW(
    HANDLE hFile,
    LPCWSTR lpShortName
);

パラメーター

名前方向説明
hFileHANDLEin

ファイルへのハンドル。ファイルは DELETE アクセス権、および FILE_FLAG_BACKUP_SEMANTICS ファイル属性を指定して開く必要があります。

メモ

Windows 10 バージョン 1903 より前では、ファイルは GENERIC_ALL アクセス権、または GENERIC_WRITE|DELETE アクセス権のいずれか、および FILE_FLAG_BACKUP_SEMANTICS ファイル属性を指定して開く必要がありました。

lpShortNameLPCWSTRin

ファイルの短いファイル名を指定する文字列へのポインター。

空 (長さ 0) の文字列を指定すると、hFile パラメーターで指定したファイルに短いファイル名が存在する場合はそれが削除されます。短いファイル名が存在しない場合、関数は何も行わず、成功を返します。

Windows Server 2008、Windows Vista、Windows Server 2003 および Windows XP: この動作はサポートされていません。このパラメーターには 1 文字以上の有効な文字列を指定する必要があります。

戻り値の型: BOOL

公式ドキュメント

指定したファイルの短いファイル名を設定します。ファイルは NTFS ファイルシステムのボリューム上にある必要があります。(Unicode)

戻り値

関数が成功すると、戻り値は 0 以外の値になります。

関数が失敗すると、戻り値は 0 になります。拡張エラー情報を取得するには、GetLastError を呼び出します。GetLastError は、この関数に固有の次のエラーコードのいずれかを返すことがあります。

戻り値 説明
ERROR_ALREADY_EXISTS 指定された短いファイル名が一意ではありません。
ERROR_INVALID_PARAMETER 指定されたファイルが大文字と小文字を区別するモードで開かれているか、指定された短いファイル名が無効です。

解説(Remarks)

メモ

Windows 10 バージョン 1903 より前では、この関数を呼び出すには SE_RESTORE_NAME 特権が必要でした。詳細については、Running with Special Privileges を参照してください。

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

テクノロジー サポート
Server Message Block (SMB) 3.0 プロトコル はい
SMB 3.0 Transparent Failover (TFO) いいえ
SMB 3.0 with Scale-out File Shares (SO) いいえ
Cluster Shared Volume File System (CsvFS) はい
Resilient File System (ReFS) いいえ

SMB 3.0 は、継続的可用性機能を持つ共有上での短いファイル名をサポートしません。CsvFs では短いファイル名は推奨されません。

メモ

winbase.h ヘッダーは SetFileShortName を、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして定義しています。エンコーディング非依存のエイリアスを、エンコーディング非依存でないコードと混在させて使用すると、不整合が生じ、コンパイルエラーや実行時エラーの原因となることがあります。詳細については、Conventions for Function Prototypes を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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 SetFileShortNameW(
    HANDLE hFile,
    LPCWSTR lpShortName
);
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern bool SetFileShortNameW(
    IntPtr hFile,   // HANDLE
    [MarshalAs(UnmanagedType.LPWStr)] string lpShortName   // LPCWSTR
);
<DllImport("KERNEL32.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function SetFileShortNameW(
    hFile As IntPtr,   ' HANDLE
    <MarshalAs(UnmanagedType.LPWStr)> lpShortName As String   ' LPCWSTR
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function
' hFile : HANDLE
' lpShortName : LPCWSTR
Declare PtrSafe Function SetFileShortNameW Lib "kernel32" ( _
    ByVal hFile As LongPtr, _
    ByVal lpShortName 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

SetFileShortNameW = ctypes.windll.kernel32.SetFileShortNameW
SetFileShortNameW.restype = wintypes.BOOL
SetFileShortNameW.argtypes = [
    wintypes.HANDLE,  # hFile : HANDLE
    wintypes.LPCWSTR,  # lpShortName : LPCWSTR
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
SetFileShortNameW = Fiddle::Function.new(
  lib['SetFileShortNameW'],
  [
    Fiddle::TYPE_VOIDP,  # hFile : HANDLE
    Fiddle::TYPE_VOIDP,  # lpShortName : LPCWSTR
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"
#[link(name = "kernel32")]
extern "system" {
    fn SetFileShortNameW(
        hFile: *mut core::ffi::c_void,  // HANDLE
        lpShortName: *const u16  // LPCWSTR
    ) -> 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 SetFileShortNameW(IntPtr hFile, [MarshalAs(UnmanagedType.LPWStr)] string lpShortName);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_SetFileShortNameW' -Namespace Win32 -PassThru
# $api::SetFileShortNameW(hFile, lpShortName)
#uselib "KERNEL32.dll"
#func global SetFileShortNameW "SetFileShortNameW" wptr, wptr
; SetFileShortNameW hFile, lpShortName   ; 戻り値は stat
; hFile : HANDLE -> "wptr"
; lpShortName : LPCWSTR -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "KERNEL32.dll"
#cfunc global SetFileShortNameW "SetFileShortNameW" sptr, wstr
; res = SetFileShortNameW(hFile, lpShortName)
; hFile : HANDLE -> "sptr"
; lpShortName : LPCWSTR -> "wstr"
; BOOL SetFileShortNameW(HANDLE hFile, LPCWSTR lpShortName)
#uselib "KERNEL32.dll"
#cfunc global SetFileShortNameW "SetFileShortNameW" intptr, wstr
; res = SetFileShortNameW(hFile, lpShortName)
; hFile : HANDLE -> "intptr"
; lpShortName : LPCWSTR -> "wstr"
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	kernel32 = windows.NewLazySystemDLL("KERNEL32.dll")
	procSetFileShortNameW = kernel32.NewProc("SetFileShortNameW")
)

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

extern "kernel32" fn SetFileShortNameW(
    hFile: ?*anyopaque, // HANDLE
    lpShortName: [*c]const u16 // LPCWSTR
) callconv(std.os.windows.WINAPI) i32;
// Unicode(-W): UTF-16LE のヌル終端バッファ([*c]const u16)を渡す。
proc SetFileShortNameW(
    hFile: pointer,  # HANDLE
    lpShortName: WideCString  # LPCWSTR
): int32 {.importc: "SetFileShortNameW", stdcall, dynlib: "KERNEL32.dll".}
# Unicode(-W): WideCString は newWideCString("...") で生成。
pragma(lib, "kernel32");
extern(Windows)
int SetFileShortNameW(
    void* hFile,   // HANDLE
    const(wchar)* lpShortName   // LPCWSTR
);
ccall((:SetFileShortNameW, "KERNEL32.dll"), stdcall, Int32,
      (Ptr{Cvoid}, Cwstring),
      hFile, lpShortName)
# hFile : HANDLE -> Ptr{Cvoid}
# lpShortName : LPCWSTR -> Cwstring
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
# Unicode(-W): Cwstring には transcode(UInt16, "...") 等で UTF-16 を渡す。
local ffi = require("ffi")
ffi.cdef[[
int32_t SetFileShortNameW(
    void* hFile,
    const uint16_t* lpShortName);
]]
local kernel32 = ffi.load("kernel32")
-- kernel32.SetFileShortNameW(hFile, lpShortName)
-- hFile : HANDLE
-- lpShortName : LPCWSTR
-- 構造体/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 SetFileShortNameW = lib.func('__stdcall', 'SetFileShortNameW', 'int32_t', ['void *', 'str16']);
// SetFileShortNameW(hFile, lpShortName)
// hFile : HANDLE -> 'void *'
// lpShortName : LPCWSTR -> 'str16'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("KERNEL32.dll", {
  SetFileShortNameW: { parameters: ["pointer", "buffer"], result: "i32" },
});
// lib.symbols.SetFileShortNameW(hFile, lpShortName)
// hFile : HANDLE -> "pointer"
// lpShortName : LPCWSTR -> "buffer"
// 文字列は "buffer"。Unicode(-W) は new TextEncoder() ではなく UTF-16LE のバイト列(末尾に \x00\x00)を Uint8Array で渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int32_t SetFileShortNameW(
    void* hFile,
    const uint16_t* lpShortName);
C, "KERNEL32.dll");
// $ffi->SetFileShortNameW(hFile, lpShortName);
// hFile : HANDLE
// lpShortName : LPCWSTR
// 構造体/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 SetFileShortNameW(
        Pointer hFile,   // HANDLE
        WString lpShortName   // LPCWSTR
    );
}
// Unicode(-W): WString(入力)/char[](出力)で UTF-16 をマーシャリング。
@[Link("kernel32")]
lib LibKERNEL32
  fun SetFileShortNameW = SetFileShortNameW(
    hFile : Void*,   # HANDLE
    lpShortName : UInt16*   # LPCWSTR
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef SetFileShortNameWNative = Int32 Function(Pointer<Void>, Pointer<Utf16>);
typedef SetFileShortNameWDart = int Function(Pointer<Void>, Pointer<Utf16>);
final SetFileShortNameW = DynamicLibrary.open('KERNEL32.dll')
    .lookupFunction<SetFileShortNameWNative, SetFileShortNameWDart>('SetFileShortNameW');
// hFile : HANDLE -> Pointer<Void>
// lpShortName : LPCWSTR -> Pointer<Utf16>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function SetFileShortNameW(
  hFile: THandle;   // HANDLE
  lpShortName: PWideChar   // LPCWSTR
): BOOL; stdcall;
  external 'KERNEL32.dll' name 'SetFileShortNameW';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "SetFileShortNameW"
  c_SetFileShortNameW :: Ptr () -> CWString -> IO CInt
-- hFile : HANDLE -> Ptr ()
-- lpShortName : LPCWSTR -> CWString
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let setfileshortnamew =
  foreign "SetFileShortNameW"
    ((ptr void) @-> (ptr uint16_t) @-> returning int32_t)
(* hFile : HANDLE -> (ptr void) *)
(* lpShortName : LPCWSTR -> (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 ("SetFileShortNameW" set-file-short-name-w :convention :stdcall) :int32
  (h-file :pointer)   ; HANDLE
  (lp-short-name (:string :encoding :utf-16le)))   ; LPCWSTR
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $SetFileShortNameW = Win32::API::More->new('KERNEL32',
    'BOOL SetFileShortNameW(HANDLE hFile, LPCWSTR lpShortName)');
# my $ret = $SetFileShortNameW->Call($hFile, $lpShortName);
# hFile : HANDLE -> HANDLE
# lpShortName : LPCWSTR -> LPCWSTR
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。
# Unicode(-W): LPCWSTR/LPWSTR は Win32::API が UTF-16 変換を行う。

関連項目

文字セット違い