Bezeichnung
DownloadFile -- lädt Dateien über HTTP-, FTP- oder ein anderes Protokoll herunter (V5.0)
Übersicht
data$, count = DownloadFile(url$[, options, func, userdata])
Beschreibung
Mit diesem Befehl können Sie bequem eine Datei von einem beliebigen Netzwerk-Server herunterladen. Standardmäßig werden HTTP- und FTP-Server genutzt, aber Hollywood-Plugins können weitere Protokolle unterstützen. Sie müssen die URL der Datei im Argument url$ übergeben. DownloadFile() lädt dann die Datei herunter und gibt sie als Zeichenkette in data$ zurück. Die Speicherung binärer Daten in Zeichenketten ist möglich, weil die Zeichenketten von Hollywood nicht auf druckbare Zeichen beschränkt sind. Stattdessen können sie auch Steuerzeichen und das Nullzeichen enthalten. Der zweite Rückgabewert count gibt die Größe der heruntergeladenen Datei in Byte an.

Alternativ können Sie auch den Tag File im optionalen Tabellenargument options auf einen Dateinamen setzen. In diesem Fall wird die heruntergeladene Datei nicht als Zeichenkette zurückgegeben, sondern als die im Tag File angegebene Datei gespeichert. Dies wird für größere Dateien empfohlen, da Zeichenketten offensichtlich im Speicher gespeichert werden. Das Herunterladen einer großen Datei in eine Zeichenkette ist daher im Allgemeinen keine gute Idee, da dies viel Speicher benötigt.

Die URL, die in url$ übergeben wird, muss mit einem Protokollpräfix beginnen wie http:// oder ftp:// und darf keine ESC-Zeichen enthalten. Die ESC-Zeichenumwandlung wird durch DownloadFile() durchgeführt, so stellen Sie sicher, dass Sie nur unverschlüsselte URLs übergeben. Das bedeutet, dass z.B. die URL "http://www.mysite.net/cool%20file.html" nicht funktionieren wird. Sie müssen eine URL ohne ESC-Zeichen angeben, womit die korrekte Version wäre: "http://www.mysite.net/cool file.html". Wenn Sie eine bereits übergebene URL übergeben wollen, müssen Sie den Tag Encoded auf True setzen (siehe unten). In diesem Fall wird DownloadFile() keine weiteren ESC-Zeichenumwandlungen auf Ihre URL anwenden.

DownloadFile() unterstützt auch die Authentifizierung für die HTTP- und FTP-Protokolle. In diesem Fall müssen Benutzername und Passwort nach der Protokollkennung im Formular username:password übergeben werden, gefolgt von einem @-Zeichen und dem Server. Hier ist ein Beispiel für den Benutzer "joe" und das Passwort "secret": http://joe:secret@www.test.net/private/files.lha. Beachten Sie, dass HTTP-Authentifizierungsunterstützung vor Hollywood 6.0 nicht verfügbar war. Beim Herunterladen von einem FTP-Server, wird "anonymous" als Standard-Benutzername und "anonymous@anonymous.org" als das Standard-Passwort verwendet. Wenn Sie ein anderes Anmeldekonto verwenden möchten, müssen Sie die Benutzername/Passwort-Kombination in der URL übergeben, z.B: ftp://joe:secret@ftp.test.net/pub/files.lha.

Die an diesen Befehl übergebene URL kann auch eine Portnummer enthalten. Wenn Sie eine Portnummer angeben möchten, müssen Sie sie hinter dem Hostnamen setzen und mit einem Doppelpunkt trennen. Hier ist ein Beispiel für die Verwendung von Port 1234: http://www.test.com:1234/test/image.jpg. Wenn kein Port angegeben wird, verwendet DownloadFile() Port 80 für HTTP-Server und Port 21 für FTP-Server.

Mit dem zweiten Argument options können weitere Optionen für den Download angegeben werden. Es ist eine Tabelle, die die folgende Felder erkennt:

File:
Wenn Sie einen Dateinamen in diesem Tabellenfeld angeben, lädt DownloadFile() die heruntergeladenen Daten direkt in diese Datei, anstatt sie als Zeichenkette zurückzugeben. Dies ist für sehr große Dateien auf der einen Seite, aber es ist auch nützlich für andere Dateien, weil es Ihnen die Mühe erspart, die Daten in Zeichenketten manuell in eine Datei zu speichern und danach die Zeichenfolge auf Nil zu setzen. Wenn Sie also die heruntergeladene Zeichenkette in einer Datei speichern möchten, ist es effizienter, dieses Feld zu verwenden. Wenn Sie es nicht verwenden, lesen Sie bitte unten die wichtigen Informationen fürs Herunterladen von Dateien in Zeichenketten.

