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

SetFileShortNameA

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

シグネチャ

// KERNEL32.dll  (ANSI / -A)
#include <windows.h>

BOOL SetFileShortNameA(
    HANDLE hFile,
    LPCSTR lpShortName
);

パラメーター

名前方向説明
hFileHANDLEin

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

メモ

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

lpShortNameLPCSTRin

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

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

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

戻り値の型: BOOL

公式ドキュメント

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

戻り値

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

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

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

解説(Remarks)

メモ

Windows 10 バージョン 1903 より前では、この関数を呼び出すために SE_RESTORE_NAME 特権が必要でした。詳細については、特殊な特権を使用した実行 を参照してください。

Windows 8 および Windows Server 2012 では、この関数は次の技術でサポートされています。

技術 サポート
Server Message Block (SMB) 3.0 プロトコル あり
SMB 3.0 透過的フェールオーバー (TFO) なし
SMB 3.0 スケールアウトファイル共有 (SO) なし
クラスター共有ボリュームファイルシステム (CsvFS) あり
回復性ファイルシステム (ReFS) なし

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

メモ

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

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

各言語での呼び出し定義

// KERNEL32.dll  (ANSI / -A)
#include <windows.h>

BOOL SetFileShortNameA(
    HANDLE hFile,
    LPCSTR lpShortName
);
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", CharSet = CharSet.Ansi, SetLastError = true, ExactSpelling = true)]
static extern bool SetFileShortNameA(
    IntPtr hFile,   // HANDLE
    [MarshalAs(UnmanagedType.LPStr)] string lpShortName   // LPCSTR
);
<DllImport("KERNEL32.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function SetFileShortNameA(
    hFile As IntPtr,   ' HANDLE
    <MarshalAs(UnmanagedType.LPStr)> lpShortName As String   ' LPCSTR
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function
' hFile : HANDLE
' lpShortName : LPCSTR
Declare PtrSafe Function SetFileShortNameA Lib "kernel32" ( _
    ByVal hFile As LongPtr, _
    ByVal lpShortName As String) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

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

lib = Fiddle.dlopen('KERNEL32.dll')
SetFileShortNameA = Fiddle::Function.new(
  lib['SetFileShortNameA'],
  [
    Fiddle::TYPE_VOIDP,  # hFile : HANDLE
    Fiddle::TYPE_VOIDP,  # lpShortName : LPCSTR
  ],
  Fiddle::TYPE_INT)
#[link(name = "kernel32")]
extern "system" {
    fn SetFileShortNameA(
        hFile: *mut core::ffi::c_void,  // HANDLE
        lpShortName: *const u8  // LPCSTR
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", CharSet = CharSet.Ansi, SetLastError = true)]
public static extern bool SetFileShortNameA(IntPtr hFile, [MarshalAs(UnmanagedType.LPStr)] string lpShortName);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_SetFileShortNameA' -Namespace Win32 -PassThru
# $api::SetFileShortNameA(hFile, lpShortName)
#uselib "KERNEL32.dll"
#func global SetFileShortNameA "SetFileShortNameA" sptr, sptr
; SetFileShortNameA hFile, lpShortName   ; 戻り値は stat
; hFile : HANDLE -> "sptr"
; lpShortName : LPCSTR -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "KERNEL32.dll"
#cfunc global SetFileShortNameA "SetFileShortNameA" sptr, str
; res = SetFileShortNameA(hFile, lpShortName)
; hFile : HANDLE -> "sptr"
; lpShortName : LPCSTR -> "str"
; BOOL SetFileShortNameA(HANDLE hFile, LPCSTR lpShortName)
#uselib "KERNEL32.dll"
#cfunc global SetFileShortNameA "SetFileShortNameA" intptr, str
; res = SetFileShortNameA(hFile, lpShortName)
; hFile : HANDLE -> "intptr"
; lpShortName : LPCSTR -> "str"
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	kernel32 = windows.NewLazySystemDLL("KERNEL32.dll")
	procSetFileShortNameA = kernel32.NewProc("SetFileShortNameA")
)

// hFile (HANDLE), lpShortName (LPCSTR)
r1, _, err := procSetFileShortNameA.Call(
	uintptr(hFile),
	uintptr(unsafe.Pointer(windows.BytePtrFromString(lpShortName))),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // BOOL
function SetFileShortNameA(
  hFile: THandle;   // HANDLE
  lpShortName: PAnsiChar   // LPCSTR
): BOOL; stdcall;
  external 'KERNEL32.dll' name 'SetFileShortNameA';
result := DllCall("KERNEL32\SetFileShortNameA"
    , "Ptr", hFile   ; HANDLE
    , "AStr", lpShortName   ; LPCSTR
    , "Int")   ; return: BOOL
●SetFileShortNameA(hFile, lpShortName) = DLL("KERNEL32.dll", "bool SetFileShortNameA(void*, char*)")
# 呼び出し: SetFileShortNameA(hFile, lpShortName)
# hFile : HANDLE -> "void*"
# lpShortName : LPCSTR -> "char*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "kernel32" fn SetFileShortNameA(
    hFile: ?*anyopaque, // HANDLE
    lpShortName: [*c]const u8 // LPCSTR
) callconv(std.os.windows.WINAPI) i32;
proc SetFileShortNameA(
    hFile: pointer,  # HANDLE
    lpShortName: cstring  # LPCSTR
): int32 {.importc: "SetFileShortNameA", stdcall, dynlib: "KERNEL32.dll".}
pragma(lib, "kernel32");
extern(Windows)
int SetFileShortNameA(
    void* hFile,   // HANDLE
    const(char)* lpShortName   // LPCSTR
);
ccall((:SetFileShortNameA, "KERNEL32.dll"), stdcall, Int32,
      (Ptr{Cvoid}, Cstring),
      hFile, lpShortName)
# hFile : HANDLE -> Ptr{Cvoid}
# lpShortName : LPCSTR -> Cstring
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
int32_t SetFileShortNameA(
    void* hFile,
    const char* lpShortName);
]]
local kernel32 = ffi.load("kernel32")
-- kernel32.SetFileShortNameA(hFile, lpShortName)
-- hFile : HANDLE
-- lpShortName : LPCSTR
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('KERNEL32.dll');
const SetFileShortNameA = lib.func('__stdcall', 'SetFileShortNameA', 'int32_t', ['void *', 'str']);
// SetFileShortNameA(hFile, lpShortName)
// hFile : HANDLE -> 'void *'
// lpShortName : LPCSTR -> 'str'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("KERNEL32.dll", {
  SetFileShortNameA: { parameters: ["pointer", "buffer"], result: "i32" },
});
// lib.symbols.SetFileShortNameA(hFile, lpShortName)
// hFile : HANDLE -> "pointer"
// lpShortName : LPCSTR -> "buffer"
// 文字列は "buffer"。ANSI(-A) は new TextEncoder() で UTF-8/ANSI バイト列(末尾に \x00)を渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int32_t SetFileShortNameA(
    void* hFile,
    const char* lpShortName);
