Bezeichnung
CopyFile -- kopiert eine Datei oder ein Verzeichnis (V2.0)
Übersicht
CopyFile(src$, dst$[, t])
Frühere syntax
CopyFile(src$, dst$[, newname$, func, userdata, pattern$, matchdir])
Beschreibung
Dieser Befehl kopiert die Datei oder das Verzeichnis in src$ in das in dst$ angegebene Verzeichnis. Beachten Sie, dass vorhandene Dateien standardmäßig ohne Nachfrage überschrieben werden. Sie können dieses Verhalten anpassen, indem Sie eine Callback-Funktion angeben (siehe unten). Beachten Sie auch, dass Sie in dst$ ein Verzeichnis und keine Datei angeben müssen.

Dieser Befehl ist mächtig. Es wird vollständig rekursiv alle Unterverzeichnisse erfassen und kopiert außerdem die Dateiattribute, Datumsstempel und Kommentare. Wenn das Zielverzeichnis nicht vorhanden ist, wird es für Sie erstellt werden (auch wenn es Verzeichnisse enthält, die noch nicht existieren). Alle Pfadangaben können lokal in das aktuelle Verzeichnis verweisen. Sie können somit auch Dateien in das aktuelle Verzeichnis kopieren, indem Sie "" als dst$ angeben.

CopyFile() unterstützt viele optionale Argumente. Vor Hollywood 9.0 mussten diese als optionale Parameter übergeben werden (siehe oben). Seit Hollywood 9.0 wird jedoch empfohlen, die neue Syntax zu verwenden, die ein einzelnes optionales Tabellenargument hat, mit dem ein oder mehrere optionale Argumente an CopyFile() übergeben werden können.

Die folgenden Tabellenfelder werden von diesem Befehl erkannt:

NewName:
Wenn Sie den Namen der Datei beim Kopieren ändern möchten, setzen Sie dieses Feld auf den gewünschten neuen Namen für die Datei. Das Setzen dieses Feldes ist natürlich nur sinnvoll, wenn Sie eine Datei in src$ angeben.

Pattern:
Sie können in diesem Tabellenfeld ein Filtermuster übergeben. In diesem Fall kopiert CopyFile() nur die Dateien, die dem angegebenen Muster entsprechen. Wenn Sie beispielsweise .jpg in Pattern angeben, werden nur Dateien kopiert, die die Dateierweiterung .jpg verwenden. Natürlich macht die Verwendung eines Filtermusters nur dann Sinn, wenn Sie ein Verzeichnis in src$ übergeben. Beachten Sie, dass aus historischen Gründen das in Pattern angegebene Muster auch mit allen zu kopierenden Unterverzeichnissen abgeglichen wird, die kopiert werden sollen. Wenn Sie das nicht möchten, setzen Sie das Tabellen-Tag MatchDir auf False (siehe unten). Das in Pattern angegebene Muster muss den Musterregeln entsprechen, die in der Dokumentation des Befehls MatchPattern() beschrieben sind. Siehe MatchPattern für Details. (V5.0)

MatchDir:
Dieses Tabellenfeld gibt an, ob das in Pattern angegebene Filtermuster auch mit Unterverzeichnissen abgeglichen werden soll oder nicht. Wenn dies auf True gesetzt ist, rekursiert CopyFile() nur in Unterverzeichnisse, die dem angegebenen Filtermuster entsprechen. Wenn es auf False gesetzt ist, rekursiert CopyFile() in alle Unterverzeichnisse. Aus Kompatibilitätsgründen ist MatchDir standardmäßig auf True gesetzt, aber meistens möchten Sie hier False übergeben, da es normalerweise keinen Sinn macht, ein Dateimuster mit einem Verzeichnisnamen abzugleichen. Es macht beispielsweise keinen Sinn, das obige Beispiel *.jpg auch mit Verzeichnissen abzugleichen. (V5.0)

