Murl Engine Lua Addon API  Version 1.0 beta
Murl.IUrlRequest

The url request interface.

The IUrlRequest object can be created by the IWebControl object.

After creation, custom HTTP headers can be set for the URL request by calling SetHeaders() with a given string/string map of key/value pairs that define the actual headers. To unset the currently defined headers, ClearHeaders() can be called. To query the current map of headers defined, call GetHeaders().

To initiate the actual request, either SendGet() or SendPost() must be called (for each of the available HTTP request types GET and POST, respectively), with a given URL string and an optional timeout value in seconds. SendPost() additionally takes two other parameters: A data object containing the POST data to be sent, and a string defining the content type (e.g. "application/x-www-form-urlencoded"). Note that if the "Content-Type" header was previously defined using SetHeaders(), it is overwritten by the value given with SendPost().

After the request was initiated, its current status can be queried in the current logic tick by checking IsPending(), WasFinished() and WasRejected(). Additionally, the current number of received response bytes can be checked via GetCurrentDataSize().

As long as IsPending() returns true, the application should keep running and checking both WasFinished() and WasRejected() for every subsequent logic tick. As soon as one of those two methods returns true, the request is done and appropriate action can be taken.

If WasRejected() returns true, this indicates that the request failed without ever being able to communicate with the server at the given URL, e.g. when the network is down or when trying to connect to an unknown host.

If WasFinished() returns true, this indicates that the system did actually communicate with the given server. To verify that the request was in fact successful, the HTTP response code should be checked by calling GetResponseStatusCode(). The value returned by this method is the actual response code sent from the server; see the website https://tools.ietf.org/html/rfc7231 for a list of standardized codes. Codes in the range from 200 to 299 usually indicate success. If any other code was received, the application should react accordingly.

Any response data that was sent from the server can be queried via GetResponseData(). In case of success, the data usually contains the requested payload. In other cases, e.g. a 404 (not found) error, the data may contain a simple verbatim description, an actually viewable HTML page describing the error, any other data or simply no data at all. If no data was sent, this method returns an empty data object.

The actual set of HTTP response headers can be queried by calling GetResponseHeaders(), which returns a string/string map of header key/value pairs.

When a URL request is finally done (either rejected or finished), it can be reused by simply calling SendGet() or SendPost() again, with optionally setting different headers beforehand.

Finally, when the received response data is not needed anymore, the method ReleaseData() can be called to release the internal data buffer without destroying the actual URL request object, to save memory.


Table members

Methods


SetHeaders(headers)

Define custom HTTP headers for the request. This method can be used to define any number of custom HTTP headers sent with the URL request, given as a map containing string key/value pairs for the header names and values, respectively. Note: When using a POST request, the given headers should not include the "Content-Type" and "Content-Length" headers, as they are automatically added during SendPost().

Boolean SetHeaders(Murl.Map.StringString headers)

Parameters
headersThe map of header key/value pairs.
Returns
Boolean true if successful.

ClearHeaders()

Clear any custom HTTP headers for the request.

Boolean ClearHeaders()

Returns
Boolean true if successful.

SendGet(url, timeout)

Send a URL request with http method GET. When posting a URL request the IsPending() state is true. If the URL request was successful the WasFinished() state is true and the response data can be accessed by GetResponseData().

Boolean SendGet(String url, Number timeout)

Parameters
urlThe url string to send to.
timeoutThe request timeout in seconds.
Returns
Boolean true if successful.

SendPost(url, body, contentType, timeout)

Send a URL request with http method POST. When posting a URL request the IsPending() state is true. If the URL request was successful the WasFinished() state is true and the response data can be accessed by GetResponseData().
If the url is redirected, the POST is cancelled and WasRejected() state is true.

Boolean SendPost(String url, Murl.Data body, String contentType, Number timeout)

Parameters
urlThe url string to send to.
bodyThe body data to send.
contentTypeThe string for the "Content-Type" http header field.
timeoutThe request timeout in seconds.
Returns
Boolean true if successful.

Cancel()

Cancel a URL request. This method cancels a URL request if it is pending, and clears its internal state.

Boolean Cancel()

Returns
Boolean true if successful.

GetHeaders()

Get the custom HTTP headers defined for this request.

Murl.Map.StringString GetHeaders()

Returns
Murl.Map.StringString The map of header key/value pairs.

GetUrlString()

Get the URL request string.

String GetUrlString()

Returns
String The url which was passed to SendGet() or SendPost().

GetResponseStatusCode()

Get the URL request's response status code. The status code is available if WasFinished() returns true.

Integer GetResponseStatusCode()

Returns
Integer The response status code.

GetResponseData()

Get the URL request's response data. The data is available if WasFinished() returns true.

Murl.Data GetResponseData()

Returns
Murl.Data The URL request response data.

GetResponseHeaders()

Get the HTTP headers received with this URL request's response. The headers are available if WasFinished() returns true.

Murl.Map.StringString GetResponseHeaders()

Returns
Murl.Map.StringString The map of header key/value pairs.

GetCurrentDataSize()

Get the current response data size. The size is updated while receiving data asynchronous.

Integer GetCurrentDataSize()

Returns
Integer The current response data byte size.

ReleaseData()

Release the response data. Releasing the data can be performed only if the URL request is not pending.

Boolean ReleaseData()

Returns
Boolean true if successful.

IsIdle()

Check if the URL request is idle, i.e. ready to start a GET or POST operation. The request is idle if it is not waiting for a response and not waiting to be cancelled.

Boolean IsIdle()

Returns
Boolean true if idle.

IsPending()

Check if the URL request is pending, i.e. waiting for a response.

Boolean IsPending()

Returns
Boolean true if pending.

IsCancelling()

Check if the URL request waiting to be cancelled.

Boolean IsCancelling()

Returns
Boolean true if cancelling.

WasFinished()

Check if the URL request was finished in the most recent tick.

Boolean WasFinished()

Returns
Boolean true if finished.

WasRejected()

Check if the URL request was rejected in the most recent tick.

Boolean WasRejected()

Returns
Boolean true if rejected.

WasCancelled()

Check if the URL request was cancelled in the most recent tick.

Boolean WasCancelled()

Returns
Boolean true if cancelled.