Bezeichnung
UploadFile -- lädt die Datei auf einen Server hoch (V5.0)
Übersicht
s$, len = UploadFile(url$, options[, func, userdata])
Beschreibung
Mit diesem Befehl können Sie eine Datei auf einen Netzwerkserver hochladen. Standardmäßig unterstützt UploadFile() die Protokolle FTP und HTTP, aber Plugins können zusätzliche Protokolle nutzen. Vor Hollywood 6.0 unterstützte UploadFile() nur das hochladen auf FTP-Server. Aber ab Version 6.0 wird das hochladen auf HTTP-Server ebenfalls unterstützt. Da das hochladen auf HTTP- und FTP- Server zwei völlig unterschiedliche Mechanismen zum Senden der Daten an den empfangenden Server verwenden, sind die Verfahren zum hochladen einer Datei unter Verwendung von FTP und HTTP ziemlich unterschiedlich.

Wenn Sie eine Datei mit UploadFile() auf einen FTP-Server hochladen möchten, müssen Sie als erstes Argument die URL übergeben, auf der die Datei auf dem FTP-Server gespeichert werden soll. Diese URL muss mit dem Präfix ftp:// beginnen und sie muss eine vollständige Pfadangabe (d.h. den Zieldateinamen) enthalten. Die URL darf keine Escape-Zeichen enthalten. Die ESC-Zeichenumwandlung wird durch UploadFile() durchgeführt werden, so stellen Sie sicher, dass Sie nur unverschlüsselte URLs übergeben. D.h. URL wie z.B. "ftp://ftp.site.net/my%20file.zip" funktionieren nicht. Sie müssen eine URL ohne ESC-Zeichen angeben, womit die korrekte Version wäre: "ftp://ftp.site.net/my file.zip". Wenn Sie eine bereits mit ESC-Zeichen codierte URL übergeben möchten, müssen Sie den Tag Encoded auf True setzen (siehe unten). In diesem Fall wird UploadFile() keine weitere ESC-Zeichenumwandlung auf Ihre URL verwenden.

Die Datei, die auf den FTP-Server hochgeladen werden soll, muss entweder im Tabellenelement File oder Data angegeben werden (siehe unten).

Wenn Sie eine Datei auf einen HTTP-Server hochladen möchten, müssen Sie die URL eines PHP- oder CGI-Skripts übergeben, das das Hochladen abwickelt. Beachten Sie, dass UploadFile() nur das Hochladen mit der HTTP-POST-Methode unterstützt. Das Hochladen Upload über HTTP-PUT wird nicht unterstützt. Zusätzlich zur URL eines PHP- oder CGI-Skripts müssen Sie auch die Parameter angeben, die an dieses Skript übergeben werden sollen. Diese Parameter werden im Tabellenelement FormData übergeben (siehe unten). Die Dateien, die hochgeladen werden sollen, müssen auch als Parameter im Tabellenelement FormData übergeben werden.

Sie können auch einen Benutzernamen und ein Passwort angeben, die für die Anmeldung am HTTP- oder FTP-Server verwendet werden sollen. Bei Verwendung vom FTP-Hochladen wird "anonymous" als Standardbenutzername und "anonymous@anonymous.org" als Standardkennwort verwendet. Wenn Sie ein anderes Benutzerkonto verwenden möchten, müssen Sie das Benutzername-/Passwortpaar in der URL übergeben. Hier ist eine Beispiel-URL für den Nutzernamen "johndoe" und dem Passwort "topsecret": ftp://johndoe:topsecret@ftp.test.net/pub/files.lha für das FTP-Hochladen oder http://johndoe:topsecret@www.test.com/private/upload.php für das HTTP-Hochladen.

Die an diesen Befehl übergebene URL kann auch eine Portnummer enthalten. Wenn Sie eine Portnummer angeben möchten, müssen Sie sie nach dem Hostnamen setzen und mit einem Doppelpunkt trennen. Hier ist ein Beispiel für die Verwendung von Port 1234: ftp://ftp.test.net:1234/test/image.jpg. Wenn kein Port angegeben wird, verwendet UploadFile() Port 21.

Das zweite Argument options ist eine Tabelle, die mehrere Optionen erkennt. Bei der Verwendung vom FTP-Hochladen können die hochzuladenden Daten entweder mit dem Tabellenfeld File oder mit Data angegeben werden. Bei der Verwendung vom HTTP-Hochladen müssen die hochzuladenden Daten mit dem Feld FormData angegeben werden. Hier ist eine Übersicht aller Felder, die derzeit erkannt werden:

File:
Für das FTP-Hochladen muss die Datei in diesem Tag angegeben werden. Wenn Sie Daten aus einer Zeichenkettenquelle hochladen möchten, müssen Sie den Tag Data verwenden. Bei jedem Aufruf von UploadFile() für das FTP-Hochladen müssen Sie entweder File oder Data angeben. Sie dürfen diesen Tag nicht fürs HTTP-Hochladen benutzen. Verwenden Sie dafür FormData (siehe unten).

