infuze c api user guide

WURFL InFuze C API: User Guide

Introduction

The WURFL C Application Programming Interface (API) is a high-performance and low-memory footprint mobile device detection software component written in C++ that can quickly and accurately detect over 500 capabilities of visiting devices. It can differentiate between portable mobile devices, desktop devices, SmartTVs and any other types of devices on which a web browser can be installed. The API library allows applications to perform real-time detection for a variety of uses, such as content adaptation, redirections, and data traffic analysis.

ScientiaMobile's WURFL C Module is also the core component for the Apache, Nginx, and Varnish-Cache Modules, offered by ScientiaMobile as separate products. Those modules allow you to add support for device detection in a variety of contexts, such as retrieving WURFL device data through the Apache Environment, FastCGI Environment, or data objects defined by Nginx and Varnish scripts. Other strategies may include injecting WURFL capabilities into HTTP Headers from your HTTP Proxy. This eliminates the need for application developers to maintain a WURFL library dependency in their code base.

Note: Apache, Nginx and Varnish-Cache are the trademarks of the respective trademark holders.

API Features

  • Standard WURFL API (implements same logic as other standard WURFL APIs by ScientiaMobile)
  • Accurately detect over 500 capabilities
  • High performance & low memory footprint (as compared to other WURFL APIs)
  • Automatic caching previous detections for faster response times
  • Ability to adjust and configure different in-memory caching strategies
  • Support for WURFL 'patch files' (custom device description profiles that enrich WURFL)

Technical Overview

The libwurfl C API is written in C++ language, with a C-language interface on top of it. The installed libwurfl library on the system consists of a header file wurfl.h and a dynamic link library which an application can link to.

When running the WURFL C API library, libwurfl will read and parse the WURFL's Device Definition Repository (DDR) database file from run-time memory. If needed, you can also load wurfl patch files that extend or correct the WURFL repository with your own customizations of the device data.

The libwurfl C library has an in-memory cache technique to preserve the result of previous detections. This achieves a great balance between accuracy of detection and fast response time in virtually all use cases. Finally, the strategies for caching are configurable (more later).

Note: Full documentation for API methods can be found below.

Supported Platforms

The libwurfl API is supported by multiple linux distros such as Ubuntu, CentOS, RedHat, Fedora, and FreeBSD (other distros have similar building procedures). Other supported operating systems include Windows and Mac OS X. The libwurfl API was tested on SmartOS as well (actually 13.2.0 zone, released on September 25, 2013), but due to the very particular environment, you should contact ScientiaMobile for support. Please contact ScientiaMobile to inquire about specific platforms not listed here.

Installing libwurfl on Ubuntu/Debian

Once you have obtained the libwurfl deb package from ScientiaMobile, you can install it with:

sudo apt-get update
sudo dpkg -i libwurfl-1.8.3.0-x86_64.deb

Installing libwurfl on RedHat/Fedora/CentOS/Opensuse

Once you have obtained the libwurfl rpm package from ScientiaMobile, you can install it with:

sudo yum update
sudo rpm -i libwurfl-1.8.3.0-x86_64.rpm

Installing libwurfl on FreeBSD 10

The installation procedure for FreeBSD differs slightly from other Linux-based systems. In particular, you will need to use the pre-compiled files provided by ScientiaMobile. Just extract the tar file under / and everything should be set:

cd /
tar xzvf libwurfl-1.8.3.0-x86_64.tgz

Installing libwurfl on Mac OS X

Download the libwurfl-1.8.3.0-x86_64.pkg file from ScientiaMobile and install it by double clicking on it. Beware that from mac os x 10.11 (El Capitan), rootless mode is enabled by default so you should download the alternative installation package named libwurfl-1.8.3.0-x86_64-rootless.pkg

Installing libwurfl on Windows

Download the libwurfl-1.8.3.0-x64.msi file from ScientiaMobile and install it by double clicking on it.

Obtain the WURFL Repository file

In order for the WURFL C API library to work, you need a WURFL file installed on your system. The libwurfl C API library package comes with a recent evaluation copy of the WURFL file called wurfl.zip. The file is automatically installed to /usr/share/wurfl/ path, or is included with the Windows installer.

Updating the WURFL Repository

Commercial licensees of WURFL are granted access to “The Customer Vault”, a personal virtual space containing purchased software licenses and weekly updated versions of the WURFL repository.

All licensed customers are given access to a direct download URL for obtaining the latest WURFL snapshot. This is either the weekly snapshot (released on Sunday night), or an Out-Of-Band snapshot that ScientiaMobile releases to customers between weekly snapshots in case of a significant improvement to the data (for example, if a high-profile device is released mid-week). The snapshots are licensed to your organization specifically as part of the agreement with ScientiaMobile.

To create a direct download URL, login to ScientiaMobile and click the "My Account" at the top-right corner of the screen. Then, click "Direct Download" to create a URL for your access. This URL is unique to you and must be kept private.

Customer Vault of WURFL snapshot

In addition to the weekly snapshots, the Vault contains a personal URL to the latest update, that can be used to update one's WURFL installation programmatically. Please refer to the following Forum post for details.

Getting Started

Using the InFuze C API is simple : all operations are performaned on a wurfl_handle which is obtained, tipically during init phase by :

  wurfl_handle hWurfl = wurfl_create();

this operation return a wurfl_handle and creates and engine for further operations. WURFL engine is thread safe and the intended design is that multiple threads share the same wurfl_handle.

You can choose between high-accuracy (WURFL_ENGINE_TARGET_HIGH_ACCURACY) or high-performance (WURFL_ENGINE_TARGET_HIGH_PERFORMANCE) targets. In High-Performance mode, desktop web browser detection is done programmatically without referencing the WURFL data. As a result, most desktop web browsers are returned as generic_web_browser WURFL ID for performance. If either High-Performance or High-Accuracy are not defined, High-Performance mode is enabled by default.

