The default buffer size for HTTP data operations is indicated here. It affects the size of the temporary buffer that is used for storing outgoing data (PUT and POST operations).

Note that the actual buffer size may not reflect the exact size that you set here.

The timeout for connect operations is specified here. In the event of a timeout, the HTTP object will be deactivated and the Error field will be updated to a value of ERR::TimeOut.

The timeout value is measured in seconds.

HTTP servers will return a ContentLength value in their response headers when retrieving information. This value is defined here once the response header is processed. The ContentLength may be set to -1 if the content is being streamed from the server.

Note that if posting data to a server with an InputFile or InputObject as the source, the Size field will have priority and override any existing value in ContentLength. In all other cases the ContentLength can be set directly and a setting of -1 can be used for streaming.

The ContentType should be set prior to sending a PUT or POST request. If NULL, the default content type for POST methods will be set to application/x-www-form-urlencoded. For PUT requests the default of application/binary will be applied.

The CurrentState is a readable field that tracks the current state of the client in its relationship with the target HTTP server. The default state is READING_HEADER. Changes to the state can be monitored through the StateChanged field.

On completion of an HTTP request, the state will be changed to either COMPLETED or TERMINATED.

A timeout for send and receive operations is required to prevent prolonged waiting during data transfer operations. This is essential when interacting with servers that stream data with indeterminate content lengths. It should be noted that a timeout does not necessarily indicate failure if the content is being streamed from the server (ContentLength is set to -1).

In the event of a timeout, the HTTP object will be deactivated and the Error field will be updated to a value of ERR::TimeOut.

The timeout value is measured in seconds.

When streaming downloaded content to an object, the default datatype is RAW (binary mode). An alternative is to send the data as TEXT or XML by changing the Datatype field value.

The receiving object can identify the data as HTTP information by checking the class ID of the sender.

On completion of an HTTP request, the most appropriate error code will be stored here. If the request was successful then the value will be zero (ERR::Okay). It should be noted that certain error codes may not necessarily indicate a comms failure - for instance, an ERR::TimeOut error may be received on termination of streamed content; while ERR::NotAuthorised is a credentials issue.

The recommended process for error checking is: 1. Check if the CurrentState is COMPLETED or TERMINATED; 2. Check the Status field for NIL; 3. Check the Error field for the error code.

The HTTP server to target for HTTP requests is defined here. To change the host post-initialisation, set the Location.

Data can be received from an HTTP request by setting a callback routine in the Incoming field. The format for the callback routine is ERR Function(*HTTP, APTR Data, INT Length). For scripts the format is Function(HTTP, Array).

If an error code of ERR::Terminate is returned or raised by the callback routine, the currently executing HTTP request will be cancelled.

If an HTTP GET request is executed, the Index field will reflect the number of bytes that have been received. This field is updated continuously until either the download is complete or cancelled.

The Index value will always start from zero when downloading, even in resume mode.

The Index field can be monitored for changes so that progress during send and receive transmissions can be tracked.

HTTP content can be streamed from a source file when a POST command is executed. To do so, set the InputFile field to the file path that contains the source data. The path is not opened or checked for validity until the POST command is executed by the HTTP object.

An alternative is to set the InputObject for abstracting the data source.

Multiple files can be specified in the InputFile field by separating each file path with a pipe symbol |.

HTTP content can be streamed from a source object when a POST command is executed. To do so, set the InputObject to an object that supports the Read() action. The provided object ID is not checked for validity until the POST command is executed by the HTTP object.

The URI of the HTTP source must be specified here. The string must start with http:// or https://, followed by the host name, HTTP path and port number if required. The values mentioned will be broken down and stored in the Host, Path and Port fields respectively. Note that if the port is not defined in the URI, the Port field is reset to the default (80 for HTTP or 443 for HTTPS).

An alternative to setting the Location is to set the Host, Path and Port separately.

