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.

1. Erstellen Sie eine Datei mit dem Namen Test.htm im Verzeichnis C:\Files (C:\Files\Test.htm).
2. Erstellen Sie einen neuen Ordner mit dem Namen Test.files im Verzeichnis C:\Files (C:\Files\Test.files).
3. Füllen Sie den Ordner mit einigen Dateien auf. Jede Datei, die sich in diesem Ordner befindet, ist mit Test.htm verbunden.
4. Verschieben oder kopieren Sie die Test.htm-Datei in das Verzeichnis C:\Files2.
5. 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.

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)