s$, len = UploadFile(url$, options[, func, userdata])

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, e.g. 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 the adapter set using SetDefaultAdapter(). 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)

Async:

If this is set to True, UploadFile() will operate in asynchronous mode. This means that it will return immediately, passing an asynchronous operation handle to you. You can then use this asynchronous operation handle to finish the operation by repeatedly calling ContinueAsyncOperation() until it returns True. This is very useful in case your script needs to do something else while the operation is in progress, e.g. displaying a status animation or something similar. By putting UploadFile() into asynchronous mode, it is easily possible for your script to do something else while the operation is being processed. See ContinueAsyncOperation for details. Defaults to False. (V9.0)

Verbose:

This tag can be set to True to request detailed log information about the connection and the protocol interaction with the server. This is currently only used by Hollywood plugins so if you use Hollywood's internal network adapter, setting this tag to True has no effect. Plugins, however, may choose to provide extended connection information when this tag has been set to True. Defaults to False. (V9.0)

FileAdapter:

This tag is only used if the File tag is set as well. In that case, FileAdapter allows you to specify one or more file adapters that should be asked if they want to open the specified file. If you use this tag, you must set it to a string containing the name(s) of one or more adapter(s). Defaults to default. See Loaders and adapters for details. (V10.0)

UserTags:

This tag can be used to specify additional data that should be passed to file and network adapters. If you use this tag, you must set it to a table of key-value pairs that contain the additional data that should be passed to plugins. See User tags for details. (V10.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.

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

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

UploadFile("ftp://ftp.test.net/pub/image.jpg", {File = "image.jpg"})

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"}}})

@REQUIRE "hurl"
...
UploadFile("ftp://ftp.test.net/pub/image.jpg",
    {File = "image.jpg", SSL = True, Adapter = "hurl"})

@REQUIRE "hurl"
...
UploadFile("ftps://ftp.test.net/pub/image.jpg",
    {File = "image.jpg", Adapter = "hurl"})