s$, len = UploadFile(url$, options[, func, userdata])
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:
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:
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:
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:
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:
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:
Data:
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:
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:
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:
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:
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 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:
#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 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:
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 ö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:
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:
Total:
UserData:
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:
Total:
UserData:
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.
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.