Murl::IUrlRequest Interface Referenceabstract

The url request interface. More...

#include "murl_i_url_request.h"

Inherited by Murl::Platform::Android::UrlRequest, Murl::Platform::Emscripten::UrlRequest, Murl::Platform::Foundation::UrlRequest, and Murl::Platform::Win32::UrlRequest.

Public Member Functions

virtual Bool SetHeaders (const Map< String, String > &headers)=0
 Define custom HTTP headers for the request. More...
 
virtual Bool ClearHeaders ()=0
 Clear any custom HTTP headers for the request. More...
 
virtual Bool SendGet (const String &url, Double timeout=60)=0
 Send a URL request with http method GET. More...
 
virtual Bool SendPost (const String &url, const Data &body, const String &contentType, Double timeout=60)=0
 Send a URL request with http method POST. More...
 
virtual Bool Cancel ()=0
 Cancel a URL request. More...
 
virtual const Map< String, String > & GetHeaders () const =0
 Get the custom HTTP headers defined for this request. More...
 
virtual const StringGetUrlString () const =0
 Get the URL request string. More...
 
virtual SInt32 GetResponseStatusCode () const =0
 Get the URL request's response status code. More...
 
virtual const DataGetResponseData () const =0
 Get the URL request's response data. More...
 
virtual const Map< String, String > & GetResponseHeaders () const =0
 Get the HTTP headers received with this URL request's response. More...
 
virtual System::Time GetResponseTimestamp () const =0
 Get the URL request's response received timestamp. More...
 
virtual UInt64 GetCurrentDataSize () const =0
 Get the current response data size. More...
 
virtual Bool ReleaseData ()=0
 Release the response data. More...
 
virtual Bool IsIdle () const =0
 Check if the URL request is idle, i.e. More...
 
virtual Bool IsPending () const =0
 Check if the URL request is pending, i.e. More...
 
virtual Bool IsCancelling () const =0
 Check if the URL request waiting to be cancelled. More...
 
virtual Bool WasFinished () const =0
 Check if the URL request was finished in the most recent tick. More...
 
virtual Bool WasRejected () const =0
 Check if the URL request was rejected in the most recent tick. More...
 
virtual Bool WasCancelled () const =0
 Check if the URL request was cancelled in the most recent tick. More...
 

Detailed Description

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.

Member Function Documentation

◆ SetHeaders()

virtual Bool Murl::IUrlRequest::SetHeaders ( const Map< String, String > &  headers)
pure virtual

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().

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

◆ ClearHeaders()

virtual Bool Murl::IUrlRequest::ClearHeaders ( )
pure virtual

Clear any custom HTTP headers for the request.

Returns
true if successful.

◆ SendGet()

virtual Bool Murl::IUrlRequest::SendGet ( const String url,
Double  timeout = 60 
)
pure virtual

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().

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

◆ SendPost()

virtual Bool Murl::IUrlRequest::SendPost ( const String url,
const Data body,
const String contentType,
Double  timeout = 60 
)
pure virtual

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.

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
true if successful.

◆ Cancel()

virtual Bool Murl::IUrlRequest::Cancel ( )
pure virtual

Cancel a URL request.

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

Returns
true if successful.

◆ GetHeaders()

virtual const Map<String, String>& Murl::IUrlRequest::GetHeaders ( ) const
pure virtual

Get the custom HTTP headers defined for this request.

Returns
The map of header key/value pairs.

◆ GetUrlString()

virtual const String& Murl::IUrlRequest::GetUrlString ( ) const
pure virtual

Get the URL request string.

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

◆ GetResponseStatusCode()

virtual SInt32 Murl::IUrlRequest::GetResponseStatusCode ( ) const
pure virtual

Get the URL request's response status code.

The status code is available if WasFinished() returns true.

Returns
The response status code.

◆ GetResponseData()

virtual const Data& Murl::IUrlRequest::GetResponseData ( ) const
pure virtual

Get the URL request's response data.

The data is available if WasFinished() returns true.

Returns
The URL request response data.

◆ GetResponseHeaders()

virtual const Map<String, String>& Murl::IUrlRequest::GetResponseHeaders ( ) const
pure virtual

Get the HTTP headers received with this URL request's response.

The headers are available if WasFinished() returns true.

Returns
The map of header key/value pairs.

◆ GetResponseTimestamp()

virtual System::Time Murl::IUrlRequest::GetResponseTimestamp ( ) const
pure virtual

Get the URL request's response received timestamp.

The response timestamp is available if WasFinished() or WasRejected() returns true.

Returns
The URL request response timestamp.

◆ GetCurrentDataSize()

virtual UInt64 Murl::IUrlRequest::GetCurrentDataSize ( ) const
pure virtual

Get the current response data size.

The size is updated while receiving data asynchronous.

Returns
The current response data byte size.

◆ ReleaseData()

virtual Bool Murl::IUrlRequest::ReleaseData ( )
pure virtual

Release the response data.

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

Returns
true if successful.

◆ IsIdle()

virtual Bool Murl::IUrlRequest::IsIdle ( ) const
pure virtual

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.

Returns
true if idle.

◆ IsPending()

virtual Bool Murl::IUrlRequest::IsPending ( ) const
pure virtual

Check if the URL request is pending, i.e.

waiting for a response.

Returns
true if pending.

◆ IsCancelling()

virtual Bool Murl::IUrlRequest::IsCancelling ( ) const
pure virtual

Check if the URL request waiting to be cancelled.

Returns
true if cancelling.

◆ WasFinished()

virtual Bool Murl::IUrlRequest::WasFinished ( ) const
pure virtual

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

Returns
true if finished.

◆ WasRejected()

virtual Bool Murl::IUrlRequest::WasRejected ( ) const
pure virtual

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

Returns
true if rejected.

◆ WasCancelled()

virtual Bool Murl::IUrlRequest::WasCancelled ( ) const
pure virtual

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

Returns
true if cancelled.

The documentation for this interface was generated from the following file:
  • murl_i_url_request.h


Copyright © 2011-2022 Spraylight GmbH.