Data:
Für das FTP-Hochladen können Sie bei diesem Tag eine Zeichenkette angeben, die hochgeladen wird. Die Zeichenkette ist nicht nur auf Text beschränkt, sondern kann auch binäre Daten enthalten. Wenn Sie Daten aus einer Datei hochladen möchten, müssen Sie stattdessen den Tag File verwenden (siehe oben). Sie müssen bei jedem Aufruf von UploadFile() fürs FTP-Hochladen entweder Data oder File angeben. Sie dürfen diesen Tag nicht fürs HTTP-Hochladen benutzen. Verwenden Sie FormData für das HTTP-Hochladen (siehe unten).

TransferMode:
Mit diesem Tag können Sie festlegen, ob UploadFile() die Datei im ASCII- oder im Binärmodus übertragen soll. Für den ASCII-Modus geben Sie hier #FTPASCII an. Verwenden Sie für den Binärmodus #FTPBINARY. Der voreingestellte Übertragungsmodus ist #FTPBINARY. Dieser Tag wird nur beim FTP-Hochladen unterstützt.

SilentFail:
Wenn Sie diesen Tag auf True setzen, wird UploadFile() niemals einen Fehler auslösen, sondern einfach still abbrechen und eine Fehlermeldung im ersten Rückgabewert s$ sowie -1 im zweiten Rückgabewert len zurückgeben, um anzuzeigen, dass ein Fehler aufgetreten ist. Wenn es auf False gesetzt ist, wird UploadFile() einen Systemfehler für alle auftretenden Fehler melden. Standardwert ist False.

FormData:
Dieser Tag wird für das HTTP-Hochladen benötigt. Er erlaubt Ihnen, eine Tabelle von Parametern anzugeben, die an das PHP- oder CGI-Skript weitergegeben werden soll, welches das Hochladen verarbeitet. Die Datei oder die Daten, die hochgeladen werden sollen, müssen ebenfalls in dieser Tabelle übergeben werden. Sie müssen eine Tabelle mit Tabellen an dieses Argument übergeben. Jede Untertabelle beschreibt einen einzelnen Skriptparameter. UploadFile() verwendet diese Tabelle mit Tabellen, um Multipart/Form-Data zu erstellen, die dann an den HTTP-Server über den POST-Anforderungstyp gesendet wird. Folgende Tabellenelemente können in jeder Untertabelle verwendet werden:

Name:
Dies muss auf den Namen des Parameters eingestellt sein. Dieses Tabellenelement muss immer vorhanden sein.

Data:
Die Daten, die als Parameterwert übergeben werden sollen. Diese muss mit einer Zeichenkette geschehen, die auch binäre Daten enthalten kann, so dass es möglich ist, die in diesem Tabellenelement hochzuladenden Dateidaten zu übergeben. Alternativ können Sie auch das Tabellenelement File verwenden, um Daten aus einer Dateiquelle hochzuladen. Beachten Sie, dass Sie für jede Untertabelle den Tag Data oder File angeben müssen. Wenn Sie Data zum Hochladen von Dateien anstelle von Formulardaten verwenden möchten, müssen Sie auch die Tags MIMEType und FileAlias angeben (siehe unten).

File:
Wenn Sie den Tag Data nicht setzen, müssen Sie dieses Tabellenelement auf einen Dateinamen setzen, dessen Inhalt als Teil des übergebenen Parameters in Name hochgeladen werden soll. Alternativ können Sie auch das Tabellenelement Data verwenden, um Daten aus einer Zeichenkettenquelle hochzuladen. Beachten Sie, dass Sie für jede Untertabelle entweder den Tag File oder Data angeben müssen.

MIMEType:
Mit diesem Tag können Sie den MIME-Typ der hochzuladenden Daten einstellen. Dies sollte angegeben werden, wann immer die Parameteruntertabelle eine Datei hochladen möchte. Sie darf nicht angegeben werden, wenn die Parameteruntertabelle lediglich einfache Formulardaten (d. h. Klartext) an den Server übergibt. Dieser Tag wird standardmäßig auf "application/octet-stream" eingestellt, wenn der Tag File gesetzt wurde. Wenn der Tag Data gesetzt wurde, gibt es keine Vorgabe für den Tag MIMEType, da der Tag Data auch einfache Formulardaten enthalten könnte. Wenn Sie also den Tag Data zum Hochladen von Dateidaten verwenden möchten, müssen Sie MIMEType immer explizit auf den MIME-Typ der Daten setzen.

FileAlias:
Wenn die Parameteruntertabelle eine Datei hochladen möchte, kann mit diesem Tag ein Name für diese Datei festgelegt werden. Dies ist in der Regel nur erforderlich, wenn die Dateidaten mit dem Tag Data angegeben werden. Bei Verwendung des Tags File benutzt UploadFile() einfach den Namen dieser Datei und Sie müssen FileAlias nicht verwenden, obwohl es benutzt werden kann, um den in File angegebenen Dateinamen zu überschreiben.