BufferSize:
In diesem Tabellenfeld kann die Puffergröße eingestellt werden, die zum Kopieren von Dateien verwendet werden soll. Der hier übergebene Wert muss in Bytes angegeben werden. Der Standardwert ist 16384, also 16 Kilobyte. (V9.0)

FailOnError:
Standardmäßig schlägt CopyFile() fehl, wenn ein Fehler auftritt. Sie können dieses Verhalten ändern, indem Sie FailOnError auf False setzen. In diesem Fall schlägt CopyFile() bei einem Fehler nicht fehl, stattdessen wird Ihre Callback-Funktion, falls vorhanden, mit der Meldung #COPYFILE_FAILED benachrichtigt und Ihre Callback-Funktion muss CopyFile() mitteilen, wie es weitergeht (Wiederholen, Fortfahren, Abbrechen). Siehe unten, um zu erfahren, wie man eine Callback-Funktion für CopyFile() einrichtet. Die Voreinstellung für FailOnError ist True. (V9.0)

Force:
Wenn dieser Tag auf True gesetzt ist, werden schreib- oder löschgeschützte Dateien automatisch überschrieben, ohne vorher die Callback-Funktion abzufragen. Beachten Sie, dass CopyFile() fehlschlägt, wenn es keine Callback-Funktion gibt und Force auf False (Standard) gesetzt ist, wenn es eine Datei nicht überschreiben kann, da diese Datei schreib- oder löschgeschützt ist. Die Voreinstellung ist False. (V9.0)

Async:
Wenn dies auf True gesetzt ist, arbeitet CopyFile() im asynchronen Modus. Das bedeutet, dass der Befehl sofort zurückkehrt und falls Ihr Skript während des Vorgangs etwas anderes tun muss, Ihnen ein asynchroner Operationshandler übergibt. Sie können dann diesen asynchroner Operationshandler verwenden, um den Vorgang abzuschließen, indem Sie wiederholt ContinueAsyncOperation() aufrufen, bis True zurückgegeben wird. Dies ist sehr nützlich, z.B. für die Anzeige eines Fortschrittsbalken oder ähnlichem. Indem Sie CopyFile() in den asynchronen Modus versetzen, ist es Ihrem Skript leicht möglich, während der Verarbeitung des Vorgangs etwas anderes zu tun. Siehe ContinueAsyncOperation für Details. Voreingestellt ist False. (V9.0)

Adapter:
Mit diesem Tag können Sie einen oder mehrere Dateiadapter angeben, welche die Quelldatei oder das Quellverzeichnis öffnen. Wenn Sie diesen Tag verwenden, müssen Sie ihn auf eine Zeichenkette setzen, die den Namen eines oder mehrerer Adapter enthält. Standardmäßig wird der Adapter verwendet, der mit SetDefaultAdapter() gesetzt wurde. Siehe Lader und Adapter für Details. (V10.0)

UserTags:
Dieser Tag kann verwendet werden, um zusätzliche Daten anzugeben, die an den Dateiadapter übergeben werden sollen. Wenn Sie diesen Tag verwenden, müssen Sie ihn auf eine Tabelle mit Schlüssel-Wert-Paaren setzen, die die zusätzlichen Daten enthalten, die an Plugins übergeben werden sollen. Siehe Benutzer-Tags für Details. (V10.0)

DstAdapter:
Mit diesem Tag können Sie einen oder mehrere Dateisystemadapter angeben, alle Operationen auf der Seite des Kopierziels auszuführen. Der hier angegebene Dateisystemadapter ist beispielsweise für das Erstellen von Verzeichnissen und das Setzen von Datei- und Verzeichnisattributen zuständig. Dies muss auf eine Zeichenkette festgelegt werden, die den Namen eines oder mehrerer Adapter enthält. Der Standardwert ist default. Siehe Lader und Adapter für Details. (V10.0)

