WURFL InFuze C++ API Wrapper: User Guide

Introduction

The WURFL InFuze C++ Wrapper is a single HPP header file encapsulating the WURFL InFuze C API in C++ classes. This provides a handy and intuitive OOP interface for WURFL InFuze.

Supported Platforms

The C++ Wrapper is supported on the same platforms as the WURFL InFuze C API, providing a (C++98 or above) C++ compiler. Among these, there are multiple Linux distros such as Ubuntu, CentOS, RedHat, Fedora, and FreeBSD. Other supported operating systems include Windows and Mac OS X.

Installation

Being a header-only package, no explicit installation is needed. You just need to add:

#include <wurfl/wurfl.hpp>

to begin using the InFuze C++ Wrapper in your code. The wrapper relies on a proper installation of WURFL InFuze.

WURFL Data Snapshot

To perform lookups, you will need a copy of your WURFL data snapshot (also referred to as the wurfl.xml). While there is one included in the release package, it is intended to be a sample and will not contain all of your licensed capabilities. Your licensed WURFL data snapshot can be accessed by following these directions. It's strongly recommended, as first thing, to download the latest version of your WURFL data snapshot as shown in the example below.

Basic Usage

Here is a quick code sample you can run to get started with the C++ Wrapper:

#include <wurfl/wurfl.hpp>
#include <iostream>

int main(int argc, char **argv){
  // Download WURFL data file
  // substitute https://data.scientiamobile.com/xxxxxxx/wurfl.zip with your data URL from the ScientiaMobile Vault
  // the second parameter is the destination folder where the zip file will be extracted. It must be writable by the process.
  wurfl::Manager::wurflDownload("https://data.scientiamobile.com/xxxxxxx/wurfl.zip", ".");

  // declare a Builder and set a data file as root
  wurfl::Builder builder;
  builder.setRoot("./wurfl.zip");

  // let the Builder build a Manager
  wurfl::Manager manager(builder.build());

  // use the Manager to obtain a Device by looking up a User Agent string
  wurfl::Device device = manager.lookup("Mozilla/5.0 (Linux; Android 5.0; SAMSUNG SM-G925 Build/LRX21V) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/4.0 Chrome/44.0.2403.133 Mobile Safari/537.36");

  // retrieve Device ID
  std::cout << "device: " << device.id() << std::endl;

  // retrieve a static and virtual capability
  std::cout << "brand_name: " << device.staticCapability("brand_name") << std::endl;
  std::cout << "form_factor: " << device.virtualCapability("form_factor") << std::endl; // NOTE: virtual capabilities are calculated at runtime!
}

There is no need to call the XXX_destroy() method. Destruction of the Builder, Manager, and Device objects are handled automatically by the C++ destructor mechanism when the instances go out of scope.

As you will see, the Manager object wraps wurfl_XXX() InFuze C API calls, while the Device wraps the wurfl_device_XXX() InFuze C API calls. The Builder is a utility class introduced in the C++ layer which wraps an engine configuration and creation. All required calls are conveniently issued in order in the Build::build() method, after you have configured your engine with all the desired Builder::setXXX() calls.

More on Lookup

Looking up a single user agent string is a basic use case. More realistic scenarios call for look-ups using a user-defined HTTP headers retrieval callback function - similar to the WURFL C API wurfl_lookup() call:

const char *lookup_callback(const char *header_name, const void *headers_data)
{
    ...
    your code that receives header data in the "headers_data" parameter,
    receives the requested header name in the "header_name" parameter
    and returns the value of the requested header
    ...
}

...

// declare a Builder and set a data file as root
wurfl::Builder builder;
builder.setRoot("/tmp/wurfl.zip");

// let the Builder build a Manager
wurfl::Manager manager(builder.build());

// use the Manager to obtain a Device by looking up header values passed with a callback function
wurfl::Device device = manager.lookup(&lookup_callback, your_headers_data)

If you choose to roll out your own user-defined HTTP header retrieval callback, you should perform a case-insensitive comparison on header names, and/or verify if your scenario supplies header names in a different case, rather than the standard one expected by WURFL.