Es ist absolut erlaubt, mehr als eine Datei auf einmal hochzuladen. Sie können beliebig viele Untertabellen mit dem Tabellenelement FormData verwenden. Die resultierende HTML-Seite, die vom PHP- oder CGI-Skript nach dem Upload erzeugt wird, wird als Zeichenkette von UploadFile() zurückgegeben. (V6.0)

CustomHeaders:
Mit diesem Tag können Sie eine Reihe von benutzerdefinierten Headern angeben, die an den HTTP-Server gesendet werden sollen. Dies kann für einige Feinabstimmungen bei einigen Servern 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 UploadFile() keine Zeichen codieren. 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 UploadFile() 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 asynchronen 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 UploadFile() 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 öffnen 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 UploadFile() aufgerufen wird, so dass Sie beispielsweise eine Fortschrittsanzeige aktualisieren können. Die Callback-Funktion, wird mit einem einzigen Argument aufgerufen: Eine Tabelle, die mehr Informationen enthält. Hier ist eine Übersicht der Tabellenfelder, die initialisiert werden, bevor UploadFile() Ihre Callback-Funktion ausführt:

Action:
#UPLOADFILE_STATUS

Count:
Enthält die Anzahl der bereits hochgeladenen Bytes.

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

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

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

Beachten Sie, dass beim Verwenden von UploadFile() für das HTTP-Hochladen das PHP- oder CGI-Skript, das für das Hochladen verwendet wird, auch eine resultierende HTML-Seite generiert, die normalerweise vom Browser nach Abschluss des Hochladens angezeigt wird. Diese HTML-Seite wird von UploadFile() als Zeichenkette s$ zurückgegeben. Der zweite Rückgabewert len beschreibt die Länge dieser HTML-Seite in Bytes. Da UploadFile() diese resultierende HTML-Seite vom Server herunterladen muss, wird Ihre Callback-Funktion aufgerufen, während UploadFile() die Antwort des Servers erhält, damit Sie den Fortschritt überwachen können. Die Tabelle, die an Ihre Callback-Funktion übergeben wird, wird in diesem Fall wie folgt initialisiert:

Action:
#UPLOADFILE_RESPONSE

Count:
Enthält die Anzahl der bereits heruntergeladenen Bytes.

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 #UPLOADFILE_RESPONSE sollte normalerweise False zurückgeben. Wenn es 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 angeben. Zahlen, Zeichenketten, Tabellen und sogar Funktionen können als Benutzerdaten weitergegeben werden.

Eingaben
url$
FTP-URL für die Zieldatei oder URL eines PHP- oder CGI-Skripts auf einem HTTP-Server
options
eine Tabelle mit der zu hochladenden Datei/Daten sowie weitere Optionen
func
optional: eine Callback-Funktion, die von Zeit zu Zeit aufgerufen wird
userdata
optional: Benutzerdaten, welche an die Callback-Funktion übergeben werden
Rückgabewerte
s$
optional: die resultierende HTML-Seite, die durch das PHP- oder CGI-Skript erzeugt wird; Beachten Sie, dass diese nur beim HTTP-Hochladen übergeben wird
len
optional: die Länge der resultierenden HTML-Seite, die durch das PHP- oder CGI-Skript erzeugt wird; Beachten Sie, dass diese nur bei HTTP-Hochladen übergeben wird
Beispiel
UploadFile("ftp://ftp.test.net/pub/image.jpg", {File = "image.jpg"})
Der obige Code lädt die Datei "image.jpg" auf den in Argument 1 angegebenen FTP-Server hoch.


UploadFile("http://www.test.com/upload.php", {FormData = {
    {Name = "uploadername", Data = "John Doe"},
    {Name = "uploaderemail", Data = "john@doe.com"},
    {Name = "description", Data = "My profile picture"},
    {Name = "imagefile", File = "image.jpg", MIMEType = "image/jpeg"}}})
Der obige Code lädt die Datei "image.jpg" auf einen HTTP-Server hoch. Zusätzlich werden die Parameter uploadername, uploaderemail und description an das PHP-Skript weitergegeben.


@REQUIRE "hurl"
...
UploadFile("ftp://ftp.test.net/pub/image.jpg",
    {File = "image.jpg", SSL = True, Adapter = "hurl"})
Der obige Code lädt eine Datei mit explizitem FTPS hoch. Da Hollywood SSL/TLS standardmäßig nicht unterstützt, verwendet dieser Code das hURL-Plugin für den Vorgang, da hURL SSL/TLS unterstützt. hURL wird aktiviert, indem hurl im Tag Adapter übergeben wird.


@REQUIRE "hurl"
...
UploadFile("ftps://ftp.test.net/pub/image.jpg",
    {File = "image.jpg", Adapter = "hurl"})
Der obige Code lädt eine Datei mit implizitem FTPS hoch. Da Hollywood SSL/TLS standardmäßig nicht unterstützt, verwendet dieser Code das hURL-Plugin für den Vorgang, da hURL SSL/TLS unterstützt. hURL wird aktiviert, indem hurl im Tag Adapter übergeben wird.

Navigation zeigen