~~Title: HTTPRequest~~
<pageheader/>

The **HTTPRequest** object lets you easily send an asynchronous HTTP request to a remote webserver and receive and process the response.

This object is created via the [[.dialog|Dialog]] object's `NewHTTPReq` method, and so requires a [[:scripting:script_dialogs|Script Dialog]] in order to use. The dialog also must be [[:scripting:script_dialogs:the_dialog_message_loop:detached_dialogs|detached]].

The general process to use this object is as follows:
  - Create the HTTPRequest object
  - Add any required headers
  - Add POST data or GET query name/value pairs as required
  - Send the request
  - Process "http" events in your message loop
  - Read any returned data when you get a "data" event.

<commandtable columns="3" id="cmdtable_1">
$$ Property Name
$$ Return Type
$$ Description
$$ contenttype
$$ //string//
$$ When a response has been received, returns the value of the Content-Type response header.
$$ complete
$$ //bool//
$$ Returns True when a request is complete (and all data has been received).
$$ errorcode
$$ //int//
$$ Returns the numerical error code, if any.
$$ errortext
$$ //string//
$$ Returns the error message, if any.
$$ id
$$ //int//
$$ Returns the ID of the request. This is assigned automatically when the request is created. You'll need this if you use more than one request at once.
$$ response
$$ //string//
$$ Returns the HTTP response message.
$$ responsecode
$$ //int//
$$ Returns the HTTP response code (e.g. 200, 404).
$$ status
$$ //string//
$$ Returns the current status of the request. This is also provided via the **[[.msg|Msg]].value** property when you retrieve an HTTP message in your message loop. Valid status values are: notready, ready, pending, data, complete, error, shutdown.

A status value of "data" means the response has been received and data is available to read. A status of "complete" means the response is complete (e.g. a HEAD request won't return any data, so you'd look for "complete" in that case).
</commandtable>

<commandtable columns="4" id="cmdtable_2">
$$ Method Name
$$ **Arguments**
$$ Return Type
$$ Description
$$ Abort
$$ //none//
$$ //none//
$$ Aborts the request if it hasn't yet returned any data, and removes any headers and post data that you've added.

Calling this method resets the `HTTPRequest` object to its initial state, meaning it can be reused to send another request.
$$ AddHeader
$$ <string:name>\\
<string:value>\\
//or//\\
<**Map**:headers>
$$ //none//
$$ Adds one or more headers to the HTTP request. You can either provide two strings (a name and a value), or a [[.map|Map]] of name -> value pairs to add more than one header at once.
$$ AddPostData
$$ <string:name>\\
<value>\\
[<string:contenttype>]\\
[<string:filename>]\\
[<string::encoding>]
//or//\\
<**Map**:data>
$$ //none//
$$ Adds one or more name/value pairs to the request's POST data. You can either provide the name and value as two arguments, in which case you can also optionally provide a content type string. Alternatively, you can provide a [[.map|Map]] of name -> value pairs. The //value// of a posted data element can either be a string, or a [[.blob|Blob]] object to provide binary data.

If you only add a single item of POST data you can leave the name empty (pass an empty string). This lets you, for example, POST data formatted as JSON - set the //name// to an empty string, the //value// to the JSON data in string form, and //contenttype// to `application/json`.

If adding a **Blob** you can provide the //filename// argument which gives the receiving system a suggested filename to store the file under. You can also specify the //encoding// type - set to "base64" to have the **Blob** sent as base64-encoded data (otherwise by default it will be sent as binary). If you've encoded the data yourself you can specify another encoding type which will be passed as the value of the //Content-Transfer-Encoding// header.

The data will be sent as `multipart/form-data` if you either pass a **Blob** object, or the **Map** contains more than one name/value pair.
$$ AddQueryData
$$ <string:name>\\
<string:value>\\
//or//\\
<**Map**:data>
$$ //none//
$$ Adds one or more name/value pairs to the request's QUERY data. You can either provide the name and value as two arguments, or you can provide a [[.map|Map]] of name -> value pairs. The query data will be automatically url-encoded and appended to the request string when the request is sent.
$$ GetResponseHeaders
$$ //none//
$$ **Map**
$$ Returns a [[.map|Map]] of name -> value pairs containing the response headers once the response data has been received.
$$ ReadResponse
$$ //none//
$$ //string// or\\
**Image** or\\
**Blob**
$$ Once a response has been received (i.e. your message loop gets an "http" message with the value type set to "data"), you can call this function to read the returned data. Note that this function will block until all data is received.

The function tries to interpret the returned data automatically based on the Content-Type header in the response. Text data wil be converted to a string if possible. Image data will be returned as [[.image|Image]] object if it's a format that Opus recognises. Otherwise, a [[.blob|Blob]] containing the response data will be returned.
$$ ReadResponseData
$$ [<int:size>]
$$ **Blob**
$$ Use this function instead of `ReadResponse` to read the raw data from the response without trying to interpret it. The data is returned as a [[.blob|Blob]] object.

You can specify the maximum about of data to read in bytes. If the requested size is available it will be returned; otherwise the function will return immediately with as much data as possible. If you specify //size// as 0, or don't specify a size, then the function will block until the entire response has been received. If you specify //size// as -1 then the function will return as much data as possible, but won't block.
$$ SendRequest
$$ <string:url>\\
[<string:action>]
$$ //none//
$$ Sends the HTTP request to the specified webserver. The //url// parameter should be the full URL to retrieve (e.g. `https://www.gpsoft.com.au`). If you've added any query parameters via the `AddQueryData` method these will be appended automatically.

By default HTTP action will be chosen automatically based on the state of the object - `POST` if `AddPostData` has been used, otherwise `GET`. You can override this with the optional //action// parameter if you like - e.g. specify `HEAD` to just retrieve the headers without any response data.
$$ SetTimeout
$$ <int:seconds>
$$ //none//
$$ Specifies a timeout in seconds (default is 30). Functions which block like `ReadResponse` will timeout if a complete response is not received in time. Set to 0 for no timeout.
$$ SetUserAgent
$$ <string:agent>
$$ //none//
$$ Specifies the User-Agent string of the request, if requires.
$$ Shutdown
$$ //none//
$$ //none//
$$ Call this to close down the request and free any associated resources. This aborts the request if it's still outstanding. Once you've called this function you can't query the request for any other data except the `complete` property.

You don't need to call this function but if you use a lot of requests you may want to once they're completed in order to free up memory.

Once `Shutdown` has been called the request object can no longer be used. Note that messages from the request may still be in your dialog's message queue even after calling `Shutdown` - best practice is to check the `complete` property before using any other methods or properties.
</commandtable>