ホーム › UI.Shell › SHGetFolderPathA

SHGetFolderPathA

関数

CSIDLで指定したフォルダーのパス(ANSI)を取得する。

DLLSHELL32.dll文字セットANSI (-A)呼出規約winapi対応OSWindows 2000 以降

シグネチャ

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

HRESULT SHGetFolderPathA(
    HWND hwnd,   // optional
    INT csidl,
    HANDLE hToken,   // optional
    DWORD dwFlags,
    LPSTR pszPath
);

パラメーター

名前	型	方向	説明
hwnd	HWND	optional	予約済みです。
csidl	INT	in	パスを取得する対象のフォルダーを識別する CSIDL 値です。実在するフォルダーのみが有効です。仮想フォルダーを指定した場合、この関数は失敗します。フォルダーの CSIDL を CSIDL_FLAG_CREATE と組み合わせることで、フォルダーの作成を強制できます。
hToken	HANDLE	inoptional	特定のユーザーを表すために使用できるアクセストークンです。 Microsoft Windows 2000 以前: このパラメーターには常に NULL を設定してください。 Windows XP 以降: このパラメーターには通常 NULL を設定しますが、複数のユーザーを持ち得るものの単一のユーザーに属するものとして扱われるフォルダーについては、hToken に NULL 以外の値を割り当てる必要がある場合があります。この種のフォルダーで最もよく使われるのは Documents です。 hToken が NULL 以外の場合、正しい偽装を行う責任は呼び出し側プロセスにあります。呼び出し側プロセスは、TOKEN_QUERY および TOKEN_IMPERSONATE を含む、当該ユーザーに対する適切なセキュリティ特権を持っている必要があり、そのユーザーのレジストリハイブが現在マウントされている必要があります。アクセス制御に関する詳細は、アクセス制御を参照してください。 hToken パラメーターに値 -1 を割り当てると、既定のユーザー (Default User) を示します。これにより、SHGetFolderPath のクライアントは既定のユーザーのフォルダーの場所 (デスクトップフォルダーなど) を見つけることができます。既定のユーザーのユーザープロファイルは、新しいユーザーアカウントが作成されるたびに複製され、マイドキュメントやデスクトップなどの特殊フォルダーが含まれます。既定のユーザーのフォルダーに追加された項目は、新しいユーザーアカウントにも反映されます。
dwFlags	DWORD	in	返されるパスを指定するフラグです。この値は、KNOWNFOLDERID (または CSIDL) に関連付けられたフォルダーが、ユーザーまたは管理者によって移動、名前変更、リダイレクト、または言語間でローミングされ得る場合に使用されます。 SHGetFolderPath の基盤となる既知のフォルダーシステムでは、ユーザーまたは管理者が既知のフォルダーを自分のニーズに合った場所へリダイレクトできます。これは IKnownFolderManager::Redirect を呼び出すことで実現され、SHGFP_TYPE_CURRENT フラグに関連付けられたフォルダーの「現在の」値が設定されます。フォルダーの既定値、すなわちユーザーまたは管理者が他の場所へリダイレクトしていなかった場合のフォルダーの場所は、SHGFP_TYPE_DEFAULT フラグを指定することで取得されます。この値は、既知のフォルダーに対する「既定値に戻す」機能を実装するために使用できます。たとえば、FOLDERID_Music (CSIDL_MYMUSIC) の既定値 (SHGFP_TYPE_DEFAULT) は "C:\Users\user name\Music" です。フォルダーがリダイレクトされていた場合、現在の値 (SHGFP_TYPE_CURRENT) は "D:\Music" のようになることがあります。フォルダーがリダイレクトされていない場合、SHGFP_TYPE_DEFAULT と SHGFP_TYPE_CURRENT は同じパスを取得します。 SHGFP_TYPE_CURRENT フォルダーの現在のパスを取得します。 SHGFP_TYPE_DEFAULT フォルダーの既定のパスを取得します。
pszPath	LPSTR	out	パスを受け取る、長さ MAX_PATH の null で終わる文字列へのポインターです。エラーが発生した場合、または S_FALSE が返された場合、この文字列は空になります。返されるパスには末尾のバックスラッシュは含まれません。たとえば、"C:\Users\" ではなく "C:\Users" が返されます。

戻り値の型: HRESULT

公式ドキュメント

非推奨です。 (SHGetFolderPathA)

戻り値

型: HRESULT

この関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

この関数は SHGetSpecialFolderPath のスーパーセットです。

サポートされている CSIDL 値は一部のみで、以下が含まれます。

例

次のコード例では、SHGetFolderPath を使用してフォルダーを検索または作成し、その中にファイルを作成します。

TCHAR szPath[MAX_PATH];

