Parasol Framework Manual

Provides a complete working implementation of HTTP.

The HTTP class provides a way of interacting with servers that support the HTTP protocol. Supported HTTP methods include GET, POST, PUT, DELETE, COPY, MOVE, MKCOL and more. The following features are included:

Handling of errors and HTTP status codes.
Monitoring of the server communication process.
Data transfer monitoring.
Sending and receiving in chunks of data.
Background processing of all HTTP instructions.
Data streaming.
User authentication, either automated or with user login dialogs.

For information on command execution and a technical overview of HTTP processing, please refer to the Activate() action.

Sending Content

There are a variety of ways to send content to a server when using methods such as PUT and POST. Content can be sent from objects by setting the InputObject field. To send content from files, set the InputFile field. To send string content, use an InputFile location that starts with string: followed by the text to send.

Receiving Content

There are three possible methods for content download. This first example downloads content to a temporary file for further processing:

http = obj.new('http', {
   src        = 'http://www.parasol.ws/index.html',
   method     = 'get',
   outputFile = 'temp:index.html',
   stateChanged = function(HTTP, State)
      if (State == HGS::COMPLETED) then print(content) end
   end
})

http.acActivate()

This example uses data feeds to push the downloaded data to another object in text format:

doc = obj.new('scintilla')
http = obj.new('http', {
   src        = 'http://www.parasol.ws/index.html',
   method     = 'get',
   dataFeed   = 'text'
   objectMode = 'datafeed'
   outputObject = doc
})
http.acActivate()

Note that the target object needs to support the datatype that you specify, or it will ignore the incoming data. The default datatype is RAW (binary format), but the most commonly supported datatype is TEXT.

The third method is to use function callbacks. Refer to the Incoming field for further information on receiving data through callbacks.

Progress Monitoring

Progress of a data transfer can be monitored through the Index field. If the callback features are not being used for a data transfer, consider using a timer to read from the Index periodically.

SSL Support (HTTPS)

Secure sockets are supported and can be enabled by setting the Port to 443 prior to connection, or by using https:// in URI strings. Methods of communication remain unchanged when using SSL, as encrypted communication is handled transparently.

Structure

The HTTP class consists of the following fields:

Access

Name

Type

Comment

BufferSize INT Indicates the preferred buffer size for data operations.

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.

ClientData APTR This unused field value can be used for storing private data.

ConnectTimeout DOUBLE The initial connection timeout value, measured in seconds.

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.

ContentLength BIGINT The byte length of incoming or outgoing content.

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.

ContentType STRING Defines the content-type for PUT and POST methods.

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.

CurrentState HGS Indicates the current state of an HTTP object during its interaction with an HTTP server.

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.

Name	Description
HGS::AUTHENTICATED	Following successful authentication, this state value will be set.
HGS::AUTHENTICATING	If authentication is requested from the server, the HTTP object will enter this state.
HGS::COMPLETED	This state indicates that the HTTP request was completed in a normal manner.
HGS::READING_CONTENT	The client will remain in this state when the server is sending data to the client.
HGS::READING_HEADER	The default state - this value will be indicated when no data is being written to the server and the client is waiting for a complete header from the server.
HGS::SENDING_CONTENT	During the uploading of data to the server (e.g. `POST`), the HTTP object will remain in this state.
HGS::SEND_COMPLETE	On successful completion of the send phase, the state changes to `SEND_COMPLETE`. Successful completion requires either that the number of bytes indicated in ContentLength have been sent, or `ERR::Terminate` has been returned by the callback functions.
HGS::TERMINATED	If an HTTP command fails to complete normally - for instance if the connection is broken before completion - then the state is set to `TERMINATED`.

DataTimeout DOUBLE The data timeout value, relevant when receiving or sending data.

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.

Datatype DATA The default datatype format to use when passing data to a target object.

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.

Name	Description

Error ERR The error code received for the most recently executed HTTP command.

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 failure - for instance, an ERR::TimeOut error may be received on termination of streamed content. For genuine HTML error codes, see the Status field.

Flags HTF Optional flags.