DstUserTags:
Dieser Tag kann verwendet werden, um zusätzliche Daten anzugeben, die an Dateisystemadapter übergeben werden sollen, die in DstAdapter angegeben sind. Siehe oben für Details. Wenn Sie diesen Tag verwenden, müssen Sie ihn auf eine Tabelle mit Schlüssel-Wert-Paaren setzen, die die zusätzlichen Daten enthalten, die an Plugins übergeben werden sollen. Siehe Benutzer-Tags für Details. (V10.0)

Callback:
Dieses Tabellenfeld kann verwendet werden, um eine Callback-Funktion zu übergeben, die von CopyFile() bei verschiedenen Gelegenheiten aufgerufen wird, damit Sie beispielsweise einen Fortschrittsbalken aktualisieren können. Die Callback-Funktion wird auch aufgerufen, wenn bereits eine Zieldatei existiert oder sie schreib-/löschgeschützt ist. Die Callback-Funktion erhält ein Argument: Eine Tabelle, die weitere Informationen enthält.

Die folgenden Callback-Typen sind verfügbar:

#COPYFILE_OVERWRITE:
CopyFile() führt diesen Callback aus, um zu fragen, ob eine Datei überschrieben werden kann. Ihre Callback-Funktion muss True zurückgeben, wenn die Datei überschrieben werden soll oder False, wenn sie übersprungen werden soll. Um den Kopiervorgang vollständig abzubrechen, geben Sie -1 zurück. Die folgenden Felder werden im Tabellenparameter gesetzt, der an Ihre Callback-Funktion übergeben wird:

Action:
#COPYFILE_OVERWRITE

Source:
Enthält den vollständigen Pfad der zu kopierenden Datei.

Destination:
Enthält den vollständigen Pfad der Datei, die bereits vorhanden ist.

UserData:
Enthält den Wert, den Sie im Tabellenfeld UserData übergeben haben (siehe unten).

#COPYFILE_UNPROTECT:
Die Callback-Funktion vom Typ #COPYFILE_UNPROTECT wird aufgerufen, wenn die zu überschreibende Datei schreib- oder löschgeschützt ist. Diese Callback-Funktion muss True zurückgeben, wenn der Schutz der Datei aufgehoben werden kann, oder False, wenn sie übersprungen werden soll. Wenn Sie -1 zurückgeben, wird der Kopiervorgang vollständig abgebrochen.

Ab Hollywood 9.0 kann Ihre Callback-Funktion auch -2 zurückgeben, um anzugeben, dass das Kopieren trotzdem versucht werden soll, obwohl die Datei schreib- oder löschgeschützt ist. Dies führt jedoch in der Regel zu einem Fehler, da schreib- oder löschgeschützte Dateien nicht überschrieben werden können, ohne den Schutz zuvor aufzuheben. Wenn Sie jedoch -2 zurückgeben, können Sie den folgenden Fehler in Ihrem #COPYFILE_FAILED-Callback abfangen, wenn Sie FailOnError auf False gesetzt haben (siehe oben).

Die folgenden Felder werden im Tabellenparameter gesetzt, der an Ihre Callback-Funktion übergeben wird:

Action:
#COPYFILE_UNPROTECT

Destination:
Enthält die schreib- oder löschgeschützte Zieldatei, deren Schutz aufgehoben werden soll.

UserData:
Enthält den Wert, den Sie im Tabellenfeld UserData übergeben haben (siehe unten).

#COPYFILE_STATUS:
Diese Callback-Funktion wird von Zeit zu Zeit ausgeführt, damit Sie eine Statusleiste oder ähnliches aktualisieren können. Die Callback-Funktion vom Typ #COPYFILE_STATUS sollte normalerweise False zurückgeben. Wenn True zurückgegeben wird, wird der Kopiervorgang abgebrochen. Die folgenden Felder werden im Tabellenparameter gesetzt, der an Ihre Callback-Funktion übergeben wird:

Action:
#COPYFILE_STATUS

Source:
Enthält den vollständigen Pfad der Datei, die gerade kopiert wird (Quelle).

Destination:
Enthält den vollständigen Pfad der Datei, die gerade geschrieben wird (Ziel).

