data$, count = DownloadFile(url$[, options, func, userdata])
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:
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:
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:
Fail404:
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:
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:
True
, was bedeutet, dass die Umleitung erlaubt ist. Dieser Tag
wird nur beim Herunterladen von Dateien von einer HTTP-Quelle unterstützt.
Post:
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:
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:
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:
Encoded:
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:
#IPV4:
#IPV6:
#IPV6
auf AmigaOS und kompatiblen Systemen derzeit
nicht unterstützt wird.
#IPAUTO:
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:
SSL:
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:
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:
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:
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:
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:
Total:
UserData:
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.
File
in
der Optionstabelle angegeben wurdeDownloadFile("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.