Name	Description
HTF::DEBUG_SOCKET	Log all HTTP headers and data that goes out through the socket. This should only be used when sending plain-text data.
HTF::LOG_ALL	Print extra log messages during HTTP processing.
HTF::MESSAGE	When activating child objects, send delayed messages to postpone execution rather than making direct calls.
HTF::MOVED	Read-only. Indicates that the HTTP source was moved (`HTS::MOVED_PERMANENTLY`).
HTF::NO_DIALOG	Turn off the username/password dialog.
HTF::NO_HEAD	Do not send a `HEAD` prior to executing a `PUT` or `POST` (removes the authentication check).
HTF::RAW	Forcibly turns off chunk detection and chunk handling on incoming data. Also turns off automatic chunk encoding for outgoing data.
HTF::RECV_BUFFER	Enables buffering of all received HTTP content into a local buffer. The buffer information can be read at any time during and after the transaction through the RecvBuffer field. Note that this option should only be used for limited data transfers to avoid excessive memory usage.
HTF::REDIRECTED	Read-only. Indicates that the HTTP request was redirected (`HTS::TEMP_REDIRECT`).
HTF::RESUME	Enables resuming when downloading content. Only applies when a file is being targeted and the file already exists.
HTF::SSL	Force SSL connectivity, irrespective of the HTTP port. Note that this flag is automatically set (and remains set for all future transfers) if the Port field is set to `443`.

Host STRING The targeted HTTP server is specified here, either by name or IP address.

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

Incoming FUNCTION A callback routine can be defined here for incoming data.

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, LONG Length).

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

Index BIGINT Indicates download progress in terms of bytes received.

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.

InputFile STRING To upload HTTP content from a file, set a file path here.

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.

InputObject OBJECTID Allows data to be sent from an object on execution of a POST command.

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.

Location STRING A valid HTTP URI must be specified here.

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.

Method HTM The HTTP instruction to execute is defined here (defaults to GET).

Name	Description
HTM::BCOPY	WebDAV instruction.
HTM::BDELETE	WebDAV instruction.
HTM::BMOVE	WebDAV instruction.
HTM::BPROPFIND	WebDAV instruction.
HTM::BPROPPATCH	WebDAV instruction.
HTM::COPY	WebDAV instruction.
HTM::DELETE	Deletes a file from the HTTP server, location indicated by the Path field.
HTM::GET	Retrieves files from the HTTP server. The Path field will indicate which file to retrieve.
HTM::HEAD	A HEAD request is equivalent to a `GET` without the content.
HTM::LOCK	WebDAV instruction.
HTM::MKCOL	WebDAV instruction.
HTM::MOVE	WebDAV instruction.
HTM::NOTIFY	WebDAV instruction.
HTM::OPTIONS	Request permitted communication options for a given URL or server.
HTM::POLL	WebDAV instruction.
HTM::POST	Sends information to the HTTP server.
HTM::PROPFIND	WebDAV instruction.
HTM::PROPPATCH	WebDAV instruction.
HTM::PUT	Uploads a file to the HTTP server. The data will be read from the InputFile or InputObject references.
HTM::SEARCH	WebDAV instruction.
HTM::SUBSCRIBE	WebDAV instruction.
HTM::TRACE	Perform a message loop-back test along the path to the target resource.
HTM::UNLOCK	WebDAV instruction.
HTM::UNSUBSCRIBE	WebDAV instruction.

ObjectMode HOM The access mode used when passing data to a targeted object.

This field is relevant when the OutputObject field has been set for receiving incoming data. The method of communication used against the target object can be defined through the ObjectMode. 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.

Name	Description
HOM::DATA_FEED	Use the DataFeed() action to send data to the targeted object.
HOM::READ_WRITE	Use the Write() action to send data to the targeted object.

Outgoing FUNCTION Outgoing data can be managed using a function callback if this field is set.

Outgoing data can be managed manually by providing the HTTP object with an outgoing callback routine. The C prototype for the callback routine is ERR Function(*HTTP, APTR Buffer, LONG BufferSize, LONG *Result). For Fluid use function(HTTP, Buffer, BufferSize).

Outgoing content is placed in the Buffer address and must not exceed the indicated BufferSize. The total number of bytes placed in the Buffer must be indicated in the Result parameter before the callback routine returns.

If an error code of ERR::Terminate is returned 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.

OutputFile STRING To download HTTP content to a file, set a file path here.

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.

OutputObject OBJECTID Incoming data can be sent to the object referenced in this 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.

Password STRING The password to use when authenticating access to the server.

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.

Path STRING The HTTP path targeted at the host server.

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.

Port INT The HTTP port to use when targeting a server.

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.

ProxyPort INT The port to use when communicating with the proxy server.

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.

ProxyServer STRING The targeted HTTP server is specified here, either by name or IP address.

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.

Realm STRING Identifies the realm during HTTP authentication.

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

RecvBuffer BYTE [] Refers to a data buffer that is used to store all incoming content.

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.

Size BIGINT Set this field to define the length of a data transfer when issuing a POST command.

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.

StateChanged FUNCTION A callback routine can be defined here for monitoring changes to the HTTP state.

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.

Status HTS Indicates the HTTP status code returned on completion of an HTTP request.

