Lumberyard
User Guide (Version 1.16)

HttpRequestor Gem

You can use the HttpRequestor gem to make asynchronous HTTP/HTTPS requests and return data through a user-provided call back function. This gem uses the EBus for communication and provides all requests asynchronously. For more information, see Working with the Event Bus (EBus) System.

Note

This feature is supported only on Windows and replaces CryAction::HttpRequest.

Getting Started

To use the HttpRequestor gem, you must enable it in your project.

To enable the HttpRequestor gem

  1. In the Project Configurator, select your project, and then click Enable Gems.

  2. In the list of gems, select the check box next to HttpRequestor.

  3. Click Save.

  4. Enter the following command to build your project.

    lmbr_waf configure

C++ API Using EBUS_EVENT

The HttpRequestor gem has separate sets of APIs for adding requests and adding text requests.

AddRequest, AddRequestWithHeaders, AddRequestWithHeadersAndBody

You can use the AddRequest, AddRequestWithHeaders, and AddRequestWithHeadersAndBody APIs to send generic HTTP requests to any website and receive the returned data in JSON format. The methods return the data received in the callback parameter.

Syntax

EBUS_EVENT(HttpRequestor::HttpRequestorRequestBus,AddRequest, URI, method, callback)
EBUS_EVENT(HttpRequestor::HttpRequestorRequestBus, AddRequestWithHeaders, URI, method, headers, callback)
EBUS_EVENT(HttpRequestor::HttpRequestorRequestBus, AddRequestWithHeadersAndBody, URI, method, headers, body, callback)

Each add request method requires the URI, a method and a callback.

Parameters

Parameter Type Description
URI AZStd::String The fully qualified web address, in the following format: scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
method Aws::Http::HttpMethod The method type. The following values are supported: HTTP_GET, HTTP_POST, HTTP_DELETE, HTTP_PUT, HTTP_HEAD, and HTTP_PATCH.
callback This function is called when the HTTP request is completed. The response body and code are present in the callback.
headers HttpRequestor::Headers The list of header fields for the HTTP request.
body AZStd::String Optional body to send with the request.

Return: No return value.

JSON Request Callback

This callback is returned for the AddRequest, AddRequestWithHeaders, and AddRequestWithHeadersAndBody methods.

void Callback(const Aws::Utils::Json::JsonValue& json, Aws::Http::HttpResponseCode responseCode);

Parameters

Parameter Type Description
json Aws::Utils::Json::JsonValue The JSON object. The life span of this object is valid only during the scope of the callback.
responseCode Aws::Http::HttpResponseCode The HTTP response code.

Return: No return value.

AddTextRequest, AddTextRequestWithHeaders, AddTextRequestWithHeadersAndBody

You can use the AddTextRequest, AddTextRequestWithHeaders, and AddTextRequestWithHeadersAndBody APIs to send a generic HTTP request to any website and receive the returned data in a text string. The methods return the data received in the callback parameter.

Syntax

EBUS_EVENT(HttpRequestor::HttpRequestorRequestBus, AddTextRequest, URI, method, callback)
EBUS_EVENT(HttpRequestor::HttpRequestorRequestBus, AddTextRequestWithHeaders, URI, method, headers, callback)
EBUS_EVENT(HttpRequestor::HttpRequestorRequestBus, AddTextRequestWithHeadersAndBody, URI, method, headers, body, callback)

Each add text request method requires the URI, a method and a callback.

Parameters

Parameter Type Description
URI AZStd::String The fully qualified web address, in the following format: scheme:[//[user:password@]host[:port]][/]path[?query][#fragment]
method Aws::Http::HttpMethod The method type. The following values are supported: HTTP_GET, HTTP_POST, HTTP_DELETE, HTTP_PUT, HTTP_HEAD, and HTTP_PATCH.
callback This function is called when the HTTP request is completed. The response body and code are present in the callback.
headers HttpRequestor::Headers The list of header fields for the HTTP request.
body AZStd::String Optional body to send with the request.

Return: No return value.

Text Request Callback

This callback is returned for the AddTextRequest, AddTextRequestWithHeaders, AddTextRequestWithHeadersAndBody methods.

void Callback(const AZStd::string& response, Aws::Http::HttpResponseCode responseCode);

Parameters

Parameter Type Description
response AZStd::string& The text returned from the server. The life span of this object is valid only during the scope of the callback.
responseCode Aws::Http::HttpResponseCode The HTTP response code.

Return: No return value.

Example

The following example uses the Metastream C++ API to obtain a gateway IP address.

EBUS_EVENT(HttpRequestor::HttpRequestorRequestBus, AddRequest, "https://httpbin.org/ip", Aws::Http::HttpMethod::HTTP_GET, [this](AXStd::string && data, Aws::Http::HttpResponseCode code) { AZStd::string resultData = std::move(data); resultCode = code; /* Upon success: ** resultCode = Aws::Http::HttpResponceCode::Ok ** resultData = "{"origin": "xxx.xxx.xxx.xxx"}" /* Your IP will be displayed */ */ }));