TransferMode:
Dieser Tag wird nur beim Herunterladen von Dateien von einer FTP-Quelle unterstützt. In diesem Fall können Sie mit diesem Tag angeben, ob DownloadFile() die Datei im ASCII oder im Binärmodus übertragen soll. Im ASCII-Modus geben Sie hier #FTPASCII an. Verwenden Sie für den Binärmodus #FTPBINARY. Der voreingestellte Übertragungsmodus ist #FTPBINARY.

Proxy:
Dieser Tag wird nur beim Herunterladen von Dateien von einer HTTP-Quelle unterstützt. In diesem Fall können Sie hier einen Server angeben, der als Proxy-Server für die Verbindung fungieren soll.

Fail404:
Dieser Tag legt fest, ob DownloadFile() mit einem Fehler "file not found" fehlschlagen soll, wenn Sie eine URL übergeben, die auf eine nicht vorhandene Datei verweist. Wenn Sie eine nicht vorhandene Datei anfordern, generiert HTTP-Server normalerweise eine spezielle HTML-Seite mit einem Fehler "404 - Datei nicht gefunden" und sendet diese an Sie. Sie erhalten also immer eine Datei, selbst wenn Sie eine nicht vorhandene Datei anfordern. Wenn Sie dieses Verhalten nicht möchten, setzen Sie diesen Tag auf True. In diesem Fall wird DownloadFile() fehlschlagen, wenn eine ungültige Datei angefordert wird und Sie erhalten keine 404-Fehlerseite. Standardmäßig ist dieser Tag auf False gesetzt, was bedeutet, dass eine Fehlerseite generiert wird. Dieser Tag wird nur für das Herunterladen von Dateien von einer HTTP-Quelle unterstützt.

SilentFail:
Wenn Sie diesen Tag auf True setzen, wird DownloadFile() niemals einen Fehler auslösen, sondern einfach still eine Fehlermeldung im ersten Rückgabewert data$ und -1 im zweiten Rückgabewert count zurückgeben, um anzuzeigen, dass ein Fehler aufgetreten ist. Wenn dieser Tag auf False gesetzt ist, lädt DownloadFile() einen Systemfehler für alle auftretenden Fehler. Standardwert ist False.

Redirect:
Gibt an, ob der Webserver Sie zu einer neuen URL umleiten darf. Diese Vorgabe ist True, was bedeutet, dass die Umleitung erlaubt ist. Dieser Tag wird nur beim Herunterladen von Dateien von einer HTTP-Quelle unterstützt.

Post:
Dieser Tag wird nur unterstützt, wenn mit einem HTTP-Server gearbeitet wird. Wenn dieser Tag angegeben wird, sendet DownloadFile() eine POST-Anforderung an den HTTP-Server anstelle einer GET-Anforderung. Eine POST-Anforderung hat den Vorteil, dass Sie zusätzliche Daten an Ihre Anforderung anhängen können. So wird es häufig für die Übermittlung der Inhalte von Web-Formularen oder für das Hochladen von Dateien über HTTP verwendet. Die Daten, die an die POST-Anforderung angehängt werden sollen, müssen in diesem Tag als Zeichenkette angegeben werden. Sie können den Datentyp mit dem Tag PostType einstellen (siehe unten).

PostType:
Dieser Tag wird nur behandelt, wenn der Tag Post ebenfalls angegeben wurde. Wenn dies der Fall ist, gibt PostType den Datentyp innerhalb des Tags Post an. Der Typ muss als MIME-Inhaltstyp übergeben werden. Dieser Tag ist standardmäßig auf "application/x-www-form-urlencoded" gesetzt. Dies ist der MIME-Typ, der für die Übermittlung des Inhalts von Webformularen an Perl (CGI)-Skripten verwendet wird.

UserAgent:
Mit diesem Tag können Sie den User Agent ändern, den DownloadFile() an den Zielserver sendet. Dies ist nützlich bei Servern, die die Zusammenarbeit mit unbekannten Benutzern verweigern. Standardmäßig sendet DownloadFile() "Hollywood" in das User-Agent-Feld von HTTP-Anfragen. Dieser Tag wird nur für das Herunterladen von Dateien einer HTTP-Quelle unterstützt. (V5.2)

CustomHeaders:
Mit diesem Tag können Sie eine Reihe von benutzerdefinierten Headern angeben, die bei der Anforderung an den HTTP-Server gesendet werden sollen. Dies kann für einige Feinabstimmungen für gewisse Server nützlich sein. Beachten Sie, dass die einzelnen Header-Elemente durch einen Wagenrücklauf und einen Zeilenvorschub terminiert werden müssen. Dieser Tag wird nur unterstützt, wenn das HTTP-Protokoll verwendet wird. (V6.0)

