Name
UploadFile -- upload file to FTP or HTTP server (V5.0)
Synopsis
[s$, len =] UploadFile(url$, options[, func, userdata])
Function
This command allows you to conveniently upload a file to an FTP or HTTP server. Before Hollywood 6.0 UploadFile() only supported FTP upload but starting with version 6.0 HTTP upload is supported as well. Since HTTP and FTP upload use two entirely different mechanisms of sending the data to the receiving server, the procedures of uploading a file using FTP and using HTTP are quite different as well.

If you want to upload a file to an FTP server with UploadFile(), you will have to pass the URL where the file should be stored on the FTP server as the first argument. This URL must begin with the ftp:// prefix, and it must contain a fully qualified path specification (that is, including the destination filename). The URL must not contain any escaped characters. Escaping will be done by UploadFile() so make sure that you pass only unescaped URLs. I.e. passing "ftp://ftp.site.net/my%20file.zip" will not work. You must specify an URL without escaped characters, so the correct version would be: "ftp://ftp.site.net/my file.zip". If you want to pass a URL that has already been escaped, you have to set the Encoded tag to True (see below). In that case, UploadFile() won't do any further escaping on your URL.

The file that should be uploaded to the FTP server must be specified in either the File or Data table element (see below).

If you want to upload a file to an HTTP server, you need to pass the URL of a PHP or CGI script which handles the upload. Note that UploadFile() only supports upload using the HTTP POST method. Upload via HTTP PUT is not supported. In addition to the URL of a PHP or CGI script, you also have to specify the parameters that should be passed to this script. These parameters are passed in the FormData table element (see below). The file(s) to be uploaded also have to be passed as parameters in the FormData table element.

You can also specify a username and password that shall be used to log into the HTTP or FTP server. When using FTP upload, "anonymous" is used as the default username and "anonymous@anonymous.org" as the default password. If you want to use a different user account, you have to pass the username/password pair in the URL. Here is an example URL for username "johndoe" and password "topsecret": ftp://johndoe:topsecret@ftp.test.net/pub/files.lha for FTP upload or http://johndoe:topsecret@www.test.com/private/upload.php for HTTP upload.

The URL you pass to this function can also contain a port number. If you want to specify a port number, you have to put it after the host name and separate it using a colon. Here is an example for using port 1234: ftp://ftp.test.net:1234/test/image.jpg. If no port is specified, UploadFile() will use port 21.

The second argument is a table that recognizes several options. When using FTP upload, the data to be uploaded can be specified by using either the File table tag or the Data tag. When using HTTP upload, the data to be uploaded must be specified using the FormData element. Here is an overview of all tags that are currently recognized by the options table:

File:
For FTP uploads, the file you want to upload must be specified in this tag. In case you want to upload data from a string source, you must use the Data tag below. You must use either specify File or Data in every call to UploadFile() for FTP uploads. You must not use this tag for HTTP uploads. Use FormData for HTTP uploads (see below).

Data:
For FTP uploads, this tag allows you to specify a string that will be uploaded to the location specified in argument one. The string is not limited to text only, but it can also contain binary data. If you want to upload data from a file source, you must use the File tag instead (see above). You must specify either Data or File in every call to UploadFile() for FTP uploads. You must not use this tag for HTTP uploads. Use FormData for HTTP uploads (see below).

TransferMode:
This tag can be used to specify whether UploadFile() should transfer the file in ASCII or in binary mode. For ASCII mode, specify #FTPASCII here. For binary mode, use #FTPBINARY. The default transfer mode is #FTPBINARY. This tag is only supported for FTP uploads.

SilentFail:
If you set this tag to True, UploadFile() will never throw an error but simply exit silently and return an error message in the first return value, and -1 in the second return value to indicate that an error has happened. If it is set to False, UploadFile() will throw a system error for all errors that occur. Defaults to False.

FormData:
This tag is needed for HTTP uploads. It allows you to specify a table of parameters that should be passed to the PHP or CGI script which handles the upload. The file or data to be uploaded has to be passed in this table as well. You have to pass a table of tables to this argument. Every subtable describes a single script parameter. UploadFile() will use this table of tables to compose multipart form data request that is then sent to the HTTP server using the POST request type. The following table elements can be used in each subtable:

Name:
This must be set to the name of the parameter. This table element must always be provided.

Data:
The data that should be passed as the parameter's value. This must be set to a string. The string can also contain binary data so it is possible to pass the file data to be uploaded in this table element. Alternatively, you can also use the File table element to upload data from a file source. Note that you have to specify either the Data or the File tag for each subtable. If you want to use Data to upload file instead of form data, you also have to specify the MIMEType and FileAlias tags (see below).

File:
If you don't set the Data tag, you need to set this table element to a filename whose contents should be uploaded as part of the parameter passed in Name. Alternatively, you can also use the Data table element to upload data from a string source. Note that you have to specify either the File or the Data tag for each subtable.

MIMEType:
This tag allows you to set the MIME type of the data to be uploaded. This should be specified whenever the parameter subtable intends to upload a file. It must not be specified in case the parameter subtable merely passes simple form data (i.e. plain text) to the server. This tag defaults to "application/octet-stream" if the File tag has been set. If the Data tag has been set there is no default for the MIMEType tag since the Data tag could also contain plain form data. Thus, if you want to use the Data tag to upload file data, you always have to explicitly set MIMEType to the data's MIME type.

