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:
For information on command execution and a technical overview of HTTP processing, please refer to the Activate() action.
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.
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', datatype = 'text', objectMode = 'DATA_FEED', 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 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.
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.
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 ( Note that the actual buffer size may not reflect the exact size that you set here. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 The timeout value is measured in seconds. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ContentLength | INT64 | The byte length of incoming or outgoing content. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
HTTP servers will return a 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ContentType | STRING | Defines the content-type for PUT and POST methods. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The ContentType should be set prior to sending a | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 On completion of an HTTP request, the state will be changed to either
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 In the event of a timeout, the HTTP object will be deactivated and the Error field will be updated to a value of 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 The receiving object can identify the data as HTTP information by checking the class ID of the sender.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 The recommended process for error checking is: 1. Check if the CurrentState is | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Flags | HTF | Optional flags. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 If an error code of | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Index | INT64 | Indicates the total bytes received during content transfer. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
If an HTTP 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 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 An alternative to setting the Location is to set the Host, Path and Port separately. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Method | HTM | The HTTP instruction to execute (defaults to GET ). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ObjectMode | HOM | The transfer mode used when passing data to a targeted object. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ObjectMode defines the data transfer mode when OutputObject field has been set for receiving incoming data. The default setting is
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Outgoing | FUNCTION | Outgoing data can be sent procedurally using this callback. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Outgoing data can be sent procedurally by setting this field with a callback routine. In C++ the function prototype is For scripting languages the function prototype is If an error code of | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 resource. Note that if authorisation is required and no username and password has been preset, the HTTP object may present a dialog box to the user to request the relevant information. A | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Port | INT | The HTTP port to use when targeting a host. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The Port to target at the HTTP host is defined here and defaults to | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ProxyPort | INT | The port to use when communicating with a proxy server. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
If a ProxyServer has been set, the ProxyPort must define the proxy communication port number. The default value is | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ProxyServer | STRING | Route the HTTP request through the proxy server defined here. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 | INT8 [] | Refers to a data buffer that is used to store all incoming content. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
If the | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Size | INT64 | Set this field to define the length of a data transfer when issuing a POST command. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Prior to the execution of a | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
StateChanged | FUNCTION | This callback reports 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 If an error code of | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Status | HTS | Indicates the HTTP status code returned on completion of an HTTP request. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The Status value is only valid on completion of an HTTP request. A value of If the Status value is
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
UserAgent | STRING | Specifies the name of the user-agent string that is sent in HTTP requests. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
This field describes the | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. |
The following actions are currently supported:
Activate | Sends an HTTP request to the host. | |||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ERR acActivate(*Object) This action sends an HTTP request to the targeted Host. Based on the desired Method, an HTTP request will be sent to the host and the action will return whilst the HTTP object waits for a response from the server. If the host fails to respond within the time period indicated by the ConnectTimeout, the HTTP object will be deactivated and the CurrentState set to Successful parsing of the HTTP request at the host will result in a response being received, followed by content data (if applicable). The HTTP response code will be stored in the Status field. The response will be parsed automatically with the header strings stored as key-values. To receive notice of the parsed response, hook into the StateChanged callback. Incoming HTTP content can be managed in the following 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 On completion of an HTTP request, the Deactivate() action is called, regardless of the level of success. Error Codes
| ||||||||||||||||||||||||
Deactivate | Ends the current HTTP request. | |||||||||||||||||||||||
ERR acDeactivate(*Object) Following the completion of an HTTP request, the Deactivate() action will be called internally to signal an end to the process. Subscribing to Deactivate() is an effective means of responding to the end of a single HTTP request. Active HTTP requests can be manually cancelled by calling Deactivate() at any time. Deactivation does not necessarily result in closure of the socket. | ||||||||||||||||||||||||
GetKey | Entries in the HTTP response header can be read as key-values. | |||||||||||||||||||||||
ERR acGetKey(*Object, CSTRING Key, STRING Value, INT Size)
| ||||||||||||||||||||||||
SetKey | Options for the HTTP header can be set as key-values. | |||||||||||||||||||||||
ERR acSetKey(*Object, CSTRING Key, CSTRING Value)
| ||||||||||||||||||||||||
Write | Writes data to objects that provide storage or output services. | |||||||||||||||||||||||
ERR acWrite(*Object, APTR Buffer, INT Length, INT Result)
|
Options for defining an HTTP object's state.
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 . |
Output mode.
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. |
HTTP 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::DISABLE_SERVER_VERIFY | Disable SSL server certificate verification (use with caution). |
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 . |
The HTTP Method to use when the object is activated.
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. |
HTTP status codes
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 |