Encoded:
Setzen Sie diesen Tag auf True, wenn die URL, die Sie an diesen Befehl übergeben haben, bereits korrekt mit ESC-Zeichen versehen wurde. Wenn dieser Tag auf True gesetzt ist, wird DownloadFile() keine ESC-codierten Zeichen formatieren. Stattdessen wird erwartet, dass Sie eine URL übergeben, die bereits korrekt mit ESC-Zeichen versehen wurde, somit sie direkt für Serveranforderungen ohne zusätzliche ESC-Zeichenumwandlungen verwendet werden kann. (V6.1)

Protocol:
Mit diesem Tag kann das Internetprotokoll angegeben werden, das beim Öffnen der Verbindung verwendet werden soll. Dies kann eine der folgenden speziellen Konstanten sein:

#IPV4:
Verwendet die Internetprotokollversion 4 (IPv4).

#IPV6:
Verwendet die Internetprotokollversion 6 (IPv6). Beachten Sie, dass #IPV6 auf AmigaOS und kompatiblen Systemen derzeit nicht unterstützt wird.

#IPAUTO:
Lassen Sie das Host-Betriebssystem das zu verwendende Internetprotokoll bestimmen.

Dieser Tag verwendet standardmäßig den Standardprotokolltyp, der mit SetNetworkProtocol() festgelegt wird. Standardmäßig ist dies aus historischen Gründen und aus Gründen der Portabilität #IPV4. Siehe SetNetworkProtocol für Details. (V8.0)

Adapter:
Mit diesem Tag können Sie einen oder mehrere Netzwerkadapter angeben, die zum Herstellen der angegebenen Verbindung benutzt werden sollten. Dies muss auf eine Zeichenkette gesetzt werden, die den Namen eines oder mehrerer Adapter enthält. Standardmäßig wird der mit SetDefaultAdapter() eingestellte Adapter verwendet. Siehe Lade- und Adaptermodule für Details. (V8.0)

SSL:
Setzen Sie diesen Tag auf True, um eine Verbindung über TLS/SSL-Verschlüsselung anzufordern. Beachten Sie, dass die Einstellung dieses Tags bei Verwendung des integrierten Netzwerkadapters von Hollywood keine Auswirkungen hat, da dieser keine TLS/SSL-Verbindungen unterstützt. Möglicherweise gibt es jedoch einen Netzwerkadapter, der von einem Plugin bereitgestellt wird, das TLS/SSL unterstützt. Wenn Sie diesen Tag auf True setzen, leitet Hollywood Ihren Wunsch nach einer TLS/SSL-Verbindung an den Netzwerkadapter weiter, der vom Plugin bereitgestellt wird. Beachten Sie jedoch, dass Sie diesen Tag normalerweise nicht setzen müssen, wenn das Schema der URL bereits eine SSL-Verbindung mit einem Präfix wie "https://" oder "ftps://" angibt. (V8.0)

Async:
Wenn dies auf True gesetzt ist, arbeitet DownloadFile() 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 DownloadFile() 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)

Verbose:
Dieser Tag kann auf True gesetzt werden, um detaillierte Protokollinformationen über die Verbindung und die Protokollinteraktion mit dem Server anzufordern. Dies wird derzeit nur von Hollywood-Plugins verwendet. Wenn Sie also den internen Netzwerkadapter von Hollywood verwenden, hat das Setzen diesen Tags auf True keine Auswirkung. Plugins können jedoch erweiterte Verbindungsinformationen bereitstellen, wenn dieser Tag auf True gesetzt wurde. Die Voreinstellung ist False. (V9.0)

FileAdapter:
Dieser Tag wird nur verwendet, wenn auch der Tag File gesetzt ist. In diesem Fall können Sie mit FileAdapter einen oder mehrere Dateiadapter angeben, die die angegebene Datei speichern sollen. Wenn Sie diesen Tag verwenden, müssen Sie ihn auf eine Zeichenkette setzen, die den Namen eines oder mehrerer Adapter enthält. Voreingestellt ist default. Siehe Lade- und Adaptermodule für Details. (V10.0)

UserTags:
Dieser Tag kann verwendet werden, um zusätzliche Daten anzugeben, die an Datei- und Netzwerkdapter ü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)

Der optionale Parameter func kann verwendet werden, um eine Callback-Funktion zu übergeben, die von Zeit zu Zeit von DownloadFile() aufgerufen wird, so dass Sie beispielsweise eine Fortschrittsanzeige aktualisieren können. Die Callback-Funktion, die Sie hier angeben, wird mit einem einzigen Tabellenargument aufgerufen. Hier ist eine Übersicht der Tabellenfelder, die initialisiert werden, bevor DownloadFile() Ihre Callback-Funktion ausführt:

