SHFileOperationA-Funktion (shellapi.h)
Kopiert, verschiebt, benennt oder löscht ein Dateisystemobjekt. Diese Funktion wurde in Windows Vista durch IFileOperation ersetzt.
Syntax
int SHFileOperationA(
[in, out] LPSHFILEOPSTRUCTA lpFileOp
);
Parameter
[in, out] lpFileOp
Typ: LPSHFILEOPSTRUCT
Ein Zeiger auf eine SHFILEOPSTRUCT-Struktur , die Informationen enthält, die diese Funktion zum Ausführen des angegebenen Vorgangs benötigt. Dieser Parameter muss einen gültigen Wert enthalten, der nicht NULL ist. Sie sind für die Validierung des Werts verantwortlich. Wenn Sie dies nicht überprüfen, treten unerwartete Ergebnisse auf.
Rückgabewert
Typ: int
Gibt 0 (null) zurück, wenn dies erfolgreich ist. andernfalls ungleich null. Anwendungen sollten normalerweise einfach auf null oder ungleich null überprüfen.
Es empfiehlt sich, den Wert des fAnyOperationsAborted-Elements der SHFILEOPSTRUCT zu untersuchen. SHFileOperation kann 0 zurückgeben, wenn der Benutzer den Vorgang abbricht. Wenn Sie fAnyOperationsAborted sowie den Rückgabewert nicht überprüfen, können Sie nicht wissen, dass die Funktion die von Ihnen angeforderte Aufgabe vollständig erfüllt hat, und Sie können unter falschen Annahmen fortfahren.
Verwenden Sie GetLastError nicht mit den Rückgabewerten dieser Funktion.
Um die Werte ungleich 0 zu Problembehandlungszwecken zu untersuchen, werden sie größtenteils den in Winerror.h definierten Werten zugeordnet. Einige der möglichen Rückgabewerte basieren jedoch auf Vor-Win32-Fehlercodes, die in einigen Fällen die späteren Winerror.h-Werte überlappen, ohne ihrer Bedeutung zu entsprechen. Diese spezifischen Werte werden hier beschrieben, und für diese spezifischen Werte sollten nur diese Bedeutungen gegenüber den Winerror.h-Codes akzeptiert werden. Diese Werte werden jedoch mit den folgenden Warnungen bereitgestellt:
- Dies sind Fehlercodes vor Win32 und werden in keiner öffentlichen Headerdatei mehr unterstützt oder definiert. Um sie zu verwenden, müssen Sie sie entweder selbst definieren oder mit dem numerischen Wert vergleichen.
- Diese Fehlercodes können sich ändern und haben dies in der Vergangenheit getan.
- Diese Werte werden nur als Hilfe beim Debuggen bereitgestellt. Sie sollten nicht als endgültig angesehen werden.
| Fehlercode | Wert | Bedeutung |
|---|---|---|
| DE_SAMEFILE | 0x71 | Quell- und Zieldateien sind dieselbe Datei. |
| DE_MANYSRC1DEST | 0x72 | Im Quellpuffer wurden mehrere Dateipfade angegeben, aber nur ein Zieldateipfad. |
| DE_DIFFDIR | 0x73 | Der Umbenennungsvorgang wurde angegeben, aber der Zielpfad ist ein anderes Verzeichnis. Verwenden Sie stattdessen den Verschiebungsvorgang. |
| DE_ROOTDIR | 0x74 | Die Quelle ist ein Stammverzeichnis, das nicht verschoben oder umbenannt werden kann. |
| DE_OPCANCELLED | 0x75 | Der Vorgang wurde vom Benutzer abgebrochen oder automatisch abgebrochen, wenn die entsprechenden Flags für SHFileOperation bereitgestellt wurden. |
| DE_DESTSUBTREE | 0x76 | Das Ziel ist eine Teilstruktur der Quelle. |
| DE_ACCESSDENIEDSRC | 0x78 | Sicherheitseinstellungen haben den Zugriff auf die Quelle verweigert. |
| DE_PATHTOODEEP | 0x79 | Der Quell- oder Zielpfad hat MAX_PATH überschritten oder überschritten. |
| DE_MANYDEST | 0x7A | Der Vorgang umfasste mehrere Zielpfade, die im Falle eines Verschiebungsvorgangs fehlschlagen können. |
| DE_INVALIDFILES | 0x7C | Der Pfad in der Quelle oder dem Ziel oder beides war ungültig. |
| DE_DESTSAMETREE | 0x7D | Quelle und Ziel haben denselben übergeordneten Ordner. |
| DE_FLDDESTISFILE | 0x7E | Der Zielpfad ist eine vorhandene Datei. |
| DE_FILEDESTISFLD | 0x80 | Der Zielpfad ist ein vorhandener Ordner. |
| DE_FILENAMETOOLONG | 0x81 | Der Name der Datei überschreitet MAX_PATH. |
| DE_DEST_IS_CDROM | 0x82 | Das Ziel ist eine schreibgeschützte CD-ROM, möglicherweise unformatiert. |
| DE_DEST_IS_DVD | 0x83 | Das Ziel ist eine schreibgeschützte DVD, möglicherweise unformatiert. |
| DE_DEST_IS_CDRECORD | 0x84 | Das Ziel ist eine beschreibbare CD-ROM, möglicherweise unformatiert. |
| DE_FILE_TOO_LARGE | 0x85 | Die am Vorgang beteiligte Datei ist für das Zielmedium oder dateisystem zu groß. |
| DE_SRC_IS_CDROM | 0x86 | Die Quelle ist eine schreibgeschützte CD-ROM, möglicherweise unformatiert. |
| DE_SRC_IS_DVD | 0x87 | Die Quelle ist eine schreibgeschützte DVD, möglicherweise unformatiert. |
| DE_SRC_IS_CDRECORD | 0x88 | Die Quelle ist eine beschreibbare CD-ROM, möglicherweise unformatiert. |
| DE_ERROR_MAX | 0xB7 | MAX_PATH wurde während des Vorgangs überschritten. |
| 0x402 | Unbekannter Fehler aufgetreten. Dies ist in der Regel auf einen ungültigen Pfad in der Quelle oder dem Ziel zurückzuführen. Dieser Fehler tritt unter Windows Vista und höher nicht auf. | |
| ERRORONDEST | 0x10000 | Am Ziel ist ein nicht angegebener Fehler aufgetreten. |
| DE_ROOTDIR | ERRORONDEST | 0x10074 | Ziel ist ein Stammverzeichnis und kann nicht umbenannt werden. |
Hinweise
Sie sollten vollqualifizierte Pfadnamen mit dieser Funktion verwenden. Die Verwendung mit relativen Pfadnamen ist nicht threadsicher.
Mit zwei Ausnahmen können Sie SHFileOperation nicht verwenden, um spezielle Ordner von einem lokalen Laufwerk auf einen Remotecomputer zu verschieben, indem Sie einen Netzwerkpfad angeben. Ausnahmen sind die Ordner Eigene Dokumente (CSIDL_PERSONAL, CSIDL_DOCUMENTS) und Meine Bilder (CSIDL_MYPICTURES).
Wenn sie zum Löschen einer Datei verwendet wird, löscht SHFileOperation die Datei dauerhaft, es sei denn, Sie legen das flag FOF_ALLOWUNDO im fFlags-Element der SHFILEOPSTRUCT-Struktur fest, auf die von lpFileOp verwiesen wird. Durch Festlegen dieses Flags wird die Datei in den Papierkorb gesendet. Wenn Sie eine Datei einfach löschen und sicherstellen möchten, dass sie nicht im Papierkorb platziert wird, verwenden Sie DeleteFile.
Wenn ein Kopierrückrufhandler verfügbar gemacht und registriert wird, ruft SHFileOperation ihn auf, es sei denn, Sie legen ein Flag wie FOF_NOCONFIRMATION im fFlags-Element der Struktur fest, auf die von lpFileOp verwiesen wird. Weitere Informationen zum Implementieren von Kopierrückrufhandlern finden Sie unter ICopyHook::CopyCallback .
Das Löschen von Dateien ist rekursiv, es sei denn, Sie legen das FOF_NORECURSION-Flag in lpFileOp fest.
Verbinden von Dateien
Mit Windows 2000 oder höher ist es möglich, eine HTML-Datei mit einem Ordner zu verbinden , der verwandte Dateien wie GIF-Bilder (Graphics Interchange Format) oder Stylesheets enthält. Wenn die Dateiverbindung aktiviert ist, werden beim Verschieben oder Kopieren der HTML-Datei auch der verbundene Ordner und alle zugehörigen Dateien verschoben oder kopiert. Wenn Sie hingegen den Ordner mit den zugehörigen Dateien verschieben, wird auch die HTML-Datei verschoben.Die HTML-Datei muss über eine .htm- oder .html-Erweiterung verfügen. Sie erstellen die Verbindung mit den zugehörigen Dateien, indem Sie den Ordner, der sie enthält, im selben Ordner wie die HTML-Datei ablegen. Der Name des Ordners, der die verbundenen Dateien enthält, muss mit dem Namen der HTML-Datei gefolgt von "_files" oder ".files" identisch sein (hierbei wird die Groß-/Kleinschreibung beachtet, z. B. ". Dateien" funktioniert nicht). Hier finden Sie ein Beispiel.
- Erstellen Sie eine Datei mit dem Namen Test.htm im Verzeichnis C:\Files (C:\Files\Test.htm).
- Erstellen Sie einen neuen Ordner mit dem Namen Test.files im Verzeichnis C:\Files (C:\Files\Test.files).
- Füllen Sie den Ordner mit einigen Dateien auf. Jede Datei, die sich in diesem Ordner befindet, ist mit Test.htm verbunden.
- Verschieben oder kopieren Sie die Test.htm-Datei in das Verzeichnis C:\Files2.
- Beachten Sie, dass sich das Verzeichnis Test.files jetzt auch im Verzeichnis C:\Files2 befindet.
Die Dateiverbindung ist standardmäßig aktiviert. Sie kann deaktiviert werden, indem Sie wie hier gezeigt einen REG_DWORD Eintrag NoFileFolderConnection hinzufügen:
HKEY_CURRENT_USER Software Microsoft Windows CurrentVersion Explorer NoFileFolderConnection
Wenn NoFileFolderConnection auf 1 festgelegt wird, wird die Dateiverbindung deaktiviert. Wenn der Wert auf 0 festgelegt ist oder fehlt, ist die Dateiverbindung aktiviert.
Um nur die angegebenen Dateien und keine der verbundenen Dateien zu verschieben, legen Sie das FOF_NO_CONNECTED_ELEMENTS-Flag im fFlags-Element der Struktur fest, auf die von lpFileOp verwiesen wird.
Beachten Sie, dass die Verwendung eines Ordners mit einem Namen wie "MyFile_files" zum Definieren einer Verbindung für lokalisierte Versionen von Windows möglicherweise nicht gültig ist. Der Begriff "files" muss möglicherweise durch das entsprechende Wort in der lokalen Sprache ersetzt werden.
Hinweis
Der shellapi.h-Header definiert SHFileOperation als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch 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 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | shellapi.h |
| Bibliothek | Shell32.lib |
| DLL | Shell32.dll (Version 4.0 oder höher) |
| APIs | ext-ms-win-shell-shell32-l1-2-1 (eingeführt in Windows 10, Version 10.0.10240) |
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für