SHSetFolderPathA-Funktion (shlobj_core.h)

Artikel
11/20/2024

Veraltet. Weist einem systemordner, der durch die 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 ist, schlägt diese Funktion fehl.

Fügen Sie den CSIDL_FLAG_DONT_UNEXPAND Wert zur CSIDL 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 wie %USERPROFILE%ersetzt werden.

[in] hToken

Typ: HANDLE

Ein Zugriffstoken, das verwendet werden kann, um einen bestimmten Benutzer darzustellen. Dieser Parameter wird in der Regel auf NULL-festgelegt. In diesem Fall versucht die Funktion, auf die Instanz des ordners des aktuellen Benutzers zuzugreifen. Sie müssen jedoch möglicherweise einen Wert hToken- für ordner zuweisen, die mehrere Benutzer haben können, aber als Zugehörigkeit zu einem einzelnen Benutzer behandelt werden. Der am häufigsten verwendete Ordner dieses Typs ist Documents.

Die aufrufende Anwendung ist für den korrekten Identitätswechsel verantwortlich, wenn hToken- ungleich NULL ist. Sie 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 .

[in] dwFlags

Typ: DWORD-

Reserviert. Muss auf 0 festgelegt sein.

[in] pszPath

Typ: LPCTSTR-

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

Rückgabewert

Typ: HRESULT-

Gibt standardmäßige HRESULT--Codes zurück, einschließlich der folgenden:

Rückgabecode	Beschreibung
S_OK	Der Pfad des Ordners wurde erfolgreich aktualisiert.
E_INVALIDARG	Mehrere Fehlerbedingungen verursachen die Rückgabe dieses Werts, einschließlich der folgenden: Der csidl Wert ist ungültig. Der wert csidl 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 pszPath Wert verweist, ist eine leere Zeichenfolge ("") der Länge Null.

Rückgabecode

Beschreibung

S_OK

Der Pfad des Ordners wurde erfolgreich aktualisiert.

E_INVALIDARG

Mehrere Fehlerbedingungen verursachen die Rückgabe dieses Werts, einschließlich der folgenden:

Der csidl Wert ist ungültig.
Der wert csidl 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 pszPath Wert verweist, ist eine leere Zeichenfolge ("") der Länge Null.

Bemerkungen

Note As of Windows Vista, this function is lediglich a wrapper for SHSetKnownFolderPath. Der CSIDL-Wert wird in die zugeordnete KNOWNFOLDERID- übersetzt und SHSetKnownFolderPath- 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 anhand des Namens aus Shell32.dllexportiert. Um die Funktion zu verwenden, müssen Sie GetProcAddress- mit Ordinal 231 für SHSetFolderPathA- (für ANSI-Zeichenfolgen) oder Ordnungszahl 232 für SHSetFolderPathW- (für Unicode-Zeichenfolgen) aufrufen, um einen Funktionszeiger abzurufen.

Es wird empfohlen, die Pfade als Unicode-Zeichenfolgen ausgedrückt zu werden, da Ordnernamen unicode-Zeichen enthalten können, die in ANSI nicht ausgedrückt werden können.

Anmerkung

Der header shlobj_core.h 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 Code, der nicht codierungsneutral ist, 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
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	shlobj_core.h (einschließlich Shlobj.h, Shlobj_core.h)
Library	Shell32.lib
DLL-	Shell32.dll (Version 5.0 oder höher)

Siehe auch

IKnownFolder::SetPath

Freigeben über