if(SUCCEEDED(SHGetFolderPath(NULL, 
                             CSIDL_PERSONAL|CSIDL_FLAG_CREATE, 
                             NULL, 
                             0, 
                             szPath))) 
{
    PathAppend(szPath, TEXT("New Doc.txt"));
    HANDLE hFile = CreateFile(szPath, ...);
}

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

各言語での呼び出し定義

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

HRESULT SHGetFolderPathA(
    HWND hwnd,   // optional
    INT csidl,
    HANDLE hToken,   // optional
    DWORD dwFlags,
    LPSTR pszPath
);

[DllImport("SHELL32.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int SHGetFolderPathA(
    IntPtr hwnd,   // HWND optional
    int csidl,   // INT
    IntPtr hToken,   // HANDLE optional
    uint dwFlags,   // DWORD
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder pszPath   // LPSTR out
);

<DllImport("SHELL32.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function SHGetFolderPathA(
    hwnd As IntPtr,   ' HWND optional
    csidl As Integer,   ' INT
    hToken As IntPtr,   ' HANDLE optional
    dwFlags As UInteger,   ' DWORD
    <MarshalAs(UnmanagedType.LPStr)> pszPath As System.Text.StringBuilder   ' LPSTR out
) As Integer
End Function

' hwnd : HWND optional
' csidl : INT
' hToken : HANDLE optional
' dwFlags : DWORD
' pszPath : LPSTR out
Declare PtrSafe Function SHGetFolderPathA Lib "shell32" ( _
    ByVal hwnd As LongPtr, _
    ByVal csidl As Long, _
    ByVal hToken As LongPtr, _
    ByVal dwFlags As Long, _
    ByVal pszPath As String) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

SHGetFolderPathA = ctypes.windll.shell32.SHGetFolderPathA
SHGetFolderPathA.restype = ctypes.c_int
SHGetFolderPathA.argtypes = [
    wintypes.HANDLE,  # hwnd : HWND optional
    ctypes.c_int,  # csidl : INT
    wintypes.HANDLE,  # hToken : HANDLE optional
    wintypes.DWORD,  # dwFlags : DWORD
    wintypes.LPSTR,  # pszPath : LPSTR out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('SHELL32.dll')
SHGetFolderPathA = Fiddle::Function.new(
  lib['SHGetFolderPathA'],
  [
    Fiddle::TYPE_VOIDP,  # hwnd : HWND optional
    Fiddle::TYPE_INT,  # csidl : INT
    Fiddle::TYPE_VOIDP,  # hToken : HANDLE optional
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
    Fiddle::TYPE_VOIDP,  # pszPath : LPSTR out
  ],
  Fiddle::TYPE_INT)

#[link(name = "shell32")]
extern "system" {
    fn SHGetFolderPathA(
        hwnd: *mut core::ffi::c_void,  // HWND optional
        csidl: i32,  // INT
        hToken: *mut core::ffi::c_void,  // HANDLE optional
        dwFlags: u32,  // DWORD
        pszPath: *mut u8  // LPSTR out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("SHELL32.dll", CharSet = CharSet.Ansi)]
public static extern int SHGetFolderPathA(IntPtr hwnd, int csidl, IntPtr hToken, uint dwFlags, [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder pszPath);
"@
$api = Add-Type -MemberDefinition $sig -Name 'SHELL32_SHGetFolderPathA' -Namespace Win32 -PassThru
# $api::SHGetFolderPathA(hwnd, csidl, hToken, dwFlags, pszPath)

#uselib "SHELL32.dll"
#func global SHGetFolderPathA "SHGetFolderPathA" sptr, sptr, sptr, sptr, sptr
; SHGetFolderPathA hwnd, csidl, hToken, dwFlags, varptr(pszPath)   ; 戻り値は stat
; hwnd : HWND optional -> "sptr"
; csidl : INT -> "sptr"
; hToken : HANDLE optional -> "sptr"
; dwFlags : DWORD -> "sptr"
; pszPath : LPSTR out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "SHELL32.dll"
#cfunc global SHGetFolderPathA "SHGetFolderPathA" sptr, int, sptr, int, var
; res = SHGetFolderPathA(hwnd, csidl, hToken, dwFlags, pszPath)
; hwnd : HWND optional -> "sptr"
; csidl : INT -> "int"
; hToken : HANDLE optional -> "sptr"
; dwFlags : DWORD -> "int"
; pszPath : LPSTR out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "SHELL32.dll"
#cfunc global SHGetFolderPathA "SHGetFolderPathA" sptr, int, sptr, int, sptr
; res = SHGetFolderPathA(hwnd, csidl, hToken, dwFlags, varptr(pszPath))
; hwnd : HWND optional -> "sptr"
; csidl : INT -> "int"
; hToken : HANDLE optional -> "sptr"
; dwFlags : DWORD -> "int"
; pszPath : LPSTR out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。