SHGetFolderPathW-Funktion (shlobj_core.h)

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

Syntax

SHFOLDERAPI SHGetFolderPathW(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [out] LPWSTR 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 ist, schlägt diese Funktion fehl. Sie können die Erstellung eines Ordners erzwingen, indem Sie die CSIDL- des Ordners mit CSIDL_FLAG_CREATEkombinieren.

[in] hToken

Typ: HANDLE

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

Microsoft Windows 2000 und früher: Diesen Parameter immer auf NULL-festlegen.

Windows XP und höher: Dieser Parameter ist in der Regel auf NULL-festgelegt, sie müssen jedoch möglicherweise einen Wert ungleichNULLhToken- für diese Ordner zuweisen, die mehrere Benutzer haben können, aber als ein einzelner Benutzer behandelt werden. Der am häufigsten verwendete Ordner dieses Typs ist Documents.

Der Aufrufvorgang ist für den korrekten Identitätswechsel verantwortlich, wenn hToken- nichtNULL-ist. Der Aufrufvorgang muss über geeignete Sicherheitsberechtigungen für den jeweiligen Benutzer verfügen, einschließlich TOKEN_QUERY und TOKEN_IMPERSONATE, und die Registrierungsstruktur des Benutzers muss zurzeit bereitgestellt werden. Weitere Informationen zu Zugriffssteuerungsproblemen finden Sie .

Wenn Sie den hToken Parameter zuweisen, wird der Standardwert -1 angegeben. Dadurch können Clients von SHGetFolderPath- Ordnerspeicherorte (z. B. den Desktopordner) für den Standardbenutzer suchen. Das Benutzerprofil des Standardbenutzers wird dupliziert, wenn ein neues Benutzerkonto erstellt wird, und enthält spezielle Ordner wie "Eigene Dokumente" und "Desktop". Alle Elemente, die dem Standardbenutzerordner hinzugefügt werden, werden auch in einem neuen Benutzerkonto angezeigt.

[in] dwFlags

Typ: DWORD-

Flags, die den zurückzugebenden Pfad angeben. Dieser Wert wird in Fällen verwendet, in denen der ordner, der einer KNOWNFOLDERID- (oder CSIDL-) zugeordnet ist, verschoben, umbenannt, umgeleitet oder von einem Benutzer oder Administrator über sprachenübergreifend übertragen 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 IKnownFolderManager::Redirecterreicht, wodurch der "aktuelle" Wert des Ordners festgelegt wird, der dem SHGFP_TYPE_CURRENT Flag zugeordnet ist.

Der Standardwert des Ordners, bei dem es sich um den Speicherort des Ordners handelt, wenn ein Benutzer oder Administrator ihn nicht an anderer Stelle umgeleitet hat, wird abgerufen, indem das SHGFP_TYPE_DEFAULT Flag angegeben wird. 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, lautet der aktuelle Wert (SHGFP_TYPE_CURRENT) möglicherweise "D:\Music". 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: LPWSTR-

Ein Zeiger auf eine null-terminated string of length MAX_PATH which will receive the path. Wenn ein Fehler auftritt oder S_FALSE zurückgegeben wird, ist diese Zeichenfolge leer. Der zurückgegebene Pfad enthält keinen nachgestellten umgekehrten Schrägstrich. Beispielsweise wird "C:\Users" anstelle von "C:\Users\" zurückgegeben.

Rückgabewert

Typ: HRESULT-

Wenn diese Funktion erfolgreich ist, wird S_OKzurückgegeben. Andernfalls wird ein HRESULT- Fehlercode zurückgegeben.

Bemerkungen

Diese Funktion ist eine Obermenge von SHGetSpecialFolderPath.

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

• CSIDL_ADMINTOOLS
• CSIDL_APPDATA
• CSIDL_COMMON_ADMINTOOLS
• CSIDL_COMMON_APPDATA
• CSIDL_COMMON_DOCUMENTS
• CSIDL_COOKIES
• CSIDL_FLAG_CREATE
• CSIDL_FLAG_DONT_VERIFY
• CSIDL_HISTORY
• CSIDL_INTERNET_CACHE
• CSIDL_LOCAL_APPDATA
• CSIDL_MYPICTURES
• CSIDL_PERSONAL
• CSIDL_PROGRAM_FILES
• CSIDL_PROGRAM_FILES_COMMON
• CSIDL_SYSTEM
• CSIDL_WINDOWS

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

Siehe auch

IKnownFolder::GetPath