SHGetFolderLocation-Funktion (shlobj_core.h)

Artikel
03/06/2024

Veraltet. Ruft den Pfad eines Ordners als ITEMIDLIST-Struktur ab.

Syntax

SHSTDAPI SHGetFolderLocation(
  [in]  HWND             hwnd,
  [in]  int              csidl,
  [in]  HANDLE           hToken,
  [in]  DWORD            dwFlags,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Parameter

[in] hwnd

Typ: HWND

Reserviert.

[in] csidl

Typ: int

Ein CSIDL-Wert , der den ordner identifiziert, der sich befinden soll. Die ordner, die den CSIDLs zugeordnet sind, sind möglicherweise nicht auf einem bestimmten System vorhanden.

[in] hToken

Typ: HANDLE

Ein Zugriffstoken , das verwendet werden kann, um einen bestimmten Benutzer darzustellen. Sie wird normalerweise auf NULL festgelegt, kann jedoch erforderlich sein, wenn mehrere Benutzer für die Ordner vorhanden sind, die als zu einem einzelnen Benutzer gehören. Der am häufigsten verwendete Ordner dieses Typs ist Eigene Dokumente. Die aufrufende Anwendung ist für einen korrekten Identitätswechsel verantwortlich, wenn hToken ungleich NULL ist. Es muss über die entsprechenden Sicherheitsberechtigungen für den jeweiligen Benutzer verfügen, und die Registrierungsstruktur des Benutzers muss derzeit eingebunden sein. Weitere Informationen zu Problemen mit der Zugriffssteuerung finden Sie unter Access Control.

Wenn Sie dem hToken-Parameter den Wert -1 zuweisen, wird der Standardbenutzer angegeben. Dadurch können Clients von SHGetFolderLocation Ordnerspeicherorte (z. B. den Desktopordner) für den Standardbenutzer suchen. Das Benutzerprofil Standardbenutzer 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 werden, werden auch in jedem neuen Benutzerkonto angezeigt.

[in] dwFlags

Art: DWORD

[out] ppidl

Typ: PIDLIST_ABSOLUTE*

Die Adresse eines Zeigers auf eine Elementbezeichnerlistenstruktur, die den Speicherort des Ordners relativ zum Stamm des Namespace (desktop) angibt. Der ppidl-Parameter ist bei Einem Fehler auf NULL festgelegt. Die aufrufende Anwendung ist dafür verantwortlich, diese Ressource durch Aufrufen von ILFree frei zu geben.

Rückgabewert

Typ: HRESULT

Gibt bei erfolgreicher Ausführung S_OK oder andernfalls einen Fehlerwert zurück, einschließlich der folgenden:

Rückgabecode	Beschreibung
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	Die CSIDL in nFolder ist gültig, aber der Ordner ist nicht vorhanden.
E_INVALIDARG	Die CSIDL in nFolder ist ungültig.

Hinweise

Hinweis Ab Windows Vista ist diese Funktion lediglich ein Wrapper für SHGetKnownFolderIDList. Der CSIDL-Wert wird in den zugeordneten KNOWNFOLDERID-Wert übersetzt, und SHGetKnownFolderIDList wird 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.

Die Funktionen SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation und SHGetSpecialFolderPath sind die bevorzugten Methoden zum Abrufen von Handles für Ordner auf Systemen vor Windows Vista. Funktionen wie ExpandEnvironmentStrings , die die Namen der Umgebungsvariablen direkt im Format %VariableName% verwenden, sind möglicherweise nicht zuverlässig.

Diese Funktion ist eine Obermenge von SHGetSpecialFolderLocation, die in früheren Versionen der Shell enthalten ist.

Anforderungen

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

Weitere Informationen

IKnownFolder::GetIDList

Freigeben über