SHSetFolderPathA-Funktion (shlobj_core.h)

Artikel
03/02/2024

Veraltet. Weist einem Systemordner, der durch seine CSIDL identifiziert wird, einen neuen Pfad zu.

Syntax

HRESULT SHSetFolderPathA(
  [in] int    csidl,
  [in] HANDLE hToken,
  [in] DWORD  dwFlags,
  [in] LPCSTR pszPath
);

Parameter

[in] csidl

Typ: int

Ein CSIDL-Wert , der den Ordner identifiziert, dessen Pfad festgelegt werden soll. Nur physische Ordner sind gültig. Wenn ein virtueller Ordner angegeben wird, schlägt diese Funktion fehl.

Fügen Sie der CSIDL den wert CSIDL_FLAG_DONT_UNEXPAND hinzu, um sicherzustellen, dass die Zeichenfolge genau wie angegeben in die Registrierung geschrieben wird. Wenn das CSIDL_FLAG_DONT_UNEXPAND-Flag nicht enthalten ist, können Teile des Pfads durch Umgebungszeichenfolgen ersetzt werden, z. B. %USERPROFILE%.

[in] hToken

Typ: HANDLE

Ein Zugriffstoken , das verwendet werden kann, um einen bestimmten Benutzer darzustellen. Dieser Parameter wird normalerweise auf NULL festgelegt. In diesem Fall versucht die Funktion, auf die instance des aktuellen Benutzers des Ordners zuzugreifen. Möglicherweise müssen Sie hToken jedoch einen Wert 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.

Die aufrufende Anwendung ist für den korrekten Identitätswechsel verantwortlich, wenn hToken nicht NULL ist. Es muss über geeignete 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.

[in] dwFlags

Art: DWORD

Reserviert. Muss auf 0 festgelegt werden.

[in] pszPath

Typ: LPCTSTR

Ein Zeiger auf eine null-beendete Zeichenfolge mit der Länge MAX_PATH, die den neuen Pfad des Ordners enthält. Dieser Wert darf nicht NULL sein, und die Zeichenfolge darf keine Länge von 0 sein.

Rückgabewert

Typ: HRESULT

Gibt HRESULT-Standardcodes zurück, einschließlich der folgenden:

Rückgabecode	BESCHREIBUNG
S_OK	Der Pfad des Ordners wurde erfolgreich aktualisiert.
E_INVALIDARG	Mehrere Fehlerbedingungen führen zur Rückgabe dieses Werts, einschließlich der folgenden: Der csidl-Wert ist ungültig. Der csidl-Wert verweist nicht auf einen virtuellen Ordner. Der csidl-Wert verweist nicht auf einen Systemordner. Der csidl-Wert bezieht sich auf einen Ordner, der nicht umbenannt oder verschoben werden kann. Der dwFlags-Wert ist nicht 0 (null). Der PszPath-Wert ist NULL. Die Zeichenfolge, auf die vom pszPath-Wert verwiesen wird, ist eine leere Zeichenfolge ("") der Länge 0.

Rückgabecode

BESCHREIBUNG

S_OK

Der Pfad des Ordners wurde erfolgreich aktualisiert.

E_INVALIDARG

Mehrere Fehlerbedingungen führen zur Rückgabe dieses Werts, einschließlich der folgenden:

Der csidl-Wert ist ungültig.
Der csidl-Wert verweist nicht auf einen virtuellen Ordner.
Der csidl-Wert verweist nicht auf einen Systemordner.
Der csidl-Wert bezieht sich auf einen Ordner, der nicht umbenannt oder verschoben werden kann.
Der dwFlags-Wert ist nicht 0 (null).
Der PszPath-Wert ist NULL.
Die Zeichenfolge, auf die vom pszPath-Wert verwiesen wird, ist eine leere Zeichenfolge ("") der Länge 0.

Hinweise

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

SHSetFolderPath wird nicht nach Name aus Shell32.dll exportiert. Um die Funktion zu verwenden, müssen Sie GetProcAddress mit Ordinal 231 für SHSetFolderPathA (für ANSI-Zeichenfolgen) oder Ordinal 232 für SHSetFolderPathW (für Unicode-Zeichenfolgen) aufrufen, um einen Funktionszeiger zu erhalten.

Es wird empfohlen, die Pfade als Unicode-Zeichenfolgen auszudrücken, da Ordnernamen unicode-Zeichen enthalten können, die in ANSI nicht expressierbar sind.

Hinweis

Der shlobj_core.h-Header definiert SHSetFolderPath als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	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, Shlobj_core.h)
Bibliothek	Shell32.lib
DLL	Shell32.dll (Version 5.0 oder höher)

Weitere Informationen

IKnownFolder::SetPath

Freigeben über