SHGetKnownFolderPath-Funktion (shlobj_core.h)

Artikel
08/26/2023

Ruft den vollständigen Pfad eines bekannten Ordners ab, der durch die KNOWNFOLDERID des Ordners identifiziert wird.

Syntax

HRESULT SHGetKnownFolderPath(
  [in]           REFKNOWNFOLDERID rfid,
  [in]           DWORD            dwFlags,
  [in, optional] HANDLE           hToken,
  [out]          PWSTR            *ppszPath
);

Parameter

[in] rfid

Typ: REFKNOWNFOLDERID

Ein Verweis auf die KNOWNFOLDERID , die den Ordner identifiziert.

[in] dwFlags

Art: DWORD

Flags, die spezielle Abrufoptionen angeben. Dieser Wert kann 0 sein. andernfalls mindestens einer der KNOWN_FOLDER_FLAG Werte.

[in, optional] hToken

Typ: HANDLE

Ein Zugriffstoken , das einen bestimmten Benutzer darstellt. Wenn dieser Parameter NULL ist, was die häufigste Verwendung ist, fordert die Funktion den bekannten Ordner für den aktuellen Benutzer an.

Fordern Sie den Ordner eines bestimmten Benutzers an, indem Sie das hToken dieses Benutzers übergeben. Dies geschieht in der Regel im Kontext eines Diensts, der über ausreichende Berechtigungen zum Abrufen des Tokens eines bestimmten Benutzers verfügt. Dieses Token muss mit TOKEN_QUERY - und TOKEN_IMPERSONATE-Rechten geöffnet werden. In einigen Fällen müssen Sie auch TOKEN_DUPLICATE einschließen. Zusätzlich zum Übergeben des hTokens des Benutzers muss die Registrierungsstruktur dieses bestimmten Benutzers eingebunden werden. 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 SHGetKnownFolderPath 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 Dokumente und Desktop. Alle Elemente, die dem Ordner Standardbenutzer hinzugefügt wurden, werden auch in jedem neuen Benutzerkonto angezeigt. Beachten Sie, dass für den Zugriff auf die Standardbenutzerordner Administratorrechte erforderlich sind.

[out] ppszPath

Typ: PWSTR*

Wenn diese Methode zurückgibt, enthält die Adresse eines Zeigers auf eine Unicode-Zeichenfolge mit Null-Beendigung, die den Pfad des bekannten Ordners angibt. Der aufrufende Prozess ist für das Freigeben dieser Ressource verantwortlich, sobald sie nicht mehr benötigt wird, indem CoTaskMemFree aufgerufen wird, unabhängig davon, ob SHGetKnownFolderPath erfolgreich ist oder nicht. 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

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

Rückgabecode	Beschreibung
E_FAIL	Dieser Wert kann unter anderem angeben, dass der rfid-Parameter auf eine KNOWNFOLDERID verweist, die keinen Pfad aufweist (z. B. einen Ordner , der als KF_CATEGORY_VIRTUAL markiert ist).
E_INVALIDARG	Dieser Wert kann unter anderem angeben, dass der rfid-Parameter auf eine KNOWNFOLDERID verweist, die im System nicht vorhanden ist. Nicht alle KNOWNFOLDERID-Werte sind auf allen Systemen vorhanden. Verwenden Sie IKnownFolderManager::GetFolderIds , um den Satz von KNOWNFOLDERID-Werten für das aktuelle System abzurufen.

Hinweise

Diese Funktion ersetzt SHGetFolderPath. Diese ältere Funktion ist jetzt einfach ein Wrapper für SHGetKnownFolderPath.

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shlobj_core.h (einschließlich Shlobj.h)
DLL	Shell32.dll (Version 6.0.6000 oder höher)

Weitere Informationen

IKnownFolder::GetPath

Bekannte Ordner (Beispiel)

SHGetKnownFolderIDList

SHSetKnownFolderPath