C Match For Device Id Tutorial

What's Covered

This tutorial illustrates how to return a match for a Device Id. It shows how to first get the Device Id from a match, then get a match for that Device Id and return the value of the IsMobile property. This can be useful to look at devices that have already been matched at a previous date.

Code and Explanation

Match for device id example of using 51Degrees device detection. The example shows how to:

Specify name of the data file and properties the dataset should be initialised with.

												
	const char* fileName = argv[1];
	const char* properties = "IsMobile";

Instantiate the 51Degrees provider from the specified data file with the required properties, number of worksets in the pool and cache of the specific size.

									
	fiftyoneDegreesInitProviderWithPropertyString(
	fileName, &provider, properties, 4, 1000);

Retrieve a workset from the pool and use it for a single match.

									
	fiftyoneDegreesWorkset *ws = NULL;
	ws = fiftyoneDegreesProviderWorksetGet(&provider);

Get device ID from the match.

									
	fiftyoneDegreesMatchForDeviceId(ws, DeviceId);

Extract the value of the IsMobile property

									
	requiredPropertyIndex = fiftyoneDegreesGetRequiredPropertyIndex(ws->dataSet,
	 "IsMobile");
										

										

									
	fiftyoneDegreesSetValues(ws, requiredPropertyIndex);
	valueName = fiftyoneDegreesGetString(ws->dataSet, ws->values[0]->nameOffset);
	
										

										

									
	isMobile = &(valueName->firstByte);

Use device ID instead of a User-Agent string to perform match:

									
	fiftyoneDegreesMatchForDeviceId(ws, mobileDeviceId);

Release the workset back into the pool of worksets to be reused in one of the next matches.

									
	fiftyoneDegreesWorksetRelease(ws);

Finally release the memory taken by the provider.

									
	fiftyoneDegreesProviderFree(&provider);

This example assumes you have compiled with 51Degrees.c and city.c. This will happen automatically if you are compiling as part of the Visual Studio solution. Additionally, when running the program, the location of a 51Degrees data file must be passed as a command line argument if you wish to use Premium or Enterprise data files.

The main focus of this example is on extracting the device ID and later reusing it to obtain device information. Device ID is a more efficient way of storing information about devices as the entire ID can be stored as an array of bytes, where as when storing specific properties you would be dealing with strings, integers and doubles for each property.

The 51Degrees device ID is composed of four numbers separated by hyphens. Each number corresponds to the ID of the relevant profile. Each profile is a collection of property - value pairs for one of the components. A complete ID has one profile for each of the four components: Hardware-Software-Browser-Crawler.

For more information on the Pattern data model and how various entities are related please see: https://51degrees.com/support/documentation/device-detection-data-model For more information on how device detection works please see: https://51degrees.com/support/documentation/how-device-detection-works

Full Source File

												
#include <stdio.h>
#include "../src/pattern/51Degrees.h"

// Global settings and properties.
static fiftyoneDegreesProvider provider;

// Function declarations.
static void reportDatasetInitStatus(
    fiftyoneDegreesDataSetInitStatus status,
    const char* fileName);
const char* getIsMobile(fiftyoneDegreesWorkset* ws);
void run(fiftyoneDegreesProvider* provider);

int main(int argc, char* argv[]) {
    const char* properties = "IsMobile";
    const char* fileName = argc > 1 ? argv[1] : "../../../data/51Degrees-LiteV3.2.dat";

#ifdef _DEBUG
#ifndef _MSC_VER
    dmalloc_debug_setup("log-stats,log-non-free,check-fence,log=dmalloc.log");
#endif
#endif

    // Create a pool of 4 worksets with a cache for 1000 items.
    fiftyoneDegreesDataSetInitStatus status =
        fiftyoneDegreesInitProviderWithPropertyString(
        fileName, &provider, properties, 4, 1000);
    if (status != DATA_SET_INIT_STATUS_SUCCESS) {
        reportDatasetInitStatus(status, fileName);
        fgetc(stdin);
        return 1;
    }

    run(&provider);

    // Free the pool, dataset and cache.
    fiftyoneDegreesProviderFree(&provider);
    
#ifdef _DEBUG
#ifdef _MSC_VER
    _CrtDumpMemoryLeaks();
#else
    printf("Log file is %s\r\n", dmalloc_logpath);
#endif
#endif

    // Wait for a character to be pressed.
    fgetc(stdin);

    return 0;
}