ObjectMode defines the data transfer mode when OutputObject field has been set for receiving incoming data. The default setting is DATA::FEED, which passes data through the data feed system (see also the Datatype to define the type of data being sent to the object). The alternative method is READ_WRITE, which uses the Write action to send data to the targeted object.

Outgoing data can be sent procedurally by setting this field with a callback routine.

In C++ the function prototype is ERR Function(*HTTP, std::vector<uint8_t> &Buffer, APTR Meta). Write content to the Buffer and the final size will determine the amount of data sent to the server. Alternatively use the Write() action, although this will be less efficient.

For scripting languages the function prototype is function(HTTP). Use the Write() action to send data to the server.

If an error code of ERR::Terminate is returned or raised by the callback routine, any remaining data will be sent and the transfer will be treated as having completed successfully. Use ERR::TimeOut if data cannot be returned in a reasonable time frame. All other error codes apart from ERR::Okay indicate failure.

HTTP content can be streamed to a target file during transfer. To do so, set the OutputFile field to the destination file name that will receive data. If the file already exists, it will be overwritten unless the RESUME flag has been set in the Flags field.

HTTP content can be streamed to a target object during incoming data transfers. To do so, set the OutputObject to an object that supports data feeds and/or the Write() action. The type of method used for passing data to the output object is determined by the setting in the ObjectMode field.

The provided object ID is not checked for validity until the POST command is executed by the HTTP object.

A password may be preset if authorisation is required against the HTTP server for access to a particular resource. Note that if authorisation is required and no username and password has been preset, the HTTP object will automatically present a dialog box to the user to request the relevant information.

A 401 status code is returned in the event of an authorisation failure.

The path to target at the host server is specified here. If no path is set, the server root will be targeted. It is not necessary to set the path if one has been specified in the Location.

If spaces are discovered in the path, they will be converted to the %20 HTTP escape code automatically. No other automatic conversions are operated when setting the Path field.

The Port to target at the HTTP server is defined here. The default for HTTP requests is port 80. To change the port number, set the Location.

If the ProxyServer field has been set, the ProxyPort must be set to the port number used by the proxy server for all requests. By default the ProxyPort is set to 8080 which is commonly used for proxy communications.

If a proxy server will receive the HTTP request, set the name or IP address of the server here. To specify the port that the proxy server uses to receive requests, see the ProxyPort field.

During the user authentication process, a realm name may be returned by the HTTP server and this will be reflected here.

If the RECV_BUFFER flag is set, all content received from the HTTP server will be stored in a managed buffer that is referred to by this field. This field can be read at any time. It will be set to NULL if no data has been received. The buffer address and all content is reset whenever the HTTP object is activated.

The buffer is null-terminated if you wish to use it as a string.

Prior to the execution of a POST command it is recommended that you set the Size field to explicitly define the length of the data transfer. If this field is not set, the HTTP object will attempt to determine the byte size of the transfer by reading the size from the source file or object.

Define a callback routine in StateChanged in order to receive notifications of any change to the CurrentState of an HTTP object. The format for the routine is ERR Function(*HTTP, HGS State).

If an error code of ERR::Terminate is returned by the callback routine, the currently executing HTTP request will be cancelled.

The Status value is only valid on completion of an HTTP request. A value of 200 indicates that the request was successful. Other values indicate either redirection or an error condition. For a full list of HTTP status codes, see https://www.w3.org/Protocols/rfc2616/rfc

If the Status value is NIL on completion, the request has failed without a valid response being received from the server. Refer to the Error field for more information.

This field describe the user-agent value that will be sent in HTTP requests. The default value is Parasol Client.

A username can be preset before executing an HTTP method against a secure server zone. The supplied credentials will only be passed to the HTTP server if it asks for authorisation. The username provided should be accompanied by a Password.

In the event that a username or password is not supplied, or if the supplied credentials are invalid, the user will be presented with a dialog box and asked to enter the correct username and password.