FileAlias:
If the parameter subtable intends to upload a file, this tag can be used to set a name for this file. This is usually only needed if the file data you want to upload is specified using the Data tag. When using the File tag, UploadFile() will simply use the name of this file and you don't have to use FileAlias at all, though it can be used to override the filename specified in File.

It is perfectly allowed to upload more than one file at once. You can use as many subtables as you need with the FormData table element. The resulting HTML page generated by the PHP or CGI script after the upload will be returned as a string by UploadFile(). (V6.0)

CustomHeaders:
This tag allows you to specify a string of custom headers that should be sent to the HTTP server when making the request. This can be useful for some fine-tuned adjustments for some servers. Keep in mind that the individual header elements have to be terminated by a carriage return and a line feed. This tag is only supported when using the HTTP protocol. (V6.0)

Encoded:
Set this tag to True if the URL you passed to this function has already been correctly escaped. If this tag is set to True, UploadFile() won't escape any characters. Instead, it expects you to pass a URL that has already been correctly escaped so that it can be directly used for server requests without any additional escaping. (V6.1)

Protocol:
This tag can be used to specify the Internet protocol that should be used when opening the connection. This can be one of the following special constants:

#IPV4:
Use Internet Protocol version 4 (IPv4).
#IPV6:
Use Internet Protocol version 6 (IPv6). Note that #IPV6 is currently unsupported on AmigaOS and compatible systems.
#IPAUTO:
Let the host operating system determine the Internet protocol to use.

This tag defaults to the default protocol type set using SetNetworkProtocol(). By default, this is #IPV4 due to historical and portability reasons. See SetNetworkProtocol for details. (V8.0)

Adapter:
This tag allows you to specify one or more network adapters that should be asked to establish the specified connection. This must be set to a string containing the name(s) of one or more adapter(s). Defaults to default. See Loaders and adapters for details. (V8.0)

SSL:
Set this tag to True to request a connection through TLS/SSL encryption. Note that setting this tag when using Hollywood's inbuilt network adapter doesn't have any effect because Hollywood's inbuilt network adapter doesn't support TLS/SSL connections. However, there might be a network adapter provided by a plugin that supports TLS/SSL and if you set this tag to True Hollywood will forward your wish to have a TLS/SSL connection to the network adapter provided by the plugin. Do note, though, that you normally don't have to set this tag in case the URL's scheme already indicates an SSL connection by using a prefix such as "https://" or "ftps://". (V8.0)

The optional parameter func can be used to pass a callback function which will be called from time to time by UploadFile() allowing you to update a progress bar for example. The callback function you specify here will be called with a single argument: A table that contains more information. Here is an overview of the table fields that will be initialized before UploadFile() runs your callback function:

Action:
#UPLOADFILE_STATUS

Count:
Contains the number of bytes that have already been uploaded.

Total:
Contains the size of the file being uploaded.

UserData:
Contains the value you passed in the userdata argument.

The callback function of type #UPLOADFILE_STATUS should normally return False. If it returns True, the upload operation will be aborted.

Note that when using UploadFile() for HTTP uploading, the PHP or CGI script used to handle the upload will also generate a resulting HTML page that is usually shown by the browser after the upload has been completed. This HTML page is returned by UploadFile() as a string. The second return value describes the length of this HTML page in bytes. Since UploadFile() has to download this resulting HTML page from the server, your callback function will be called while UploadFile() is receiving the server's response so that you can monitor progress. The table that is passed to your callback function will be initialized as follows in that case:

Action:
#UPLOADFILE_RESPONSE

Count:
Contains the number of bytes that have already been downloaded.

Total:
Contains the size of the file being downloaded.

UserData:
Contains the value you passed in the userdata argument.

The callback function of type #UPLOADFILE_RESPONSE should normally return False. If it returns True, the download operation will be aborted.

Finally, there is a fourth optional argument called userdata. The value you specify here is passed to your callback function whenever it is called. This is useful if you want to avoid working with global variables. Using the userdata argument you can easily pass data to your callback function. You can specify a value of any type in userdata. Numbers, strings, tables, and even functions can be passed as user data.

Inputs
url$
FTP URL for destination file or URL of a PHP or CGI script on a HTTP server
options
a table containing the file/data to be uploaded as well as further options
func
optional: a callback function that shall be called from time to time
userdata
optional: user defined data that should be passed to callback function
Results
s$
optional: the resulting HTML page generated by the PHP or CGI script; note that this is only passed when using HTTP upload
len
optional: the length of the resulting HTML page generated by the PHP or CGI script; note that this is only passed when using HTTP upload
Example
UploadFile("ftp://ftp.test.net/pub/image.jpg", {File = "image.jpg"})
The code above uploads the file "image.jpg" to the FTP server specified in argument 1.


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"}}})
The code above uploads the file "image.jpg" to a HTTP server. Additionally, it passes the parameters uploadername, uploaderemail, and description to the PHP script.

Show TOC