C, "KERNEL32.dll");
// $ffi->SetFileShortNameA(hFile, lpShortName);
// hFile : HANDLE
// lpShortName : LPCSTR
// 構造体/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.ASCII_OPTIONS);
    boolean SetFileShortNameA(
        Pointer hFile,   // HANDLE
        String lpShortName   // LPCSTR
    );
}
@[Link("kernel32")]
lib LibKERNEL32
  fun SetFileShortNameA = SetFileShortNameA(
    hFile : Void*,   # HANDLE
    lpShortName : UInt8*   # LPCSTR
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

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

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

let setfileshortnamea =
  foreign "SetFileShortNameA"
    ((ptr void) @-> string @-> returning int32_t)
(* hFile : HANDLE -> (ptr void) *)
(* lpShortName : LPCSTR -> string *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library kernel32 (t "KERNEL32.dll"))
(cffi:use-foreign-library kernel32)

(cffi:defcfun ("SetFileShortNameA" set-file-short-name-a :convention :stdcall) :int32
  (h-file :pointer)   ; HANDLE
  (lp-short-name :string))   ; LPCSTR
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $SetFileShortNameA = Win32::API::More->new('KERNEL32',
    'BOOL SetFileShortNameA(HANDLE hFile, LPCSTR lpShortName)');
# my $ret = $SetFileShortNameA->Call($hFile, $lpShortName);
# hFile : HANDLE -> HANDLE
# lpShortName : LPCSTR -> LPCSTR
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

文字セット違い