void run(fiftyoneDegreesProvider* provider) {
    const char* isMobile;
    fiftyoneDegreesWorkset *ws = NULL;

    // User-Agent string of an iPhone mobile device.
    const char* mobileUserAgent = ("Mozilla/5.0 (iPhone; CPU iPhone OS 7_1 like Mac OS X) "
        "AppleWebKit/537.51.2 (KHTML, like Gecko) 'Version/7.0 Mobile/11D167 "
        "Safari/9537.53");

    // User-Agent string of Firefox Web browser version 41 on desktop.
    const char* desktopUserAgent = ("Mozilla/5.0 (Windows NT 6.3; WOW64; rv:41.0) "
        "Gecko/20100101 Firefox/41.0");

    // User-Agent string of a MediaHub device.
    const char* mediaHubUserAgent = ("Mozilla/5.0 (Linux; Android 4.4.2; X7 Quad Core "
        "Build/KOT49H) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 "
        "Chrome/30.0.0.0 Safari/537.36");


    printf("Starting Match For Device Id Example.\n");

    // Get a workset from the pool to perform this match.
    ws = fiftyoneDegreesProviderWorksetGet(provider);

    // Fetch device id for mobile User-Agent.
    fiftyoneDegreesMatch(ws, mobileUserAgent);
    char mobileDeviceId[40];
    fiftyoneDegreesGetDeviceId(ws, mobileDeviceId, 40);

    // Release workset after match complete and workset no longer required.
    fiftyoneDegreesWorksetRelease(ws);

    // Get a workset from the pool to perform this match.
    ws = fiftyoneDegreesProviderWorksetGet(provider);

    // Fetch device id for desktop User-Agent.
    fiftyoneDegreesMatch(ws, desktopUserAgent);
    char desktopDeviceId[40];
    fiftyoneDegreesGetDeviceId(ws, desktopDeviceId, 40);

    // Release workset after match complete and workset no longer required.
    fiftyoneDegreesWorksetRelease(ws);

    // Get a workset from the pool to perform this match.
    ws = fiftyoneDegreesProviderWorksetGet(provider);

    // Fetch device id for MediaHub User-Agent.
    fiftyoneDegreesMatch(ws, mediaHubUserAgent);
    char mediaHubDeviceId[40];
    fiftyoneDegreesGetDeviceId(ws, mediaHubDeviceId, 40);

    // Release workset after match complete and workset no longer required.
    fiftyoneDegreesWorksetRelease(ws);

    // Get a workset from the pool to perform this match.
    ws = fiftyoneDegreesProviderWorksetGet(provider);

    // Carries out a match for a mobile device id.
    printf("\nMobileDeviceId: %s\n", mobileDeviceId);
    fiftyoneDegreesMatchForDeviceId(ws, mobileDeviceId);
    isMobile = getIsMobile(ws);
    printf("   IsMobile: %s\n", isMobile);

    // Release workset after match complete and workset no longer required.
    fiftyoneDegreesWorksetRelease(ws);

    // Get a workset from the pool to perform this match.
    ws = fiftyoneDegreesProviderWorksetGet(provider);

    // Carries out a match for a desktop device id.
    printf("\nDesktopDeviceId: %s\n", desktopDeviceId);
    fiftyoneDegreesMatchForDeviceId(ws, desktopDeviceId);
    isMobile = getIsMobile(ws);
    printf("   IsMobile: %s\n", isMobile);

    // Release workset after match complete and workset no longer required.
    fiftyoneDegreesWorksetRelease(ws);

    // Get a workset from the pool to perform this match.
    ws = fiftyoneDegreesProviderWorksetGet(provider);

    // Carries out a match for a MediaHub device id.
    printf("\nMediHub Device Id: %s\n", mediaHubDeviceId);
    fiftyoneDegreesMatchForDeviceId(ws, mediaHubDeviceId);
    isMobile = getIsMobile(ws);
    printf("   IsMobile: %s\n", isMobile);

    // Release workset after match complete and workset no longer required.
    fiftyoneDegreesWorksetRelease(ws);
}

/**
 * Returns a string representation of the value associated with the IsMobile
 * property.
 * @param initialised workset of type fiftyoneDegreesWorkset
 * @returns a string representation of the value for IsMobile
 */
const char* getIsMobile(fiftyoneDegreesWorkset* ws) {
    int requiredPropertyIndex;
    const char* isMobile;
    const fiftyoneDegreesAsciiString* valueName;

    requiredPropertyIndex = fiftyoneDegreesGetRequiredPropertyIndex(ws->dataSet, "IsMobile");
    fiftyoneDegreesSetValues(ws, requiredPropertyIndex);
    valueName = fiftyoneDegreesGetString(ws->dataSet, ws->values[0]->nameOffset);
    isMobile = &(valueName->firstByte);
    return isMobile;
}

/**
* Reports the status of the data file initialization.
*/
static void reportDatasetInitStatus(fiftyoneDegreesDataSetInitStatus status,
    const char* fileName) {
    switch (status) {
    case DATA_SET_INIT_STATUS_INSUFFICIENT_MEMORY:
        printf("Insufficient memory to load '%s'.", fileName);
        break;
    case DATA_SET_INIT_STATUS_CORRUPT_DATA:
        printf("Device data file '%s' is corrupted.", fileName);
        break;
    case DATA_SET_INIT_STATUS_INCORRECT_VERSION:
        printf("Device data file '%s' is not correct version.", fileName);
        break;
    case DATA_SET_INIT_STATUS_FILE_NOT_FOUND:
        printf("Device data file '%s' not found.", fileName);
        break;
    case DATA_SET_INIT_STATUS_NULL_POINTER:
        printf("Null pointer to the existing dataset or memory location.");
        break;
    case DATA_SET_INIT_STATUS_POINTER_OUT_OF_BOUNDS:
        printf("Allocated continuous memory containing 51Degrees data file "
            "appears to be smaller than expected. Most likely because the"
            " data file was not fully loaded into the allocated memory.");
        break;
    default:
        printf("Device data file '%s' could not be loaded.", fileName);
        break;
    }
}

Full Source File

Summary

In this tutorial you have seen how to use the detector to retrieve the IsMobile property for a pre-defined Device ID string. The example can easily be modified to retrieve the value of any other property. Premium and Enterprise data files provide considerably more properties such as IsCrawler , PriceBand , HardwareVendor and ScreenInchesWidth . For a full list of properties and the data files they exist in please see the Property Dictionary .

What's Covered

Code and Explanation

Summary

More Tutorials