SHGetFolderPathA-Funktion (shlobj_core.h)

Artikel
08/26/2023

Veraltet. Ruft den Pfad eines Ordners ab, der durch einen CSIDL-Wert identifiziert wird.

Hinweis Ab Windows Vista ist diese Funktion lediglich ein Wrapper für SHGetKnownFolderPath. Der CSIDL-Wert wird in die zugeordnete KNOWNFOLDERID übersetzt und dann SHGetKnownFolderPath aufgerufen. Neue Anwendungen sollten das bekannte Ordnersystem anstelle des älteren CSIDL-Systems verwenden, das nur aus Gründen der Abwärtskompatibilität unterstützt wird.

Syntax

SHFOLDERAPI SHGetFolderPathA(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [out] LPSTR  pszPath
);

Parameter

[in] hwnd

Typ: HWND

Reserviert.

[in] csidl

Typ: int

Ein CSIDL-Wert , der den Ordner identifiziert, dessen Pfad abgerufen werden soll. Nur echte Ordner sind gültig. Wenn ein virtueller Ordner angegeben wird, schlägt diese Funktion fehl. Sie können die Erstellung eines Ordners erzwingen, indem Sie die CSIDL des Ordners mit CSIDL_FLAG_CREATE kombinieren.

[in] hToken

Typ: HANDLE

Ein Zugriffstoken , das verwendet werden kann, um einen bestimmten Benutzer darzustellen.

Microsoft Windows 2000 und früher: Legen Sie diesen Parameter immer auf NULL fest.

Windows XP und höher: Dieser Parameter ist normalerweise auf NULL festgelegt. Möglicherweise müssen Sie hToken jedoch einen Wert ungleich NULL für die Ordner zuweisen, die mehrere Benutzer haben können, aber als zu einem einzelnen Benutzer gehören behandelt werden. Der am häufigsten verwendete Ordner dieses Typs ist Dokumente.

Der aufrufende Prozess ist für den korrekten Identitätswechsel verantwortlich, wenn hToken nicht NULL ist. Der aufrufende Prozess muss über die entsprechenden Sicherheitsberechtigungen für den jeweiligen Benutzer verfügen, einschließlich TOKEN_QUERY und TOKEN_IMPERSONATE, und die Registrierungsstruktur des Benutzers muss derzeit eingebunden sein. Weitere Informationen zu Zugriffssteuerungsproblemen finden Sie unter Access Control.

Das Zuweisen des hToken-Parameters mit dem Wert -1 gibt den Standardbenutzer an. Dadurch können Clients von SHGetFolderPath Ordnerspeicherorte (z. B. den Ordner Desktop) für den Standardbenutzer finden. Das Standardbenutzerprofil wird dupliziert, wenn ein neues Benutzerkonto erstellt wird, und enthält spezielle Ordner wie Eigene Dokumente und Desktop. Alle Elemente, die dem Ordner Standardbenutzer hinzugefügt wurden, werden auch in jedem neuen Benutzerkonto angezeigt.

[in] dwFlags

Art: DWORD

Flags, die den zurückzugebenden Pfad angeben. Dieser Wert wird in Fällen verwendet, in denen der einer KNOWNFOLDERID (oder CSIDL) zugeordnete Ordner von einem Benutzer oder Administrator verschoben, umbenannt, umgeleitet oder sprachübergreifend geroamt werden kann.

Das bekannte Ordnersystem, das SHGetFolderPath zugrunde liegt, ermöglicht Es Benutzern oder Administratoren, einen bekannten Ordner an einen Speicherort umzuleiten, der ihren Anforderungen entspricht. Dies wird durch Aufrufen von IKnownFolderManager::Redirect erreicht, wodurch der "aktuelle" Wert des Ordners festgelegt wird, der dem SHGFP_TYPE_CURRENT-Flag zugeordnet ist.

Der Standardwert des Ordners, d. h. der Speicherort des Ordners, wenn er von einem Benutzer oder Administrator nicht an anderer Stelle umgeleitet wurde, wird durch Angabe des SHGFP_TYPE_DEFAULT-Flags abgerufen. Dieser Wert kann verwendet werden, um ein Feature "Standardwerte wiederherstellen" für einen bekannten Ordner zu implementieren.

Der Standardwert (SHGFP_TYPE_DEFAULT) für FOLDERID_Music (CSIDL_MYMUSIC) lautet beispielsweise "C:\Users\benutzername\Music". Wenn der Ordner umgeleitet wurde, kann der aktuelle Wert (SHGFP_TYPE_CURRENT) "D:\Music" sein. Wenn der Ordner nicht umgeleitet wurde, SHGFP_TYPE_DEFAULT und SHGFP_TYPE_CURRENT denselben Pfad abrufen.

SHGFP_TYPE_CURRENT

Rufen Sie den aktuellen Pfad des Ordners ab.

SHGFP_TYPE_DEFAULT

Rufen Sie den Standardpfad des Ordners ab.

[out] pszPath

Typ: LPTSTR

Ein Zeiger auf eine null-beendete Zeichenfolge der Länge MAX_PATH die den Pfad empfängt. Wenn ein Fehler auftritt oder S_FALSE zurückgegeben wird, ist diese Zeichenfolge leer. Der zurückgegebene Pfad enthält keinen nachfolgenden umgekehrten Schrägstrich. Beispielsweise wird "C:\Users" anstelle von "C:\Users\" zurückgegeben.

Rückgabewert

Typ: HRESULT

Wenn diese Funktion erfolgreich ist, gibt sie S_OK zurück. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Diese Funktion ist eine Übermenge von SHGetSpecialFolderPath.

Es werden nur einige CSIDL-Werte unterstützt, einschließlich der folgenden:

Beispiele

Im folgenden Codebeispiel wird SHGetFolderPath verwendet, um einen Ordner zu suchen oder zu erstellen und dann eine Datei darin zu erstellen.

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, ...);
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional, Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shlobj_core.h (einschließlich Shlobj.h, Shlobj_core.h)
Bibliothek	Shell32.lib
DLL	Shell32.dll (Version 5.0 oder höher)

Weitere Informationen

IKnownFolder::GetPath

Freigeben über