Win32 API 日本語リファレンス
ホームUI.Shell › KNOWNFOLDER_DEFINITION

KNOWNFOLDER_DEFINITION

構造体
サイズx64: 112 バイト / x86: 76 バイト

サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。

フィールド

フィールドサイズx64x86説明
categoryKF_CATEGORY4+0+0KF_CATEGORY 定数のうちの 1 つの値で、フォルダーを仮想 (virtual)、固定 (fixed)、共通 (common)、ユーザーごと (per-user) のいずれかに分類します。
pszNameLPWSTR8/4+8+4既知のフォルダーの、ローカライズされていない正規名へのポインターです。null で終わる Unicode 文字列として格納されます。このフォルダーが共通フォルダーまたはユーザーごとのフォルダーである場合、この値は "User Shell Folders" レジストリ設定の値名としても使用されます。この名前は、一意で人間が読める名前であることを意図しています。サードパーティは Company.Application.Name という形式に従うことを推奨します。ここで指定する名前は表示名とは異なるため、混同しないでください。
pszDescriptionLPWSTR8/4+16+8既知のフォルダーの簡潔な説明へのポインターです。null で終わる Unicode 文字列として格納されます。この説明には、そのフォルダーの目的と用途を含めてください。
fidParentGUID16+24+12

親フォルダーとして機能する別の既知のフォルダーを指定する KNOWNFOLDERID 値です。共通フォルダーおよびユーザーごとのフォルダーにのみ適用されます。この値は pszRelativePath と組み合わせて使用します。詳細については Remarks を参照してください。

pszRelativePath に値を指定しない場合、この値は省略可能です。

pszRelativePathLPWSTR8/4+40+28省略可能です。fidParent で指定した親フォルダーからの相対パスへのポインターです。これは null で終わる Unicode 文字列で、物理的なファイルシステムのパスを示し、ローカライズされません。共通フォルダーおよびユーザーごとのフォルダーにのみ適用されます。詳細については Remarks を参照してください。
pszParsingNameLPWSTR8/4+48+32フォルダーの Shell 名前空間におけるフォルダーパスへのポインターです。null で終わる Unicode 文字列として格納されます。仮想フォルダーにのみ適用されます。たとえば、Control Panel の解析名は ::%CLSID_MyComputer%::%CLSID_ControlPanel% です。
pszTooltipLPWSTR8/4+56+36

省略可能です。この既知のフォルダーが作成されるときに使用される、既定のツールヒントリソースへのポインターです。これは次の形式の、null で終わる Unicode 文字列です。

Module name, Resource ID

たとえば、@%_SYS_MOD_PATH%,-12688 は Common Pictures のツールヒントです。フォルダーが作成されると、この文字列はそのフォルダーの Desktop.ini に格納されます。後から他の Shell API によって変更できます。このリソースはローカライズされる場合があります。

この情報は仮想フォルダーでは必要ありません。

pszLocalizedNameLPWSTR8/4+64+40

省略可能です。フォルダーが作成されるときに使用される、既定のローカライズされた名前のリソースへのポインターです。これは次の形式の、null で終わる Unicode 文字列です。

Module name, Resource ID

フォルダーが作成されると、この文字列はそのフォルダーの Desktop.ini に格納されます。後から他の Shell API によって変更できます。

この情報は仮想フォルダーでは必要ありません。

pszIconLPWSTR8/4+72+44

省略可能です。フォルダーが作成されるときに使用される、既定のアイコンリソースへのポインターです。これは次の形式の、null で終わる Unicode 文字列です。

Module name, Resource ID

フォルダーが作成されると、この文字列はそのフォルダーの Desktop.ini に格納されます。後から他の Shell API によって変更できます。

この情報は仮想フォルダーでは必要ありません。

pszSecurityLPWSTR8/4+80+48省略可能です。Security Descriptor Definition Language 形式の文字列へのポインターです。これは null で終わる Unicode 文字列で、フォルダーが作成されるときに与えられる既定のセキュリティ記述子を記述します。このパラメーターが NULL の場合、新しいフォルダーは親のセキュリティ記述子を継承します。これは、すべてのユーザーからアクセスされる共通フォルダーで特に有用です。
dwAttributesDWORD4+88+52省略可能です。フォルダーが作成されるときに与えられる既定のファイルシステム属性です。たとえば、隠しファイルかつ読み取り専用 (FILE_ATTRIBUTE_HIDDEN および FILE_ATTRIBUTE_READONLY) にすることができます。指定できる値の完全な一覧については、CreateFile 関数の dwFlagsAndAttributes パラメーターを参照してください。不要な場合は -1 を設定します。
kfdFlagsDWORD4+92+56省略可能です。KF_DEFINITION_FLAGS 列挙型の 1 つ以上の値で、リダイレクトの制限、PC 間のローミングの許可、既知のフォルダーが作成されるタイミングの制御を行えます。不要な場合は 0 を設定します。
ftidTypeGUID16+96+60FOLDERTYPEID 値のいずれかで、フォルダーの内容 (ドキュメント、音楽、写真など) に基づいて既知のフォルダーの種類を識別します。この値は GUID です。

公式ドキュメント

既知のフォルダー (known folder) の詳細を定義します。

解説(Remarks)

fidParentpszRelativePath の値は組み合わせて機能します。たとえば、MyNewFolder というフォルダーを定義し、そのフォルダーを ...<Username>\AppData\Local\MyApp\MyNewFolder として作成したいとします。この場合、...<Username>\AppData\Local を表すために fidParentFOLDERID_LocalAppData を指定します。そして pszRelativePath に "\MyApp\MyNewFolder" を指定します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
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 Structure
import 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: GUID
struct 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