Name	Description
HTS::ACCEPTED
HTS::BAD_GATEWAY
HTS::BAD_REQUEST
HTS::CONFLICT
HTS::CONTINUE
HTS::CREATED
HTS::ENTITY_TOO_LARGE
HTS::EXPECTATION_FAILED
HTS::FORBIDDEN
HTS::FOUND
HTS::GATEWAY_TIMEOUT
HTS::GONE
HTS::LENGTH_REQUIRED
HTS::METHOD_NOT_ALLOWED
HTS::MOVED_PERMANENTLY
HTS::MULTIPLE_CHOICES
HTS::NOT_ACCEPTABLE
HTS::NOT_FOUND
HTS::NOT_IMPLEMENTED
HTS::NOT_MODIFIED
HTS::NO_CONTENT
HTS::OKAY
HTS::OUT_OF_RANGE
HTS::PARTIAL_CONTENT
HTS::PAYMENT_REQUIRED
HTS::PRECONDITION_FAILED
HTS::PROXY_AUTHENTICATION
HTS::REQUEST_TIMEOUT
HTS::RESET_CONTENT
HTS::SEE_OTHER
HTS::SERVER_ERROR
HTS::SERVICE_UNAVAILABLE
HTS::SWITCH_PROTOCOLS
HTS::TEMP_REDIRECT
HTS::UNAUTHORISED
HTS::UNSUPPORTED_MEDIA
HTS::UNVERIFIED_CONTENT
HTS::URI_TOO_LONG
HTS::USE_PROXY
HTS::VERSION_UNSUPPORTED

UserAgent STRING Specifies the name of the user-agent string that is sent in HTTP requests.

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

Username STRING The username to use when authenticating access to the server.

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.

Actions

The following actions are currently supported:

Activate Executes an HTTP method.

ERR acActivate(*Object)

This action starts an HTTP operation against a target server. Based on the desired Method, an HTTP request will be sent to the target server and the action will immediately return whilst the HTTP object will wait for a response from the server. If the server fails to respond within the time period indicated by the ConnectTimeout, the HTTP object will be deactivated (for further details, refer to the Deactivate() action).

Successful interpretation of the HTTP request at the server will result in a response being received, followed by file data (if applicable). The HTTP response code will be stored in the Status field. The HTTP object will automatically parse the response data and store the received values in the HTTP object as variable fields. It is possible to be alerted to the complete receipt of a response by listening to the CurrentState field, or waiting for the Deactivate action to kick in.

Following a response, incoming data can be managed in a number of ways. It may be streamed to an object referenced by the OutputObject field through data feeds. It can be written to the target object if the ObjectMode is set to READ_WRITE. Finally it can be received through C style callbacks if the Incoming field is set.

On completion of an HTTP request, the Deactivate() action is called, regardless of the level of success.

Error Codes

Okay	The HTTP get operation was successfully started.
Failed	The HTTP get operation failed immediately for an unspecified reason.
File	Failed to create a target file if the File field was set.
Write	Failed to write data to the HTTP NetSocket.
CreateObject	Failed to create a NetSocket object.
HostNotFound	DNS resolution of the domain name in the URI failed.

Deactivate Cancels the current download. Can also signal the end to a download if subscribed.

ERR acDeactivate(*Object)

Following the completion of an HTTP request, the Deactivate() action will be called internally to signal an end to the process. By listening to the Deactivate action(), you are given the opportunity to respond to the end of an HTTP request.

If child objects are initialised to the HTTP object, they will be activated automatically. This feature is provided to assist scripted usage of the HTTP object.

Active HTTP requests can be manually cancelled by calling the Deactivate() action at any time.

GetKey Entries in the HTTP response header can be read as key-values.

ERR acGetKey(*Object, CSTRING Key, STRING Value, LONG Size)

Parameter	Description
Key	The name of a key value.
Value	Pointer to a buffer space large enough to hold the retrieved value.
Size	Indicates the byte size of the Buffer.

SetKey Options to pass in the HTTP method header can be set as key-values.

ERR acSetKey(*Object, CSTRING Key, CSTRING Value)

Parameter	Description
Key	The name of the target key.
Value	The string value to associate with Key.

Write Writes data to objects that provide storage or output services.

ERR acWrite(*Object, APTR Buffer, LONG Length, LONG Result)

Parameter	Description
Buffer	A buffer containing the data that will be written to the object.
Length	The total number of bytes to write to the object.
Result	This parameter with be updated with the total number of bytes written from the Buffer.

HTTP Class

Sending Content

Receiving Content

Progress Monitoring

SSL Support (HTTPS)

Structure

Actions

HGS Type

HOM Type

HTF Type

HTM Type

HTS Type