Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
android
desktop
ios
web
CMakeLists.txt
README.md
shot.png

README.md

Table of contents

Overview

This example is part of OpenSceneGraph cross-platform examples.

In this example we implement HTTP client (with TLS support) working across platforms to perform GET/POST requests.

Note: this example requires 02.TextureImage example knowledge.

Architecture

Each platform has its own stack of technologies to perform HTTP(s) requests:

Such a variaty of platform specific technologies is best addressed by implementing host-guest relationship:

  • guest (platform agnostic)
    • provides networking representation
    • used by cross-platform C++ code
  • host (specific platform)
    • polls guest for pending requests
    • processes them
    • reports results back to the guest

Steps

3.1. Implement guest side classes

Guest side contains the following classes:

  • HTTPClient
    • provides get(...) function to perform HTTP(s) GET request
    • provides post(...) function to perform HTTP(s) POST request
    • creates new HTTPRequest instance for each request
  • HTTPRequest
    • contains URL
    • contains payload
      • if payload is empty, hosts perform GET request
      • if payload is non-empty, hosts perform POST request
    • contains success and failure callbacks

Cross-platform client code uses HTTPClient exclusively to perform HTTP(s) requests.

3.2. Implement HTTPClientProcessor for desktop and web hosts

Both desktop and web use HTTPClientProcessor:

  • processes single HTTPClient instance
  • is regularly called by Application to process requests
  • creates either HTTPRequestProcessorMongoose, or HTTPRequestProcessorFetch instance for each HTTPRequest instance

3.3. Implement HTTPRequestProcessorMongoose for desktop host

We prefer Mongoose to other options because it's easy to use and integrate.

HTTPRequestProcessorMongoose:

  • uses Mongoose
  • manages single HTTPRequest instance

To support requests to HTTPS, make sure to:

Note: clone Mongoose alongside OpenSceneGraph cross-platfrom examples' repository.

3.4. Implement HTTPRequestProcessorFetch for web host

Fetch API is the recommended way for Emscripten web applications to issue XMLHttpRequests to perform HTTP(s) requests.

HTTPRequestProcessorFetch:

  • uses Fetch API
  • manages single HTTPRequest instance

Note: HTTP(s) requests in web browsers are subject to Cross-origin resource sharing (CORS), which means you can't access just any location as free as on desktop or mobile.

3.5. Implement HTTP support for Android

Android uses Java, so we need to implement HTTP processing at both Java (host) and C++ (guest) sides.

Java side

Introduce the following classes to Java:

Note: make sure to add Internet permission to AndroidManifest.xml for HTTP(s) requests to work.

C++ side

Introduce the following native library functions at C++ side:

  • httpClientExecuteNextRequest
    • gets next pending request from HTTPClient
    • sets the request's status to IN_PROGRESS
    • decomposes HTTPRequest into strings
    • returns these strings to Java side
  • httpClientCompleteRequest
    • composes HTTPRequest from strings
    • sets its status to COMPLETED

3.6. Implement HTTP support for iOS

iOS uses Objective-C, so we need to implement HTTP processing at both Objective-C (host) and C++ (guest) sides.

Introduce HTTPClientProcessor to Objective-C:

Introduce the following functions to C++:

  • httpClientExecuteNextRequest
    • gets next pending request from HTTPClient
    • sets the request's status to IN_PROGRESS
    • decomposes HTTPRequest details
    • returns decomposed details to Objective-C side
  • httpClientCompleteRequest
    • composes HTTPRequest from details
    • sets its status to COMPLETED

Note: all HTTP(s) requests in iOS are subject to Application Transport Security (ATS), which means you can access HTTPS freely, however, domains without TLS must be explicitely whitelisted in Info.plist.

3.7. Change background (camera) color when GET/POST responses arrive

With hosts managing HTTPClient instance we can finally request some HTTP(s)!

Let's perform GET and POST requests:

  • if request succeeds, make green component of background (camera) color 50% lighter
  • if request fails, make red component of background (camera) color 50% lighter

Thus:

  • if both requests succeed, we should see light green background
  • if both requests fail, we should see light red background
  • if one request fails and another one suceeds, we should see some other color

Here's how to do it (source code):

// Reset background color.
this->app->camera()->setClearColor({ 0, 0, 0, 0 });
// Set background color 50% greener on success.
auto success = [&](std::string response) {
    auto color = this->app->camera()->getClearColor();
    color.y() += 0.5;
    this->app->camera()->setClearColor(color);
    MAIN_EXAMPLE_LOG(response.c_str());
};
// Set background color 50% redder on failure.
auto failure = [&](std::string reason) {
    auto color = this->app->camera()->getClearColor();
    color.x() += 0.5;
    this->app->camera()->setClearColor(color);
    MAIN_EXAMPLE_LOG(reason.c_str());
};

// GET.
this->app->httpClient->get(
    "https://raw.githubusercontent.com/OGStudio/openscenegraph-cross-platform-examples/master/.gitignore",
    success,
    failure
);

// POST.
this->app->httpClient->post(
    "https://opengamestudio-debug-broker.herokuapp.com",
    "sample-data",
    success,
    failure
);

Note: we use specific HTTPS URLs to make sure both CORS and ATS restrictions are met.

Result

Screenshot

Here's a web build of the example.

You can’t perform that action at this time.