SHGetFolderLocation-Funktion (shlobj_core.h)

  • Artikel

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 zu findenden Ordner identifiziert. Die ordner, die den CSIDLs zugeordnet sind, sind möglicherweise nicht in einem bestimmten System vorhanden.

[in] hToken

Typ: HANDLE

Ein Zugriffstoken , das verwendet werden kann, um einen bestimmten Benutzer darzustellen. Es ist in der Regel auf NULL festgelegt, aber es kann erforderlich sein, wenn mehrere Benutzer für diese Ordner vorhanden sind, die zu einem einzelnen Benutzer gehören. Der am häufigsten verwendete Ordner dieses Typs ist "Meine Dokumente". Die aufrufende Anwendung ist für die korrekte Identitätswechsel verantwortlich, wenn hToken nicht NULL ist. Es muss über geeignete Sicherheitsberechtigungen für den bestimmten Benutzer verfügen, und die Registrierungsstruktur des Benutzers muss zurzeit bereitgestellt werden. Weitere Diskussionen zu Zugriffssteuerungsproblemen finden Sie Access Control.

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

[in] dwFlags

Art: DWORD

[out] ppidl

Typ: PIDLIST_ABSOLUTE*

Die Adresse eines Zeigers auf eine Elementbezeichner-Listenstruktur, die den Speicherort des Ordners relativ zum Stamm des Namespaces (desktop) angibt. Der ppidl-Parameter ist auf NULL für Fehler festgelegt. Die aufrufende Anwendung ist dafür verantwortlich, diese Ressource durch Aufrufen von ILFree freizurufen.

Rückgabewert

Typ: HRESULT

Gibt S_OK zurück, wenn dies erfolgreich ist, oder einen anderen Fehlerwert, 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 seine zugeordnete KNOWNFOLDERID übersetzt, und SHGetKnownFolderIDList wird aufgerufen. Neue Anwendungen sollten das bekannte Ordnersystem anstelle des älteren CSIDL-Systems verwenden, das nur zur Abwärtskompatibilität unterstützt wird.
 
Die Funktionen SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation und SHGetSpecialFolderPath sind die bevorzugten Methoden zum Abrufen von Handlen für Ordner auf Systemen, die älter als Windows Vista sind. Funktionen wie ExpandEnvironmentStrings , die die Namen der Umgebungsvariablen direkt verwenden, im Formular %VariableName%, sind möglicherweise nicht zuverlässig.

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

Anforderungen

   
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 (einschließlich Shlobj.h)
Bibliothek Shell32.lib
DLL Shell32.dll (Version 5.0 oder höher)

Weitere Informationen

IKnownFolder::GetIDList