APTR handle = OpenConnection(STRPTR address, int port, struct hwTagList
                                 *tags);

The address and port parameters will contain the address and port number of the server to connect to. Note that address could be an IP address in IPv4 or IPv6 notation or a host name.

Starting with Hollywood 9.0, OpenConnection() can also be used to implement complete protocol handling. This makes it possible to add support for new protocols to Hollywood's DownloadFile() and UploadFile() functions. By default, those functions only support HTTP and FTP. If you want OpenConnection() to completely take over protocol handling, you have to ignore what is passed in address and port because it contains no protocol information but just the address and port of a remote machine. Instead, you have to examine the URL that is passed in the new HWOPENCONNTAG_URL tag. Hollywood will pass a full URL, i.e. including the protocol identifier, in that tag. If the URL contains a protocol you would like to handle, you'll have to set the HWOPENCONNTAG_CUSTOMPROTOCOL tag to True then. See below for details.

Additionally, Hollywood might pass a tag list containing further parameters to OpenConnection(). The following tags can currently be set:

HWOPENCONNTAG_SSL:

Hollywood functions like DownloadFile() or OpenConnection() support a tag named SSL that can be set to indicate that the connection should be established using SSL. If this tag is set to True, the iData member of HWOPENCONNTAG_SSL will also be set to True. How your plugin interprets this tag, is up to you.

HWOPENCONNTAG_TIMEOUT:

If this tag is part of the tag list, the iData member will tell your implementation of OpenConnection() to maximum amount of time that should be used to try to connect to the server. This timeout value will be specified in milliseconds.

HWOPENCONNTAG_URL:

The pData member of this tag will be set to a string that contains the full URL the user has passed to DownloadFile() or UploadFile(). This tag is important if your OpenConnection() implementation wants to take over protocol handling completely. In that case, you can ignore what is passed in the address and port arguments and just use the URL specified here. Note that you have to set HWOPENCONNTAG_CUSTOMPROTOCOL to True to signal to Hollywood that you want to take over all protocol handling (see below) (V9.0).

HWOPENCONNTAG_CUSTOMPROTOCOL:

The pData member of this tag will be set to a pointer to an int. You have to write True to this int pointer to indicate that your plugin wants to do all protocol handling on its own. In that case, Hollywood won't perform any protocol I/O with your connection but it will just expect your ReceiveData() function to provide the data to be downloaded, or, in case HWOPENCONNTAG_UPLOAD has been set to True, it will just send the data that should be uploaded by calling SendData(). Note that if you set this tag to True, your GetConnectionInfo() function should be prepared to return some statistical information about the connection, like the total number of bytes to be transferred. See GetConnectionInfo for details. (V9.0)

HWOPENCONNTAG_UPLOAD:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, this tag contains a boolean value that indicates whether data should be uploaded or downloaded. Note that even if this is set to True, Hollywood might still call your ReceiveData() function as well because protocols like HTTP often return HTML pages after finishing the upload. (V9.0)

HWOPENCONNTAG_UPLOADSIZE:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, the pData member of this tag will be set to a pointer to a DOSINT64 containing the size in bytes of the data to be uploaded. (V9.0)

HWOPENCONNTAG_USERNAME:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, the pData member of this tag will point to a string containing the user name to be used for protocol authentification. (V9.0)

HWOPENCONNTAG_PASSWORD:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, the pData member of this tag will point to a string containing the password to be used for protocol authentification. (V9.0)

HWOPENCONNTAG_FOLLOWLOCATION:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, this tag will be set to True if redirections to a new address should be allowed or False if they should be forbidden. Redirections to new addresses are often requested by HTTP servers. (V9.0)

HWOPENCONNTAG_TEXTMODE:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, this tag will be set to True if the transfers should be done in text (ASCII) mode. FTP servers typically distinguish between text and binary transfer modes. (V9.0)

HWOPENCONNTAG_MULTIPART:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, the pData member of this tag may be set to a struct hwMultiPartInfo pointer containing a list of multiple parts to be uploaded to a HTTP server by using the POST method.

The struct hwMultiPartInfo looks like this:

struct hwMultiPartInfo { struct hwMultiPartInfo *Succ; STRPTR Name; STRPTR MIMEType; STRPTR DestFile; STRPTR Data; APTR FileHandle; DOSINT64 Length; };

Here is a description of the individual structure members:

Succ:

Pointer to the next item in the list.

Name:

Name of the part object. This will always be specified.

MIMEType:

MIME type of the part object. This may be NULL.

