SHFileOperationA-Funktion (shellapi.h)
Kopiert, verschiebt, umbenannt oder löscht ein Dateisystemobjekt. Diese Funktion wurde in Windows Vista durch IFileOperationersetzt.
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 Überprüfung des Werts verantwortlich. Wenn Sie sie nicht überprüfen, treten unerwartete Ergebnisse auf.
Rückgabewert
Typ: int
Gibt null zurück, wenn dies erfolgreich ist; andernfalls nonzero. Anwendungen sollten normalerweise einfach auf Null oder Nichtzero prüfen.
Es empfiehlt sich, den Wert der fAnyOperationsAborted Member der SHFILEOPSTRUCTzu untersuchen. SHFileOperation- kann 0 für Erfolg 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 den von Ihnen angeforderten vollständigen Vorgang erfüllt hat, und sie können unter falschen Annahmen fortfahren.
Verwenden Sie GetLastError- nicht mit den Rückgabewerten dieser Funktion.
Um die nichtzero-Werte für Problembehandlungszwecke zu untersuchen, ordnen sie weitgehend den in Winerror.h definierten Werten zu. Einige der möglichen Rückgabewerte basieren jedoch auf Vorab-Win32-Fehlercodes, die in einigen Fällen die späteren Winerror.h-Werte überlappen, ohne deren Bedeutung zu entsprechen. Diese speziellen Werte sind hier detailliert beschrieben, und für diese spezifischen Werte sollten nur diese Bedeutungen über die Winerror.h-Codes akzeptiert werden. Diese Werte werden jedoch mit den folgenden Warnungen bereitgestellt:
- Hierbei handelt es sich um Vor-Win32-Fehlercodes, die in einer öffentlichen Headerdatei nicht mehr unterstützt oder definiert werden. Um sie zu verwenden, müssen Sie sie entweder selbst definieren oder mit dem numerischen Wert vergleichen.
- Diese Fehlercodes können geändert werden 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 | Die 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, der Zielpfad ist jedoch 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 im Hintergrund abgebrochen, wenn die entsprechenden Flags für SHFileOperationbereitgestellt wurden. |
| DE_DESTSUBTREE | 0x76 | Das Ziel ist eine Unterstruktur der Quelle. |
| DE_ACCESSDENIEDSRC | 0x78 | Sicherheitseinstellungen haben den Zugriff auf die Quelle verweigert. |
| DE_PATHTOODEEP | 0x79 | Der Quell- oder Zielpfad wurde überschritten oder überschreitet MAX_PATH. |
| DE_MANYDEST | 0x7A | Der Vorgang umfasste mehrere Zielpfade, die bei einem Verschiebungsvorgang fehlschlagen können. |
| DE_INVALIDFILES | 0x7C | Der Pfad in der Quelle oder am Ziel oder beides war ungültig. |
| DE_DESTSAMETREE | 0x7D | Die Quelle und das 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 datei, die an dem Vorgang beteiligt ist, ist zu groß für das Zielmedium oder Dateisystem. |
| 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 schreibbare CD-ROM, möglicherweise unformatiert. |
| DE_ERROR_MAX | 0xB7 | MAX_PATH wurde während des Vorgangs überschritten. |
| 0x402 | Unbekannter Fehler. Dies liegt in der Regel an einem ungültigen Pfad in der Quelle oder am Ziel. 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. |
Bemerkungen
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. Die Ausnahmen sind die "Meine Dokumente" (CSIDL_PERSONAL, CSIDL_DOCUMENTS) und Ordner "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 FOF_ALLOWUNDO Flag im fFlags Member der SHFILEOPSTRUCT Struktur fest, auf die durch lpFileOpverwiesen wird. Durch Festlegen dieses Kennzeichens wird die Datei an den Papierkorb gesendet. Wenn Sie eine Datei einfach löschen und garantieren möchten, dass sie nicht im Papierkorb abgelegt 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 Member der Struktur fest, auf das durch lpFileOpverwiesen wird. Einzelheiten zur Implementierung von Kopierrückrufhandlern finden Sie unter ICopyHook::CopyCallback-.
Dateilöschung 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 Verbindung einer HTML-Datei mit einem Ordner herzustellen, 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. Umgekehrt wird auch die HTML-Datei verschoben, wenn Sie den Ordner mit den zugehörigen Dateien verschieben.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, in denselben Ordner wie die HTML-Datei einfügen. Der Name des Ordners, der die verbundenen Dateien enthält, muss mit dem Namen der HTML-Datei übereinstimmen, gefolgt von "_files" oder ".files" (dies ist die Groß-/Kleinschreibung, z. B. ". Dateien" funktioniert nicht). Hier ist ein Beispiel angegeben.
- Erstellen Sie eine Datei namens Test.htm im Verzeichnis "C:\Files" (C:\Files\Test.htm).
- Erstellen Sie einen neuen Ordner namens "Test.files" im Verzeichnis "C:\Files" (C:\Files\Test.files).
- Füllen Sie den Ordner mit einigen Dateien auf. Jede Datei, die in diesem Ordner gespeichert ist, ist mit Test.htmverbunden.
- Verschieben oder kopieren Sie die Test.htm Datei in das Verzeichnis "C:\Files2".
- Beachten Sie, dass das Verzeichnis "Test.files" jetzt auch im Verzeichnis "C:\Files2" enthalten ist.
Die Dateiverbindung ist standardmäßig aktiviert. Sie kann deaktiviert werden, indem Sie einen REG_DWORD Eintrag, NoFileFolderConnection, hinzufügen, wie hier gezeigt:
HKEY_CURRENT_USER Software Microsoft Windows CurrentVersion Explorer NoFileFolderConnection
Durch Festlegen von NoFileFolderConnection auf 1 wird die Dateiverbindung deaktiviert. Wenn der Wert auf Null festgelegt ist oder fehlt, ist die Dateiverbindung aktiviert.
Wenn Sie nur die angegebenen Dateien und keine der verbundenen Dateien verschieben möchten, legen Sie das FOF_NO_CONNECTED_ELEMENTS Flag im fFlags Element der Struktur fest, auf das durch lpFileOp-verwiesen wird.
Beachten Sie, dass die Verwendung eines Ordners mit einem Namen wie "MyFile_files" zum Definieren einer Verbindung möglicherweise nicht für lokalisierte Versionen von Windows gültig ist. Der Begriff "Dateien" muss möglicherweise durch das entsprechende Wort in der lokalen Sprache ersetzt werden.
Anmerkung
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 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 2000 Server [nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | shellapi.h |
| Library | Shell32.lib |
| DLL- | Shell32.dll (Version 4.0 oder höher) |
| API-Satz | ext-ms-win-shell-shell32-l1-2-1 (eingeführt in Windows 10, Version 10.0.10240) |