Freigeben über

SHFileOperationA-Funktion (shellapi.h)

  • Artikel

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.

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)