Copied:
Enthält die Anzahl der Bytes, die bereits kopiert wurden.

Filesize:
Enthält die Dateigröße der Quelldatei.

UserData:
Enthält den Wert, den Sie im Tabellenfeld UserData übergeben haben (siehe unten).

#COPYFILE_FAILED:
Dieser Callback kann nur aufgerufen werden, wenn der Tag FailOnError auf False gesetzt wurde (siehe oben). In diesem Fall wird die Callback-Funktion vom Typ #COPYFILE_FAILED immer dann aufgerufen, wenn ein Kopiervorgang fehlgeschlagen ist. Es muss True zurückgegeben werden, um den Kopiervorgang abzubrechen, False, um fortzufahren, obwohl ein Fehler aufgetreten ist, oder -1, um den gerade fehlgeschlagenen Kopiervorgang erneut zu versuchen. Die folgenden Felder werden im Tabellenparameter gesetzt, der an Ihre Callback-Funktion übergeben wird:

Action:
#COPYFILE_FAILED

Source:
Enthält den vollständigen Pfad der Datei, die gerade kopiert wird (Quelle).

Destination:
Enthält den vollständigen Pfad der Datei, die gerade geschrieben wird (Ziel).

UserData:
Enthält den Wert, den Sie im Tabellenfeld UserData übergeben haben (siehe unten).

(V9.0)

UserData:
Dieses Feld kann verwendet werden, um Ihrer Callback-Funktion einen beliebigen Wert zu übergeben. Der hier angegebene Wert wird bei jedem Aufruf an Ihre Callback-Funktion übergeben. Dies ist nützlich, wenn Sie vermeiden möchten, mit globalen Variablen zu arbeiten. Mit dem Tag UserData können Sie ganz einfach Daten an Ihre Callback-Funktion übergeben. Sie können in UserData einen beliebigen Wert beliebigen Typs angeben. Als Benutzerdaten können Zahlen, Zeichenketten, Tabellen und sogar Funktionen übergeben werden. Ihre Callback-Funktion erhält diese Daten im Feld UserData in der ihm übergebenen Tabelle. (V5.1)

Siehe auch DeleteFile(), MoveFile(), Rename() und Exists().

Eingaben
src$
die zu kopierende Quelldatei oder Verzeichnis
dst$
Zielverzeichnis
t
optional: Tabelle mit zusätzlichen Optionen (siehe oben) (V9.0)
Beispiel
CopyFile("image.png", "TestDir")
Kopiert die Datei "image.png" aus dem aktuellen Verzeichnis nach "TestDir".


CopyFile("Images", "Images_Bak")
Erstellt eine Sicherung des Verzeichnis "Images" im "Images_Bak" Verzeichnis (das neue Verzeichnis wird durch diesen Befehl automatisch erstellt). Alle Dateien inklusive Unterverzeichnisse werden an den neuen Speicherort kopiert werden.


CopyFile("Hollywood_Sources/WarpOS", "HW_BAK", {Pattern = "*.c;*.h",
    MatchDir = False})
Kopiert alle Quellcode und Header-Dateien von Hollywood_Sources/WarpOS nach HW_BAK.


Function p_CopyCallback(msg)
  Switch msg.action
  Case #COPYFILE_STATUS:
    DebugPrint("Now copying", FilePart(msg.source), "to",
               PathPart(msg.destination))
  Case #COPYFILE_OVERWRITE:
    Return(SystemRequest("Hollywood", FilePart(msg.destination) ..
      " does already exist!\nDo you want me to overwrite it?",
      "Yes|No"))
  Case #COPYFILE_UNPROTECT:
    Return(SystemRequest("Hollywood", FilePart(msg.destination) ..
      " is write/delete protected!\nDo you want me to unprotect it?",
      "Yes|No"))
  EndSwitch
  Return(False)
EndFunction
CopyFile("Images", "Copy_of_Images", {Callback = p_CopyCallback})
Demonstriert die Verwendung einer Callback-Funktion.

Navigation zeigen