You can use the following code to engine target:

  wurfl_set_engine_target(hWurfl, WURFL_ENGINE_TARGET_HIGH_ACCURACY);

The caching strategies are also configurable. You can choose between NULL, LRU, or Double LRU cache mechanisms. The default is Double LRU, which is a two-cache strategy (one going from User-Agent to Device-Id, the other from Device-Id to Internal Device). The default parameters are 30,000, 10,000 (maximum 30,000 elements for the User-Agent to device-id cache and maximum 10,000 elements for the device-id to device cache) and the values are in elements. The LRU cache comes with User-Agent to Device mapping only, and the NULL parameter will disable the cache mode. For more information, please see LRU Cache Mechanism.

You can use the following code to define a different cache provider and engine target:

  wurfl_set_cache_provider(hwurfl, WURFL_CACHE_PROVIDER_DOUBLE_LRU, "100000, 30000");

Note: wurfl_set_cache_provider and wurfl_set_engine_target must be set prior to calling wurfl_load().

Before any device lookup you will need to load the DDR file, named wurfl.zip :

  // Define wurfl db
  error = wurfl_set_root(hwurfl, "/usr/share/wurfl/wurfl.zip");
  if (error != WURFL_OK) {
    printf("%s\n", wurfl_get_error_message(hwurfl));
    return -1;
  }

  // Loads wurfl db into memory
  error = wurfl_load(hwurfl);
  if (error != WURFL_OK) {
    printf("%s\n", wurfl_get_error_message(hwurfl));
    return -1;
  }

After properly loading the WURFL instance, device detection can start. For this example, we will manually inject the User-Agent string of a popular Android device and proceed to detect the device (with some error-handling):

    // Example of an User-Agent
    const char *userAgent = "Mozilla/5.0 (Linux; U; Android 3.2; en-gb; K3108 Build/HTJ85B) AppleWebKit/534.13 (KHTML, like Gecko) Version/4.0 Safari/534.13";

    wurfl_device_handle hdevice = wurfl_lookup_useragent(hwurfl, userAgent);

    if (hdevice) {
        // DEVICE FOUND
        // ...
    }

Once a device is detected, device capabilities can be retrieved as follows:

    if (hdevice) {
        // DEVICE FOUND

        // Print out a capability
        printf(" %s = %s\n", wurfl_device_get_capability(hdevice, "brand_name"));

    }

Virtual Capabilities

Virtual capabilities are an important feature of the WURFL API that obtain values related to the requesting agent out of the HTTP request as a whole (as opposed to limiting itself to capabilities that are found in WURFL).

In order to compute its final returned value, a virtual capability may look at regular (non-virtual) capabilities as well as parameters derived from the HTTP request at run-time. Virtual capabilities are useful to model aspects of the HTTP Client that are not easily captured through the finite number of profiles in WURFL.

  // Print out a virtual capability
  printf(" %s = %s\n", wurfl_device_get_virtual_capability(hdevice, "is_smartphone"));

If your application needs to retrieve all the capabilities, and/or virtual capabilities, you can use an enumerator to iterate through all capabilities that were loaded into the runtime memory and another enumerator to iterate through all the virtual capabilities. Thus, there is no need to provide a list of individual capability names.

    if (hdevice) {
        // DEVICE FOUND
        // Iterate through all capabilities
        wurfl_device_capability_enumerator_handle hdevicecaps = wurfl_device_get_capability_enumerator(hdevice);

        while (wurfl_device_capability_enumerator_is_valid(hdevicecaps)) {
            printf(" %s = %s\n", wurfl_device_capability_enumerator_get_name(hdevicecaps), wurfl_device_capability_enumerator_get_value(hdevicecaps));

            wurfl_device_capability_enumerator_move_next(hdevicecaps);
        }

        wurfl_device_capability_enumerator_destroy(hdevicecaps);

        // Iterate through all virtual capabilities
        hdevicecaps = wurfl_device_get_virtual_capability_enumerator(hdevice);

        while (wurfl_device_capability_enumerator_is_valid(hdevicecaps)) {
            printf(" %s = %s\n", wurfl_device_capability_enumerator_get_name(hdevicecaps), wurfl_device_capability_enumerator_get_value(hdevicecaps));

            wurfl_device_capability_enumerator_move_next(hdevicecaps);
        }

        wurfl_device_capability_enumerator_destroy(hdevicecaps);
    }

To avoid memory leaks, destroying pointer references to the Device Handler is recommended every time the processing of the device detection is over.

    // Destroys the Device Handler
    wurfl_device_destroy(hdevice);

Code Example