DestFile:

If the part is a file that should be uploaded to the server, this member will be set to the filename that should be used when storing the file on the server. Note that this will only contain the filename, not any path components. If this is NULL, then the part object shouldn't be uploaded as a file.

Data:

This may be set to a pointer containing the data to be uploaded. Either this member or FileHandle will always be set. If Data is set, FileHandle will be NULL and vice versa. The size of the data to be uploaded will be specified in the Length member. If DestFile is non-NULL, the data must be uploaded as a file, otherwise it must be uploaded as form data.

FileHandle:

This may be set to a pointer to file handle that contains the data to be uploaded. You can use DOS functions like hw_FRead() to read data from this file. Note that if this member is set, the part object must always be stored as a file on the server. DestFile will contain the name to use for that. The Length member will contain the file size. If FileHandle is set, Data will always be NULL and vice versa.

Length:

This will be set to the length in bytes of the data to be uploaded for this part object. The data to be uploaded will be specified either via the Data or the FileHandle members (see above).

Note that HWOPENCONNTAG_UPLOADSIZE won't contain a valid size when using multi-part uploads.

There is also the HWOPENCONNTAG_POST tag which Hollywood can also use to specify data to be uploaded to a HTTP server (see below). HWOPENCONNTAG_POST and HWOPENCONNTAG_MULTIPART are mutually exclusive. (V9.0)

HWOPENCONNTAG_PROXY:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, this tag, if it is set, will contain the address of a server to use as a proxy server for the connection. The proxy's name will be passed as a string in the pData tag member. (V9.0)

HWOPENCONNTAG_USERAGENT:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, this tag, if it is set, will contain the name to pass in the user agent header of HTTP requests. The name will be passed as a string in the pData tag member. (V9.0)

HWOPENCONNTAG_CUSTOMHEADERS:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, this tag, if it is set, will contain a list of custom headers to pass to the HTTP server. The individual headers will be passed as a string in the pData tag member and they will be separated by \r\n characters (carriage return and line feed). (V9.0)

HWOPENCONNTAG_VERBOSE:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, this tag will be set to True if the user has requested verbose mode by setting the Verbose tag in DownloadFile() or UploadFile() to True. In verbose mode, your plugin may choose to log some information about the connection to Hollywood's output device. (V9.0)

HWOPENCONNTAG_POST:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, if the tag is specified, the pData member of this tag will contain data to be posted to a HTTP server. Note that this isn't limited to text but can also contain binary data. The size of the data to be posted will be specified in the HWOPENCONNTAG_POSTSIZE tag and the type will be specified in the HWOPENCONNTAG_POSTTYPE tag. This tag is an alternative to the HWOPENCONNTAG_MULTIPART tag which is used for multi-part messages. HWOPENCONNTAG_POST and HWOPENCONNTAG_MULTIPART are mutually exclusive. (V9.0)

HWOPENCONNTAG_POSTSIZE:

If HWOPENCONNTAG_POST has been set, this will contain the size in bytes of the data to be uploaded. Hollywood will set the pData member of this tag to a pointer to a DOSINT64 that contains the size in bytes of the data to be uploaded. (V9.0)

HWOPENCONNTAG_POSTTYPE:

If HWOPENCONNTAG_POST has been set, the pData member of this tag will contain a string describing the MIME type of the data to be uploaded. (V9.0)

HWOPENCONNTAG_FAILONERROR:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, this tag will be set to True if the connection should fail in case the remote file doesn't exist. For example, when requesting a non-existing file from a HTTP server, the server will still return data (a 404 error page) instead of failing. If Hollywood wants your plugin to fail in such cases and not return a 404 error page, it will set HWOPENCONNTAG_FAILONERROR to True. (V9.1)

HWOPENCONNTAG_ENCODED:

You only need to handle this tag if your plugin wants to take over protocol handling. In that case, this tag will be set to True if the URL passed in HWOPENCONNTAG_URL is already escaped. If this tag is set to False or if it isn't present at all, the URL passed in HWOPENCONNTAG_URL is unescaped and might need escaping before it can be parsed. (V9.1)

HWOPENCONNTAG_USERTAGS:

If this is set, pData will point to a struct hwUserTagList containing a list of user tags passed by the Hollywood script. User tags are a way of passing additional information from Hollywood scripts to plugin functions. See User tags for details. (V10.0)

address

address to connect to (see notes above)

port

port number to use

tags

a tag list or NULL

handle

handle to refer to this connection later or NULL if your plugin doesn't want to handle this connection