KNOWNFOLDER_DEFINITION
構造体サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。
フィールド
| フィールド | 型 | サイズ | x64 | x86 | 説明 |
|---|---|---|---|---|---|
| category | KF_CATEGORY | 4 | +0 | +0 | KF_CATEGORY 定数のうちの 1 つの値で、フォルダーを仮想 (virtual)、固定 (fixed)、共通 (common)、ユーザーごと (per-user) のいずれかに分類します。 |
| pszName | LPWSTR | 8/4 | +8 | +4 | 既知のフォルダーの、ローカライズされていない正規名へのポインターです。null で終わる Unicode 文字列として格納されます。このフォルダーが共通フォルダーまたはユーザーごとのフォルダーである場合、この値は "User Shell Folders" レジストリ設定の値名としても使用されます。この名前は、一意で人間が読める名前であることを意図しています。サードパーティは Company.Application.Name という形式に従うことを推奨します。ここで指定する名前は表示名とは異なるため、混同しないでください。 |
| pszDescription | LPWSTR | 8/4 | +16 | +8 | 既知のフォルダーの簡潔な説明へのポインターです。null で終わる Unicode 文字列として格納されます。この説明には、そのフォルダーの目的と用途を含めてください。 |
| fidParent | GUID | 16 | +24 | +12 | 親フォルダーとして機能する別の既知のフォルダーを指定する KNOWNFOLDERID 値です。共通フォルダーおよびユーザーごとのフォルダーにのみ適用されます。この値は pszRelativePath と組み合わせて使用します。詳細については Remarks を参照してください。 pszRelativePath に値を指定しない場合、この値は省略可能です。 |
| pszRelativePath | LPWSTR | 8/4 | +40 | +28 | 省略可能です。fidParent で指定した親フォルダーからの相対パスへのポインターです。これは null で終わる Unicode 文字列で、物理的なファイルシステムのパスを示し、ローカライズされません。共通フォルダーおよびユーザーごとのフォルダーにのみ適用されます。詳細については Remarks を参照してください。 |
| pszParsingName | LPWSTR | 8/4 | +48 | +32 | フォルダーの Shell 名前空間におけるフォルダーパスへのポインターです。null で終わる Unicode 文字列として格納されます。仮想フォルダーにのみ適用されます。たとえば、Control Panel の解析名は ::%CLSID_MyComputer%::%CLSID_ControlPanel% です。 |
| pszTooltip | LPWSTR | 8/4 | +56 | +36 | 省略可能です。この既知のフォルダーが作成されるときに使用される、既定のツールヒントリソースへのポインターです。これは次の形式の、null で終わる Unicode 文字列です。 Module name, Resource ID たとえば、 この情報は仮想フォルダーでは必要ありません。 |
| pszLocalizedName | LPWSTR | 8/4 | +64 | +40 | 省略可能です。フォルダーが作成されるときに使用される、既定のローカライズされた名前のリソースへのポインターです。これは次の形式の、null で終わる Unicode 文字列です。 Module name, Resource ID フォルダーが作成されると、この文字列はそのフォルダーの Desktop.ini に格納されます。後から他の Shell API によって変更できます。 この情報は仮想フォルダーでは必要ありません。 |
| pszIcon | LPWSTR | 8/4 | +72 | +44 | 省略可能です。フォルダーが作成されるときに使用される、既定のアイコンリソースへのポインターです。これは次の形式の、null で終わる Unicode 文字列です。 Module name, Resource ID フォルダーが作成されると、この文字列はそのフォルダーの Desktop.ini に格納されます。後から他の Shell API によって変更できます。 この情報は仮想フォルダーでは必要ありません。 |
| pszSecurity | LPWSTR | 8/4 | +80 | +48 | 省略可能です。Security Descriptor Definition Language 形式の文字列へのポインターです。これは null で終わる Unicode 文字列で、フォルダーが作成されるときに与えられる既定のセキュリティ記述子を記述します。このパラメーターが NULL の場合、新しいフォルダーは親のセキュリティ記述子を継承します。これは、すべてのユーザーからアクセスされる共通フォルダーで特に有用です。 |
| dwAttributes | DWORD | 4 | +88 | +52 | 省略可能です。フォルダーが作成されるときに与えられる既定のファイルシステム属性です。たとえば、隠しファイルかつ読み取り専用 (FILE_ATTRIBUTE_HIDDEN および FILE_ATTRIBUTE_READONLY) にすることができます。指定できる値の完全な一覧については、CreateFile 関数の dwFlagsAndAttributes パラメーターを参照してください。不要な場合は -1 を設定します。 |
| kfdFlags | DWORD | 4 | +92 | +56 | 省略可能です。KF_DEFINITION_FLAGS 列挙型の 1 つ以上の値で、リダイレクトの制限、PC 間のローミングの許可、既知のフォルダーが作成されるタイミングの制御を行えます。不要な場合は 0 を設定します。 |
| ftidType | GUID | 16 | +96 | +60 | FOLDERTYPEID 値のいずれかで、フォルダーの内容 (ドキュメント、音楽、写真など) に基づいて既知のフォルダーの種類を識別します。この値は GUID です。 |
公式ドキュメント
既知のフォルダー (known folder) の詳細を定義します。
解説(Remarks)
fidParent と pszRelativePath の値は組み合わせて機能します。たとえば、MyNewFolder というフォルダーを定義し、そのフォルダーを ...<Username>\AppData\Local\MyApp\MyNewFolder として作成したいとします。この場合、...<Username>\AppData\Local を表すために fidParent に FOLDERID_LocalAppData を指定します。そして pszRelativePath に "\MyApp\MyNewFolder" を指定します。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
各言語での定義
#include <windows.h>
// KNOWNFOLDER_DEFINITION (x64 112 / x86 76 バイト)
typedef struct KNOWNFOLDER_DEFINITION {
KF_CATEGORY category;
LPWSTR pszName;
LPWSTR pszDescription;
GUID fidParent;
LPWSTR pszRelativePath;
LPWSTR pszParsingName;
LPWSTR pszTooltip;
LPWSTR pszLocalizedName;
LPWSTR pszIcon;
LPWSTR pszSecurity;
DWORD dwAttributes;
DWORD kfdFlags;
GUID ftidType;
} KNOWNFOLDER_DEFINITION;using System;
using System.Runtime.InteropServices;
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct KNOWNFOLDER_DEFINITION
{
public int category;
public IntPtr pszName;
public IntPtr pszDescription;
public Guid fidParent;
public IntPtr pszRelativePath;
public IntPtr pszParsingName;
public IntPtr pszTooltip;
public IntPtr pszLocalizedName;
public IntPtr pszIcon;
public IntPtr pszSecurity;
public uint dwAttributes;
public uint kfdFlags;
public Guid ftidType;
}Imports System.Runtime.InteropServices
<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure KNOWNFOLDER_DEFINITION
Public category As Integer
Public pszName As IntPtr
Public pszDescription As IntPtr
Public fidParent As Guid
Public pszRelativePath As IntPtr
Public pszParsingName As IntPtr
Public pszTooltip As IntPtr
Public pszLocalizedName As IntPtr
Public pszIcon As IntPtr
Public pszSecurity As IntPtr
Public dwAttributes As UInteger
Public kfdFlags As UInteger
Public ftidType As Guid
End Structureimport ctypes
from ctypes import wintypes
class KNOWNFOLDER_DEFINITION(ctypes.Structure):
_fields_ = [
("category", ctypes.c_int),
("pszName", ctypes.c_void_p),
("pszDescription", ctypes.c_void_p),
("fidParent", GUID),
("pszRelativePath", ctypes.c_void_p),
("pszParsingName", ctypes.c_void_p),
("pszTooltip", ctypes.c_void_p),
("pszLocalizedName", ctypes.c_void_p),
("pszIcon", ctypes.c_void_p),
("pszSecurity", ctypes.c_void_p),
("dwAttributes", wintypes.DWORD),
("kfdFlags", wintypes.DWORD),
("ftidType", GUID),
]#[repr(C)]
pub struct KNOWNFOLDER_DEFINITION {
pub category: i32,
pub pszName: *mut core::ffi::c_void,
pub pszDescription: *mut core::ffi::c_void,
pub fidParent: GUID,
pub pszRelativePath: *mut core::ffi::c_void,
pub pszParsingName: *mut core::ffi::c_void,
pub pszTooltip: *mut core::ffi::c_void,
pub pszLocalizedName: *mut core::ffi::c_void,
pub pszIcon: *mut core::ffi::c_void,
pub pszSecurity: *mut core::ffi::c_void,
pub dwAttributes: u32,
pub kfdFlags: u32,
pub ftidType: GUID,
}import "golang.org/x/sys/windows"
type KNOWNFOLDER_DEFINITION struct {
category int32
pszName uintptr
pszDescription uintptr
fidParent windows.GUID
pszRelativePath uintptr
pszParsingName uintptr
pszTooltip uintptr
pszLocalizedName uintptr
pszIcon uintptr
pszSecurity uintptr
dwAttributes uint32
kfdFlags uint32
ftidType windows.GUID
}type
KNOWNFOLDER_DEFINITION = record
category: Integer;
pszName: Pointer;
pszDescription: Pointer;
fidParent: TGUID;
pszRelativePath: Pointer;
pszParsingName: Pointer;
pszTooltip: Pointer;
pszLocalizedName: Pointer;
pszIcon: Pointer;
pszSecurity: Pointer;
dwAttributes: DWORD;
kfdFlags: DWORD;
ftidType: TGUID;
end;const KNOWNFOLDER_DEFINITION = extern struct {
category: i32,
pszName: ?*anyopaque,
pszDescription: ?*anyopaque,
fidParent: GUID,
pszRelativePath: ?*anyopaque,
pszParsingName: ?*anyopaque,
pszTooltip: ?*anyopaque,
pszLocalizedName: ?*anyopaque,
pszIcon: ?*anyopaque,
pszSecurity: ?*anyopaque,
dwAttributes: u32,
kfdFlags: u32,
ftidType: GUID,
};type
KNOWNFOLDER_DEFINITION {.bycopy.} = object
category: int32
pszName: pointer
pszDescription: pointer
fidParent: GUID
pszRelativePath: pointer
pszParsingName: pointer
pszTooltip: pointer
pszLocalizedName: pointer
pszIcon: pointer
pszSecurity: pointer
dwAttributes: uint32
kfdFlags: uint32
ftidType: GUIDstruct KNOWNFOLDER_DEFINITION
{
int category;
void* pszName;
void* pszDescription;
GUID fidParent;
void* pszRelativePath;
void* pszParsingName;
void* pszTooltip;
void* pszLocalizedName;
void* pszIcon;
void* pszSecurity;
uint dwAttributes;
uint kfdFlags;
GUID ftidType;
}HSP用 定義
HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; KNOWNFOLDER_DEFINITION サイズ: 76 バイト(x86)
dim st, 19 ; 4byte整数×19(構造体サイズ 76 / 4 切り上げ)
; category : KF_CATEGORY (+0, 4byte) st.0 = 値 / 値 = st.0 (lpoke/lpeek も可)
; pszName : LPWSTR (+4, 4byte) st.1 = 値 / 値 = st.1 (lpoke/lpeek も可)
; pszDescription : LPWSTR (+8, 4byte) st.2 = 値 / 値 = st.2 (lpoke/lpeek も可)
; fidParent : GUID (+12, 16byte) varptr(st)+12 を基点に操作(16byte:入れ子/配列)
; pszRelativePath : LPWSTR (+28, 4byte) st.7 = 値 / 値 = st.7 (lpoke/lpeek も可)
; pszParsingName : LPWSTR (+32, 4byte) st.8 = 値 / 値 = st.8 (lpoke/lpeek も可)
; pszTooltip : LPWSTR (+36, 4byte) st.9 = 値 / 値 = st.9 (lpoke/lpeek も可)
; pszLocalizedName : LPWSTR (+40, 4byte) st.10 = 値 / 値 = st.10 (lpoke/lpeek も可)
; pszIcon : LPWSTR (+44, 4byte) st.11 = 値 / 値 = st.11 (lpoke/lpeek も可)
; pszSecurity : LPWSTR (+48, 4byte) st.12 = 値 / 値 = st.12 (lpoke/lpeek も可)
; dwAttributes : DWORD (+52, 4byte) st.13 = 値 / 値 = st.13 (lpoke/lpeek も可)
; kfdFlags : DWORD (+56, 4byte) st.14 = 値 / 値 = st.14 (lpoke/lpeek も可)
; ftidType : GUID (+60, 16byte) varptr(st)+60 を基点に操作(16byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; KNOWNFOLDER_DEFINITION サイズ: 112 バイト(x64)
dim st, 28 ; 4byte整数×28(構造体サイズ 112 / 4 切り上げ)
; category : KF_CATEGORY (+0, 4byte) st.0 = 値 / 値 = st.0 (lpoke/lpeek も可)
; pszName : LPWSTR (+8, 8byte) qpoke st,8,値 / qpeek(st,8) ※IronHSPのみ。3.7/3.8は lpoke st,8,下位 : lpoke st,12,上位
; pszDescription : LPWSTR (+16, 8byte) qpoke st,16,値 / qpeek(st,16) ※IronHSPのみ。3.7/3.8は lpoke st,16,下位 : lpoke st,20,上位
; fidParent : GUID (+24, 16byte) varptr(st)+24 を基点に操作(16byte:入れ子/配列)
; pszRelativePath : LPWSTR (+40, 8byte) qpoke st,40,値 / qpeek(st,40) ※IronHSPのみ。3.7/3.8は lpoke st,40,下位 : lpoke st,44,上位
; pszParsingName : LPWSTR (+48, 8byte) qpoke st,48,値 / qpeek(st,48) ※IronHSPのみ。3.7/3.8は lpoke st,48,下位 : lpoke st,52,上位
; pszTooltip : LPWSTR (+56, 8byte) qpoke st,56,値 / qpeek(st,56) ※IronHSPのみ。3.7/3.8は lpoke st,56,下位 : lpoke st,60,上位
; pszLocalizedName : LPWSTR (+64, 8byte) qpoke st,64,値 / qpeek(st,64) ※IronHSPのみ。3.7/3.8は lpoke st,64,下位 : lpoke st,68,上位
; pszIcon : LPWSTR (+72, 8byte) qpoke st,72,値 / qpeek(st,72) ※IronHSPのみ。3.7/3.8は lpoke st,72,下位 : lpoke st,76,上位
; pszSecurity : LPWSTR (+80, 8byte) qpoke st,80,値 / qpeek(st,80) ※IronHSPのみ。3.7/3.8は lpoke st,80,下位 : lpoke st,84,上位
; dwAttributes : DWORD (+88, 4byte) st.22 = 値 / 値 = st.22 (lpoke/lpeek も可)
; kfdFlags : DWORD (+92, 4byte) st.23 = 値 / 値 = st.23 (lpoke/lpeek も可)
; ftidType : GUID (+96, 16byte) varptr(st)+96 を基点に操作(16byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
; ※GUID・入れ子構造体はデフォルト型でないため、依存する #defstruct を先に定義(下記に同梱)。
#defstruct global GUID, pack=1
#field int Data1
#field short Data2
#field short Data3
#field byte Data4 8
#endstruct
#defstruct global KNOWNFOLDER_DEFINITION
#field int category
#field intptr pszName
#field intptr pszDescription
#field GUID fidParent
#field intptr pszRelativePath
#field intptr pszParsingName
#field intptr pszTooltip
#field intptr pszLocalizedName
#field intptr pszIcon
#field intptr pszSecurity
#field int dwAttributes
#field int kfdFlags
#field GUID ftidType
#endstruct
stdim st, KNOWNFOLDER_DEFINITION ; NSTRUCT 変数を確保
st->category = 100
mes "category=" + st->category