This code allows you to create a WURFL Handler instance, define the path to the WURFL repository, and load the database into the memory. For this example, we assume that the wurfl.zip file is located on the same path of the executable program file. However, the path name can be different depending on your requirements.

    #include <wurfl/wurfl.h>

    ...

    int main(int argc, char **argv) {
        wurfl_handle hwurfl;
        wurfl_error error;

        // Create wurfl handler
        hwurfl = wurfl_create();

        // Define wurfl db
        error = wurfl_set_root(hwurfl, "wurfl.zip");
        if (error != WURFL_OK) {
            printf("%s\n", wurfl_get_error_message(hwurfl));
            return -1;
        }

        // Loads wurfl db into memory
        error = wurfl_load(hwurfl);
        if (error != WURFL_OK) {
            printf("%s\n", wurfl_get_error_message(hwurfl));
            return -1;
        }

    const char *userAgent = "Mozilla/5.0 (Linux; U; Android 3.2; en-gb; K3108 Build/HTJ85B) AppleWebKit/534.13 (KHTML, like Gecko) Version/4.0 Safari/534.13";

    wurfl_device_handle hdevice = wurfl_lookup_useragent(hwurfl, userAgent);

    // Print out a capability
    printf(" %s = %s\n", wurfl_device_get_capability(hdevice, "brand_name"));


    ...

Tip: You can also use wurfl_add_patch function to add one or more custom patch files to the WURFL repository.

Filtering Capabilities

By default WURFL will fetch the complete set of capabilities for all device detection. By selecting only the capabilities you need before engine load, you will achieve better load times and a smaller memory footprint.

Use

  wurfl_add_requested_capability(wurfl_handle hwurfl, const char *requested_capability);

to add the capabilities you need.

wurfl_lookup function and http headers

For better accuracy in device detection and virtual capability computation you may use wurfl_lookup() which receives a header retrieve callback function pointer to be used to retrieve all http headers needed by subsequent computations. An example in C++ :

    #include <map>
    #include <string>
    #include <wurfl/wurfl.h>

    const char* get_header_value(const char* name, const void* headers) {
        const std::map<std::string, std::string> &headersMap = *((const std::map<std::string, std::string> *)headers);
        std::map<std::string, std::string>::iterator it = headersMap.find(header_name);

        if (it != headersMap.end()) {
            return it->second.c_str();
        }

        return 0;
    }


    int main() {
        std::map<std::string, std::string> headers;
        headers["User-Agent"] = "SomeUserAgent";
        headers["Device-Stock-UA"] = "SomeDeviceStockUserAgent";

        wurfl_handle hwurfl = wurfl_create();
        wurfl_error err = wurfl_load();

        if (err) {
            std::cout << wurfl_get_error_message(hwurfl) << std::endl;
            return 1;
        }

        wurfl_device_handle hdevice = wurfl_lookup(hwurfl, get_header_value, (void*)(&headers));

        if (!hdevice) {
            std::cout << "Lookup failed with error: " << wurfl_get_error_message(hwurfl) << std::endl;
        } else {
            std::cout << "The matched device's ID: " << wurfl_get_wurfl_id(hdevice) << std::endl;
            /*
                do something else with the wurfl device handle here..
            */
            wurfl_device_destroy(hdevice);
        }

        wurfl_destroy(hwurfl);
        return 0;
    }

WURFL Updater features

Since 1.8.3.0 InFuze C API provides a set of new functions to allow for seamless update of the DDR file (wurfl.zip or wurfl.xml.gz). Assuming your init code is as follows :

  wurfl_handle hwurfl = wurfl_create();

  // Define wurfl db
  error = wurfl_set_root(hwurfl, "/usr/share/wurfl/wurfl.zip");
  if (error != WURFL_OK) {
    printf("%s\n", wurfl_get_error_message(hwurfl));
    return -1;
  }

If you wish to have your /usr/share/wurfl/wurfl.zip file automatically updated when new DDR are released you will only need to :

  // substitute https://data.scientiamobile.com/xxxxxxx/wurfl.zip with your data url from scientiamobile vault
  error = wurfl_updater_set_data_url(hwurfl, "https://data.scientiamobile.com/xxxxxxx/wurfl.zip");
  if (error != WURFL_OK) {
    printf("Updater cannot run : %s\n", wurfl_get_error_message(hwurfl));
    return -1;
  }

  // specify how frequent shall we check for updates
  error = wurfl_updater_set_data_frequency(hwurfl, WURFL_UPDATER_FREQ_DAILY);

Now everyting is set up and after loading your DDR

  // Loads wurfl db into memory
  error = wurfl_load(c);
  if (error != WURFL_OK) {
    printf("%s\n", wurfl_get_error_message(hwurfl));
    return -1;
  }

You will want to start the updater thread :

  wurfl_updater_start(hwurfl);

For better operations logging and to troubleshoot any problem you might have we suggest to enable logging (before the first set_data_url call ) :

  wurfl_updater_set_log_path(hwurfl, "updater.log");

File "updater.log" will contain detailed information of all background operations.

API Documentation

The wurfl.h interface gives you access to the main WURFL functionalities. Listed below is a quick overview of the functions, along with a few example on how to correctly use them.

Note: As of WURFL 1.5 the functions get_capability and get_virtual_capability returns a zero terminated string.

Typedef Documentation:

typedef struct wurfl_device_capability_enumerator_tag* wurfl_device_capability_enumerator_handle

Description:

WURFL Device capability enumerator handle, used to enumerate capabilities in a specific WURFL device.

typedef struct wurfl_device_tag* wurfl_device_handle

WURFL Device handle, used to represent an instance of WURFL device.

typedef struct wurfl_tag* wurfl_handle

Description:

WURFL handle, used to represent an instance of WURFL database.

Enumeration Type Documentation:

enum wurfl_cache_provider

Enumerator:

WURFL_CACHE_PROVIDER_NONE

WURFL_CACHE_PROVIDER_LRU

WURFL_CACHE_PROVIDER_DOUBLE_LRU

enum wurfl_engine_target

Enumerator:

WURFL_ENGINE_TARGET_HIGH_ACCURACY

WURFL_ENGINE_TARGET_HIGH_PERFORMANCE

enum wurfl_error

Enumerator:

WURFL_OK: No error.

WURFL_ERROR_INVALID_HANDLE: Handle passed to function is invalid.

WURFL_ERROR_ALREADY_LOAD: wurfl_load has already been invoked on the specific wurfl_handle.

WURFL_ERROR_FILE_NOT_FOUND: File not found during wurfl_load.

WURFL_ERROR_UNEXPECTED_END_OF_FILE: Unexpected end of file or parsing error during wurfl_load.

WURFL_ERROR_INPUT_OUTPUT_FAILURE: Error reading stream during wurfl_load.

WURFL_ERROR_UNKNOWN: Unknown error.

WURFL_ERROR_INVALID_PARAMETER: Invalid parameter.

WURFL_ERROR_CAPABILITY_NOT_FOUND: Specified capability is missing.

Configuration Methods:

wurfl_error wurfl_add_patch(wurfl_handle hwurfl, const char* patch)

Availability:

1.4

Description:

Adds a WURFL patch to the patch collection.

Parameters:

wurfl_handle: The WURFL instance to add the patch to.

patch: The patch filename as a zero terminated ASCII string.

Returns:

WURFL_OK: If the function terminated correctly.

wurfl_error: If the function failed.

wurfl_error wurfl_add_requested_capability(wurfl_handle hwurfl, const char* requested_capability)

Availability:

1.4

Description:

Adds a capability to the requested capabilities collection. If this function is never called on a wurfl_handle, the wurfl_load() function will automatically load all the features in the WURFL repository. If one or more of the capabilities are added to the requested capabilities collection, only the specified ones (if available) will be loaded from the repository, resulting in a reduced memory footprint.

Parameters:

wurfl_handle: The WURFL instance.

requested_capability: The capability name as a zero terminated ASCII string.

Returns:

WURFL_OK: If the function terminated correctly, or a different.

wurfl_error: If the function failed.

wurfl_error wurfl_set_cache_provider(wurfl_handle hwurfl, wurfl_cache_provider cache_provider, const char* config)

Availability:

1.4

Description:

Sets the cache provider. Default is WURFL_CACHE_PROVIDER_DOUBLE_LRU.

Parameters:

wurfl_handle: The WURFL instance.

wurfl_engine_target: The cache provider.

config: The cache configuration as a zero terminated ASCII string, or a null pointer if the specified cache doesn't need any specific configuration.

Returns:

WURFL_OK: If the funciton terminated correctly, or another.

wurfl_error: If the function failed.

wurfl_error wurfl_set_engine_target(wurfl_handle hwurfl, wurfl_engine_target target)

Availability:

1.4

Description:

Sets the engine target. Default is WURFL_TARGET_HIGH_PERFORMANCE.

Parameters:

wurfl_handle: The WURFL instance

wurfl_engine_target: The new engine target (WURFL_TARGET_HIGH_ACCURACY or WURFL_TARGET_HIGH_PERFORMANCE)

Returns:

WURFL_OK: If the function terminated correctly.

wurfl_error: If the function failed

wurfl_error wurfl_set_root(wurfl_handle hwurfl, const char* root)

Availability:

1.4

Description:

Sets the WURFL root.

Parameters:

wurfl_handle: The WURFL instance to set the root to.

root: The root filename as a zero terminated ASCII string

Returns

WURFL_OK: If the function terminated correctly.

wurfl_error: If the function failed.

wurfl_error wurfl_set_useragent_priority(wurfl_handle hwurfl, wurfl_useragent_priority priority)

Availability:

1.5.2

Description:

Tells WURFL if it should prioritize use of the plain user agent (WURFL_USERAGENT_PRIORITY_USE_PLAIN_USERAGENT) over the default sideloaded browser user agent (WURFL_USERAGENT_PRIORITY_OVERRIDE_SIDELOADED_BROWSER_USERAGENT).

Parameters:

wurfl_handle: The WURFL instance to set the root to.

wurfl_useragent_priority: WURFL_USERAGENT_PRIORITY_USE_PLAIN_USERAGENT or WURFL_USERAGENT_PRIORITY_OVERRIDE_SIDELOADED_BROWSER_USERAGENT.

Returns:

WURFL_OK: If the function terminated correctly.

wurfl_error: If the function failed.

Example:

wurfl_set_useragent_priority(hwurfl, WURFL_USERAGENT_PRIORITY_USE_PLAIN_USERAGENT);

wurfl_error wurfl_load(wurfl_handle hwurfl)

Availability:

1.4

Description:

Performs WURFL root file and patch loading. Must be called after specifying root filename by calling wurfl_set_root to set the root file name, and optionally wurfl_add_patch and/or wurfl_add_requested_capability to respectively specify patches and requested capabilities (if no capability is requested, all capabilities from WURFL root file and patches are loaded).

Parameters:

wurfl_handle: The WURFL instance.

Returns:

WURFL_OK: If the function terminated correctly.

wurfl_error: If the function failed.

const char* wurfl_get_last_load_time_as_string(wurfl_handle hwurfl)

Availability:

1.5.1

Description:

Returns a zero terminated ASCIIZ string of the most recently successful WURFL load phase. 0 will be returned if WURFL has not been successfully initialized. The returned string has the following format: Www Mmm dd hh:mm:ss yyyy where Www is the weekday, Mmm the month (in letters), dd the day of the month, hh:mm:ss the time, and yyyy the year.

Parameters:

wurfl_handle: The WURFL instance to use.

Returns:

wurfl_handle wurfl_create()

Availability:

1.4

Description:

Creates a new WURFL instance. All configuration settings must be set prior to calling this method.

Returns:

wurfl_handle or a null pointer if the function failed.

const char* wurfl_get_api_version()

Availability:

1.5.1

Description:

Returns a string representing the currently used Libwurfl API version.

const char* wurfl_get_wurfl_info(wurfl_handle hwurfl)

Availability:

1.5.1

Description:

Returns a zero terminated ASCIIZ string containing infos on WURFL root and the loaded patches, or 0 if WURFL has not been initialized yet.

Parameters:

wurfl_handle: The WURFL instance to use.

const char* wurfl_get_engine_target_as_string(wurfl_handle hwurfl)

Availability:

1.5.1

Description:

Returns a string representing the currently set WURFL Engine Target. Possible values are "HIGH_ACCURACY", "HIGH_PERFORMANCE" or "INVALID".

Parameters:

wurfl_handle: The WURFL instance to use.

Returns:

HIGH_ACCURACY: WURFL is running in high accuracy mode.

HIGH_PERFORMANCE: WURFL is running in high performance mode.

INVALID: An invalid performance mode has been set.

WURFL Query Methods:

wurfl_device_handle wurfl_lookup(wurfl_handle hwurfl, wurfl_header_retrieve_callback header_retrieve_callback, const void *header_retrieve_callback_data)

Availability:

1.5.0

Description:

WURFL Device lookup function. You must provide a header retrieve function which returns a header value given a header name. If there are no headers with that name the header retrieve callback function should return 0. Otherwise, it should return the header value associated to that name.

You must also provide the header container in which all the headers are stored using the header_retrieve_callback_data parameter, so the header retrieve callback function will look into it when searching for a header. The header_retrieve_callback function will be called at least one time during the lookup phase, but it can be called multiple times to check for additional headers.

Parameters:

wurfl_handle: The WURFL instance.

wurfl_header_retrieve_callback: A callback for function each time a header is looked up.

header_retrieve_callback_data: A header container in which all headers are stored.

Returns:

A new WURFL device instance (wurfl_device_handle).

wurfl_device_handle wurfl_lookup_useragent(wurfl_handle hwurfl, const char* useragent)

Availability:

1.5.0

Description:

User Agent lookup function.

Parameters:

wurfl_handle: The WURFL instance.

useragent: The User Agent to lookup as a zero terminated ASCIIZ string.

Returns:

A new WURFL device instance, or a null pointer if the function failed.

Example:

wurfl_device_handle hdevice = wurfl_lookup_useragent(hwurfl, "USERAGENT");

if (hdevice) {
    cout << wurfl_device_get_id(hdevice) << endl;
}

const char* wurfl_device_get_id(wurfl_device_handle hwurfldevice)

Availability:

1.4

Description:

Returns the device id of this device

Parameters:

hwurfldevice: The WURFL device instance.

Returns:

The WURFL device id as a zero terminated ASCIIZ string, or a null pointer if the function failed.

const char* wurfl_device_get_root_id(wurfl_device_handle hwurfldevice)

Description:

Retrieve the root device id of this device.

Parameters:

hwurfldevice: The WURFL device instance.

Returns:

The WURFL device root id as a zero terminated ASCIIZ string, or a null pointer if the function failed.

const char* wurfl_device_get_useragent(wurfl_device_handle hwurfldevice)

Availability:

1.4

Description:

Retrieve the User Agent for a device (as found in the WURFL repository).

Parameters:

hwurfldevice: The WURFL device instance

Returns:

The matched User Agent (as contained in the WURFL repository) as a zero terminated ASCIIZ string, or a null pointer if the function failed.

const char* wurfl_device_get_original_useragent(wurfl_device_handle hwurfldevice)

Availability:

1.5.1

Description:

Returns the original useragent of this device.

Parameters:

wurfl_device_handle: The WURFL device instance

Returns:

The original User Agent as a zero terminated ASCIIZ string, or a null pointer if the function failed.

const char* wurfl_device_get_normalized_useragent(wurfl_device_handle hwurfldevice)

Availability:

1.5.0

Description:

Returns the normalized useragent of this device as a zero terminated ASCIIZ string, or a null pointer if the function failed.

Parameters:

hwurfldevice: The WURFL device instance.

Returns:

Returns the normalized useragent of this device as a zero terminated ASCIIZ string, or a null pointer if the function failed

wurfl_device_handle wurfl_get_device(wurfl_handle hwurfl, const char* deviceid)

Availability:

1.4

Description:

Retrieve a device by device id.

Parameters:

wurfl_handle: The WURFL instance.

deviceid: The wurfl device id to lookup as a zero terminated ASCIIZ string.

Returns:

A new WURFL device instance, or a null pointer if the function failed.

void wurfl_device_destroy(wurfl_device_handle hwurfldevice)

Availability:

1.4

Description:

Releases a wurfl_device_handle. All wurfl_device_capability_enumerator_handle's relative to this device handle must be released by calling wurfl_device_capability_enumerator_destroy on them before calling this function.

Parameters:

hwurfldevice: The WURFL device instance to destroy.

void wurfl_destroy(wurfl_handle hwurfl)

Availability:

1.4

Description:

Releases a wurfl_handle. All wurfl_device_handles relative to this handle must be released by calling wurfl_device_destroy on them before calling this function.

Parameters:

wurfl_handle: The WURFL instance to destroy.

const char* wurfl_device_get_capability(wurfl_device_handle hwurfldevice, const char* capability)

Description:

Retrieves a capability value from a device.

Parameters:

hwurfldevice: The WURFL device instance.

capability: The capability name as a zero terminated ASCIIZ string.

Returns:

The capability value as a zero terminated ASCIIZ string, or a null pointer if the function failed.

const char* wurfl_device_get_virtual_capability(wurfl_device_handle hwurfldevice, const char* capability)

Description:

Retrieves a virtual capability value from a device.

Parameters:

hwurfldevice: The WURFL device instance.

capability: The virtual capability name as a zero terminated ASCIIZ string.

Returns:

The virtual capability value as a zero terminated ASCIIZ string, or a null pointer if the function failed.

int wurfl_device_get_capability_as_int(wurfl_device_handle hwurfldevice, const char *capability)

Availability:

1.5.0

Description:

Retrieves a capability value as an integer value from a device.

Parameters:

wurfl_device_handle: The WURFL device instance.

capability: The capability name as a zero terminated ASCIIZ string.

Returns:

Returns the capability value as an integer.

Example:

wurfl_device_handle hdevice = wurfl_lookup_useragent(hwurfl, "USERAGENT");

if (hdevice) {

    int resolutionWidth = wurfl_device_get_capability_as_int(hdevice, "resolution_width");

    if (resolutionWidth == 800) {
        cout << "Do something useful for device with a 800 width resolution" << endl;
    }
    else if (resolutionWidth == 1200) {
        cout << "Do something useful for device with a 1200 width resolution" << endl;
    }
}

int wurfl_device_get_virtual_capability_as_int(wurfl_device_handle hwurfldevice, const char *virtual_capability)

Availability:

1.5.0

Description:

Retrieves a virtual capability value as an integer value from a device.

Parameters:

wurfl_device_handle: The WURFL device instance.

virtual_capability: The virtual capability name as a zero terminated ASCIIZ string.

Returns:

Returns the virtual capability value as an integer.

Example:

wurfl_device_handle hdevice = wurfl_lookup_useragent(hwurfl, "USERAGENT");

if (hdevice) {

    int browserVersion = wurfl_device_get_virtual_capability_as_int(hdevice, "advertised_browser_version");

    if (browserVersion == 26) {
        cout << "Use special layout" << endl;
    }
    else {
        cout << "Use common layout" << endl;
    }
}

int wurfl_device_get_capability_as_bool(wurfl_device_handle hwurfldevice, const char *capability)

Availability:

1.5.0

Description:

Retrieves a capability value as a boolean value from a device.

Parameters:

wurfl_device_handle: The WURFL device instance.

capability: The capability name as a zero terminated ASCIIZ string.

Returns:

Returns the capability value as a boolean.

Example:

wurfl_device_handle hdevice = wurfl_lookup_useragent(hwurfl, "USERAGENT");

if (hdevice) {

    bool isWireless = wurfl_device_get_capability_as_bool(hdevice, "is_wireless_device");

    if (isWireless) {
        cout << "Do something useful for a wireless device" << endl;
    }
    else {
        cout << "Do something useful for a non wireless device" << endl;
    }
}

int wurfl_device_get_virtual_capability_as_bool(wurfl_device_handle hwurfldevice, const char *virtual_capability)

Availability:

1.5.0

Description:

Retrieves a virtual capability value as a boolean value from a device.

Parameters:

wurfl_device_handle: The WURFL device instance.

virtual_capability: The virtual capability name as a zero terminated ASCIIZ string.

Returns:

Returns the virtual capability value as a boolean.

Example:

wurfl_device_handle hdevice = wurfl_lookup_useragent(hwurfl, "USERAGENT");

if (hdevice) {

    bool isAndroid = wurfl_device_get_virtual_capability_as_bool(hdevice, "is_android");

    if (isAndroid) {
        cout << "Do something useful for Android devices" << endl;
    }
    else {
        cout << "Do something useful for non Android devices" << endl;
    }
}

int wurfl_device_is_actual_device_root(wurfl_device_handle hwurfldevice)

Description:

Verifies if the device is an actual device root.

Parameters

hwurfldevice: The WURFL device instance.

Returns:

1 if the specified device is an actual device root, 0 otherwise.

wurfl_useragent_priority wurfl_get_useragent_priority(wurfl_handle hwurfl)

Availability:

1.5.2

Description:

Tells if WURFL is using the plain user agent or the sideloaded browser user agent for device detection. Returns either WURFL_USERAGENT_PRIORITY_USE_PLAIN_USERAGENT or WURFL_USERAGENT_PRIORITY_OVERRIDE_SIDELOADED_BROWSER_USERAGENT.

Parameters:

wurfl_handle: The WURFL instance to set the root to.

Returns:

wurfl_useragent_priority: WURFL_USERAGENT_PRIORITY_OVERRIDE_SIDELOADED_BROWSER_USERAGENT or WURFL_USERAGENT_PRIORITY_USE_PLAIN_USERAGENT.

const char* wurfl_get_useragent_priority_as_string(wurfl_handle hwurfl)

Availability:

1.5.2

Description:

Tells if WURFL is using the plain user agent or the sideloaded browser user agent for device detection, returning a zero terminated ASCIIZ string.

Parameters:

wurfl_handle: The WURFL instance to set the root to.

Returns:

WURFL_USERAGENT_PRIORITY_OVERRIDE_SIDELOADED_BROWSER_USERAGENT or WURFL_USERAGENT_PRIORITY_USE_PLAIN_USERAGENT as a string.

int wurfl_device_has_capability(wurfl_device_handle hwurfldevice, const char* capability)

Availability:

1.5.0

Description:

Verifies if the device has a specific capability.

Parameters:

hwurfldevice: The WURFL device instance. capability: The capability name as a zero terminated ASCIIZ string.

Returns:

1 if the specified device has the requested capability, 0 otherwise.

Example:

wurfl_device_handle hdevice = wurfl_lookup_useragent(hwurfl, "USERAGENT");

if (hdevice && wurfl_device_has_capability(hdevice, "requested_capability")) {
    cout << "Requested capability has been found" << endl;
}

int wurfl_device_has_virtual_capability(wurfl_device_handle hwurfldevice, const char* capability)

Availability:

1.5.0

Description:

Verifies if the device has a specific virtual capability.

Parameters:

hwurfldevice: The WURFL device instance.

capability: The virtual capability name as a zero terminated ASCIIZ string.

Returns:

1 if the specified device has the requested virtual capability, 0 otherwise.

Example:

wurfl_device_handle hdevice = wurfl_lookup_useragent(hwurfl, "USERAGENT");

if (hdevice && wurfl_device_has_capability(hdevice, "requested_virtual_capability")) {
    cout << "Requested virtual capability has been found" << endl;
}

int wurfl_has_capability(wurfl_handle hwurfl, const char *capability)

Availability:

1.5.3

Description:

Verify if a capability is a valid wurfl capability.

Parameters:

wurfl_handle: The WURFL instance to use. capability: The capility to verify.

Returns:

1 if the capility exists, otherwise 0.

int wurfl_has_virtual_capability(wurfl_handle hwurfl, const char *virtual_capability)

Availability:

1.5.3

Description:

Verify if a virtual capability is a valid wurfl virtual capability.

Parameters:

wurfl_handle: The WURFL instance to use. virtual_capability: The capility to verify.

Returns:

1 if the capility exists, otherwise 0.

WURFL Device Methods:

wurfl_capability_enumerator_handle wurfl_get_capability_enumerator(wurfl_handle hwurfl)

Availability:

1.5.1

Description:

Returns a new WURFL capability enumerator instance.

Parameters:

wurfl_handle: The WURFL handle instance to use.

Example:

wurfl_handle hwurfl = [...];

wurfl_capability_enumerator_handle hcapabilityenumerator = wurfl_get_capability_enumerator(hwurfl);

while (wurfl_capability_enumerator_is_valid(hcapabilityenumerator)) {
    const char *name = wurfl_capability_enumerator_get_name(hcapabilityenumerator);

    // do something with name

    wurfl_capability_enumerator_move_next(hcapabilityenumerator);
}

wurfl_capability_enumerator_destroy(hcapabilityenumerator);

wurfl_capability_enumerator_handle wurfl_get_virtual_capability_enumerator(wurfl_handle hwurfl)

Availability:

1.5.1

Description:

Returns a new WURFL virtual capability enumerator instance

Parameters:

wurfl_handle: The WURFL handle instance to use.

Returns:

wurfl_capability_enumerator_handle: A new capability enumerator handle.

Example:

wurfl_handle hwurfl = [...];
wurfl_capability_enumerator_handle hvirtualcapabilityenumerator = wurfl_get_virtual_capability_enumerator(hwurfl);

while (wurfl_capability_enumerator_is_valid(hvirtualcapabilityenumerator)) {

    const char *name = wurfl_capability_enumerator_get_name(hvirtualcapabilityenumerator);

    // do something with name

    wurfl_capability_enumerator_move_next(hvirtualcapabilityenumerator);
}

wurfl_capability_enumerator_destroy(hvirtualcapabilityenumerator);

void wurfl_capability_enumerator_destroy(wurfl_capability_enumerator_handle hwurflcapabilityenumeratorhandle)

Availability:

1.5.1

Description:

Releases a wurfl_capability_enumerator_handle instance.

Parameters:

wurfl_capability_enumerator_handle: The capability enumerator instance to destroy.

int wurfl_capability_enumerator_is_valid(wurfl_capability_enumerator_handle hwurflcapabilityenumeratorhandle)

Availability:

1.5.1

Description:

Verifies if the WURFL enumerator instance is still valid.

Parameters:

wurfl_capability_enumerator_handle: The WURFL enumerator handler instance to check.

Returns:

1 if the specified device is valid, 0 otherwise.

void wurfl_capability_enumerator_move_next(wurfl_capability_enumerator_handle hwurflcapabilityenumeratorhandle)

Availability:

1.5.1

Description:

Moves the WURFL enumerator instance to the next capability

Parameters:

wurfl_capability_enumerator_handle: The WURFL enumerator handler instance to check.

const char* wurfl_capability_enumerator_get_name(wurfl_capability_enumerator_handle hwurflcapabilityenumeratorhandle)

Availability:

1.5.1

Description:

Returns the name of the current capability as a string.

Parameters:

wurfl_capability_enumerator_handle: The WURFL enumerator handler instance to check.

Returns:

Returns the name of the current capability as an ASCIIZ string, or a null pointer if the function failed.

wurfl_device_id_enumerator_handle wurfl_get_device_id_enumerator(wurfl_handle hwurfl)

Availability:

1.5.2

Description:

Returns a new WURFL device id enumerator instance.

Parameters:

wurfl_handle: The WURFL instance.

Example:

wurfl_handle hwurfl = [...];
wurfl_device_id_enumerator_handle hdeviceidenumerator = wurfl_get_device_id_enumerator(hwurfl);

while (wurfl_device_id_enumerator_is_valid(hdeviceidenumerator)) {
    const char *name = wurfl_device_id_enumerator_get_device_id(hdeviceidenumerator);

    // do something with name

    wurfl_device_id_enumerator_move_next(hdeviceidenumerator);
}

wurfl_device_id_enumerator_destroy(hdeviceidenumerator);

int wurfl_device_id_enumerator_is_valid(wurfl_device_id_enumerator_handle hdeviceidenumerator)

Availability:

1.5.2

Description:

Verifies if the WURFL enumerator instance is still valid

Parameters:

wurfl_device_id_enumerator_handle: The WURFL device id enumerator to verify.

Returns:

1 if the enumerator is valid, otherwise 0.

void wurfl_device_id_enumerator_move_next(wurfl_device_id_enumerator_handle hdeviceidenumerator)

Availability:

1.5.2

Description:

Moves the WURFL enumerator instance to the next capability.

Parameters:

wurfl_device_id_enumerator_handle: The WURFL device id enumerator to use.

void wurfl_device_id_enumerator_destroy(wurfl_device_id_enumerator_handle hdeviceidenumerator)

Availability:

1.5.2

Description:

Releases a wurfl_device_id_enumerator_handle instance.

Parameters:

wurfl_device_id_enumerator_handle: The WURFL device id enumerator to use.

const char* wurfl_device_id_enumerator_get_device_id(wurfl_device_id_enumerator_handle hdeviceidenumerator)

Availability:

1.5.2

Description:

Returns the name of the current capability as an ASCIIZ string, or a null pointer if the function failed.

Parameters:

wurfl_device_id_enumerator_handle: The WURFL device id enumerator to use.

Returns:

The current capability as an ASCIIZ string, or a null pointer if the function failed.

void wurfl_device_capability_enumerator_destroy(wurfl_device_capability_enumerator_handle enumerator_handle)

Availability:

1.5.0

Description:

Releases a wurfl_device_capability_enumerator_handle (see wurfl_device_get_capability_enumerator).

Parameters:

hwurfl_device_capability_enumerator_handle: The enumerator instance to be released.

Example:

if (hdevice) {
    const char *capabilityValue = wurfl_device_get_capability(hdevice, "brand_name");

    if (capabilityValue == "Nokia") {
        cout << "Do something useful for Nokia device" << endl;
    }
    else if (capabilityValue == "HTC") {
        cout << "Do something useful for HTC device" << endl;
    }
}

const char* wurfl_device_capability_enumerator_get_name(wurfl_device_capability_enumerator_handle)

Availability:

1.5.0

Description:

The current capability name (see wurfl_device_get_capability_enumerator).

Parameters:

hwurfl_device_capability_enumerator_handle: The enumerator instance.

Returns:

The name of the current capability as an ASCIIZ string, or a null pointer if the function failed.

const char* wurfl_device_capability_enumerator_get_value(wurfl_device_capability_enumerator_handle)

Availability:

1.5.0

Description:

The current capability value (see wurfl_device_get_capability_enumerator).

Parameters:

hwurfl_device_capability_enumerator_handle: The enumerator instance.

Returns:

The value of the current capability as an ASCIIZ string, or a null pointer if the function failed.

int wurfl_device_capability_enumerator_get_value_as_int(wurfl_device_capability_enumerator_handle enumerator_handle)

Availability:

1.5.0

Description:

The current capability value as an integer (see wurfl_device_get_capability_enumerator).

Parameters:

hwurfl_device_capability_enumerator_handle: The enumerator instance.

Returns:

The value of the current capability value as an integer, or a null pointer if the function failed.

int wurfl_device_capability_enumerator_get_value_as_bool(wurfl_device_capability_enumerator_handle enumerator_handle)

Availability:

1.5.0

Description:

The current capability value as an boolean value (see wurfl_device_get_capability_enumerator).

Parameters:

hwurfl_device_capability_enumerator_handle: The enumerator instance.

Returns:

The value of the current capability value as an boolean value, or a null pointer if the function failed.

int wurfl_device_capability_enumerator_is_valid(wurfl_device_capability_enumerator_handle)

Availability:

1.5.0

Description:

Verifies if the enumerator is still valid (see wurfl_device_get_capability_enumerator).

Parameters:

hwurfl_device_capability_enumerator_handle: The enumerator instance.

Returns:

1 if the enumerator is valid, 0 otherwise.

void wurfl_device_capability_enumerator_move_next(wurfl_device_capability_enumerator_handle)

Availability:

1.5.0

Description:

Moves the enumerator to the next capability (see wurfl_device_get_capability_enumerator).

Parameters:

hwurfl_device_capability_enumerator_handle: The enumerator instance.

wurfl_device_capability_enumerator_handle wurfl_device_get_capability_enumerator(wurfl_device_handle hwurfldevice)

Availability:

1.5.0

Description:

Creates a new capability enumerator for a device

Parameters:

hwurfldevice: The WURFL device instance.

Returns:

A new WURFL capability enumerator instance.

Example:

wurfl_device_handle hdevice = wurfl_lookup_useragent(hwurfl, "USERAGENT");

if (hdevice) {
    wurfl_device_capability_enumerator_handle hdevicecaps = wurfl_device_get_capability_enumerator(hdevice);

    while (wurfl_device_capability_enumerator_is_valid(hdevicecaps)) {
        cout << "  " << wurfl_device_capability_enumerator_get_name(hdevicecaps) << "=" << wurfl_device_capability_enumerator_get_value(hdevicecaps) << endl;
        wurfl_device_capability_enumerator_move_next(hdevicecaps);
    }
    wurfl_device_capability_enumerator_destroy(hdevicecaps);
}

wurfl_device_capability_enumerator_handle wurfl_device_get_virtual_capability_enumerator(wurfl_device_handle hwurfldevice)

Availability:

1.5.0

Description:

Creates a new virtual capability enumerator for a device.

Parameters:

hwurfldevice: The WURFL device instance.

Returns:

A new WURFL virtual capability enumerator instance.

Example:

wurfl_device_handle hdevice = wurfl_lookup_useragent(hwurfl, "USERAGENT");

if (hdevice) {
    wurfl_device_capability_enumerator_handle hdevicecaps = wurfl_device_get_virtual_capability_enumerator(hdevice);

    while (wurfl_device_capability_enumerator_is_valid(hdevicecaps)) {
        cout << "  " << wurfl_device_capability_enumerator_get_name(hdevicecaps) << "=" << wurfl_device_capability_enumerator_get_value(hdevicecaps) << endl;
        wurfl_device_capability_enumerator_move_next(hdevicecaps);
    }

    wurfl_device_capability_enumerator_destroy(hdevicecaps);
}

Error Handling:

void wurfl_has_error_message(wurfl_handle hwurfl)

Availability:

1.5.0

Description:

Indicates if the last call to the WURFL library on a specific wurfl_handl instance was successful.

Parameters:

wurfl_handle: The WURFL instance.

Example:

wurfl_add_requested_capability(hwurfl, "unavailable_capability");

if (wurfl_has_error_message(hwurfl)) {
    cout << wurfl_get_error_message(hwurfl) << endl;
}

const char* wurfl_get_error_message(wurfl_handle hwurfl)

Availability:

1.5.0

Description:

Returns the last error message (if any) produced by a call to the WURFL library on a specific wurfl_handle instance.

Parameters:

wurfl_handle: The WURFL instance.

Returns:

The last error message as a zero terminated ASCII string, or a null pointer if the function failed.

Example:

if (error != WURFL_OK) {
    cout << wurfl_get_error_message(hwurfl) << endl;
}

void wurfl_clear_error_message(wurfl_handle hwurfl)

Availability:

1.5.0

Description:

Clears the last error message (if any) produced by the last call to the WURFL library on a specific wurfl_handle instance.

Parameters:

wurfl_handle: The WURFL instance.

Example:

wurfl_add_requested_capability(hwurfl, "unavailable_capability");

if (wurfl_has_error_message(hwurfl)) {
    cout << wurfl_get_error_message(hwurfl) << endl;
    wurfl_clear_error_message(hwurfl);
}

License

2017 ScientiaMobile Incorporated All Rights Reserved.

NOTICE: All information contained herein is, and remains the property of ScientiaMobile Incorporated and its suppliers, if any. The intellectual and technical concepts contained herein are proprietary to ScientiaMobile Incorporated and its suppliers and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior written permission is obtained from ScientiaMobile Incorporated.