Return values

While the WURFL C API call typically returns integer error codes (i.e., wurfl_error), the C++ WURFL API Wrapper uses C++ exception mechanisms to report usage failures:

Exception Thrown	Source of the Exception	Reason for the Exception
std::logic_error	private Manager::setXXX() methods called from Builder::build()	Configuration parameters values supplied to Builder setXXX() methods are invalid. On Builder::build() call, Manager creation fails.
std::runtime_error	Manager and Device query methods	the query cannot be satisfied (wrong device id, unexistent cap/vcap, etc)

The underlying WURFL C API error message can be retrieved by calling the what() method of the std::exception being thrown. It is up to the client code to correctly wrap the WURFL creation/query code in adequate try/catch constructs.

The WURFL Updater

Since InFuze 1.8.3.0, a native internal Updater Module is available.

The WURFL Updater will automatically keep your data file up-to-date with ScientiaMobile's data release schedule. It handles all download and reload operations - even in multithreaded, multiprocess scenarios, along with optional logging of operations, network errors, etc.

While the WURFL InFuze engine construction calls are completely hidden in the Builder class, we decided to expose the updater functionalities both in the Builder and in the Manager interfaces. This is because one could want a completely configured and working updater since the Manager creation, or he/she could prefer to configure and/or start the updater later. To create a Manager instance with a pre-configured background updater, you can do something like this:

wurfl::Builder builder;
builder.setRoot("/tmp/wurfl.zip");
builder.setUpdaterDataURL("your_personal_WURFL_Snapshot_URL");
builder.setUpdaterDataFrequency(WURFL_UPDATER_FREQ_DAILY);
builder.setUpdaterLogPath("wurfl_cpp_updater.log");
builder.updaterStart();

wurfl::Manager manager(builder.build());

Or, if you prefer to build a Manager instance without an updater, and eventually configure and start it later:

wurfl::Builder builder;
builder.setRoot(wurflFullDataFile);
wurfl::Manager manager(builder.build());

// ...later:
manager.setUpdaterDataURL("your_personal_WURFL_Snapshot_URL");
manager.setUpdaterDataFrequency(WURFL_UPDATER_FREQ_DAILY);
manager.setUpdaterLogPath("wurfl_cpp_updater.log");
manager.updaterStart();

You can check for detailed updater operations in the log file set with the setUpdaterLogPath() call. Logging is not mandatory but highly recommended, and the best way to troubleshoot network problems and the like.

Please note that the only mandatory call for the updater module to work is setUpdaterDataURL(), where you set your personal WURFL Snapshot URL (located in your license account page). This, in turn, is dependent on a successful setRoot() call:

• The WURFL data file, and the path specified in the setRoot() call, MUST have write/rename access. The old data file will be replaced (i.e, a rename operation will be performed on it) with the updated version upon successful update completion, and the directory where it resides will be used for remote file download, etc.

• ScientiaMobile does not distribute uncompressed XML data files via the updater. This means that if you plan to use this feature, you MUST use a compressed (i.e, a ZIP or a XML.GZ) file as data root in the setRoot() call.

Please note that setUpdaterDataFrequency() sets the frequency of Updater checks for the data file, not how often the engine data file is actually updated.

The WURFL InFuze Updater functionality relies on the presence and features of the curl command-line utility. A check for correct curl installation on the system being used is done in the setUpdaterDataURL() call.

WURFL InFuze C++ API Wrapper Reference

class wurfl::Builder

The Builder class abstracts the configuration and the construction of a WURFL engine.

class wurfl::Manager

The Manager class abstract the runtime usage of a WURFL engine. Amongst its responsibilities, the most important one is to perform lookups on user agent strings, or more generally on request headers, in order to identify the associated devices. Each Manager instance also has a built-in updater instance, by which both synchronous or asynchronous updates of the WURFL data file can be performed.

class wurfl::Device

The Device class abstracts a device retrieved by WURFL via lookup or direct device ID search. It encapsulates the wurfl_device_XXX() C API calls, exposing several methods to query a Device instance for its capabilities and state.