Action:
#DOWNLOADFILE_STATUS

Count:
Enthält die Anzahl der Bytes, die bereits heruntergeladen wurden.

Total:
Enthält die Größe der herunterzuladenden Datei.

UserData:
Enthält den Wert, den Sie im Argument userdata übergeben haben.

Die Callback-Funktion vom Typ #DOWNLOADFILE_STATUS sollte normalerweise False zurückgeben. Wenn sie True zurückgibt, wird der Downloadvorgang abgebrochen.

schließlich gibt es ein viertes optionales Argument mit dem Namen userdata. Der Wert, den Sie hier angeben, wird bei jedem Aufruf an Ihre Callback-Funktion übergeben. Dies ist sinnvoll, wenn Sie vermeiden wollen, mit globalen Variablen zu arbeiten. Mit dem Argument userdata können Sie einfach Daten an Ihre Callback-Funktion übergeben. Sie können einen Wert eines beliebigen Typs in userdata verwenden. Zahlen, Zeichenketten, Tabellen und sogar Funktionen können als Benutzerdaten übergeben werden.

Wenn Sie eine Zeichenfolge herunterladen, können Sie den Befehl StringToFile()-Kürzelfunktion verwenden, um die von DownloadFile() zurückgegebene Zeichenkette in eine Datei zu konvertieren. Alternativ können Sie den Befehl DefineVirtualFileFromString() verwenden, um eine virtuelle Datei aus einer Zeichenkettenquelle zu erstellen. Dies kann z.B. nützlich sein, wenn Sie eine Bilddatei herunterladen, die Sie mit dem Befehl LoadBrush() in Hollywood laden möchten. Mit DefineVirtualFileFromString() können Sie diese Datei direkt in Hollywood laden, ohne sie vorher in eine temporären Datei speichern zu müssen.

Wichtiger Hinweis: Stellen Sie sicher, dass Sie die zurückgegebene Zeichenkette data$ auf Nil setzen, wenn Sie sie nicht mehr benötigen. Durch das setzen auf Nil signalisieren Sie dem Speicherbereiniger von Hollywood, dass er den belegten Arbeitsspeicher durch diese Zeichenkette wieder freigeben kann. Dies ist besonders für große Dateien wichtig. Wenn Sie eine große Datei herunterladen, auf der Festplatte speichern und die Zeichenkette nicht auf Nil setzen, werden Sie eine Menge Arbeitsspeicher verschwenden.

Eingaben
url$
URL der Datei, die runtergeladen werden soll
options
optional: eine Tabelle mit weiteren Optionen für das Runterladen
func
optional: eine Callback-Funktion, die von Zeit zu Zeit aufgerufen wird
userdata
optional: Benutzerdaten, welche an die Callback-Funktion übergeben werden
Rückgabewerte
data$
die Daten, welche aus dem Netzwerkpuffer gelesen wurden, oder eine leere Zeichenfolge, wenn der Tag File in der Optionstabelle angegeben wurde
count
Anzahl der erfolgreich übertragenen Bytes
Beispiel
DownloadFile("http://www.airsoftsoftwair.de/images/products/" ..
             "hollywood/47_shot1.jpg", {File = "47_shot1.jpg"})
Der obige Code lädt die angegebene Datei herunter und speichert sie als "47_shot1.jpg" in das aktuelle Verzeichnis.


DownloadFile("http://www.<your server>.com/cgi-bin/formmailer.cgi",
             {Post = "sender=Hollywood&mail=me@hollywood-mal.de" ..
             "&message=Hello from Hollywood!"}))
Der obige Code zeigt an, dass ein CGI-Skript mit DownloadFile() aufgerufen wird. Die im Tag Post angegebenen Daten werden mit der POST-Methode an den HTTP-Server übergeben.


DownloadFile("https://www.hollywood-mal.com/index.html", {
             File = "index.html",
             CustomHeaders = "Accept-Encoding: gzip, deflate\r\n"})
Der obige Code lädt die angegebene Datei herunter und sendet einen benutzerdefinierten Header, um dem Server mitzuteilen, dass er die Datei auch als gzip oder flate komprimierte Datei senden kann.


@REQUIRE "hurl"
...
DownloadFile("https://www.hollywood-mal.com/index.html", {
             File = "index.html", Adapter = "hurl"})
Der obige Code lädt eine Datei mit dem HTTPS-Protokoll herunter. Da Hollywood SSL/TLS standardmäßig nicht unterstützt, verwendet dieser Code das hURL-Plugin für den Vorgang, da hURL SSL/TLS bereitstellt. hURL wird durch Übergabe von hurl im Tag Adapter aktiviert.

Navigation zeigen