• About Us
  • Blog
  • Basket
  • Account
  • Sign In
  •  

C API

What's Covered

This tutorial illustrates how to append a CSV file containing User-Agent strings with IsMobile, PlatformName and PlatformVersion properties. The following aspects of the API are covered:

  • How to perform a User-Agent match.
  • How to reuse resources to perform subsequent matching.
  • How to retrieve match results for a specific property.
  • How to append a property value to a CSV file.

Code and Explanation

Offline processing example of using 51Degrees device detection. The example shows how to:

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

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

  2. Instantiate the 51Degrees device detection provider using an array of properties as opposed to a string containing coma separated properties.

    	fiftyoneDegreesInitProviderWithPropertyArray(
    		fileName, &provider, properties, propertiesCount, 4, 1000);
    	

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

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

  4. Open an input file with a list of User-Agents, and an output file,

    	FILE* fin = fopen(inputFile, "r");
    	FILE* fout = fopen(outputFile, "w");
    	

  5. Write a header to the output file with the property names in '|' separated CSV format ('|' separated because some User-Agents contain commas)

    	fprintf(fout, "User-Agent");
    	for (j=0;j<propertiesCount;j++) {
    		fprintf(fout, "|%s", propertiesArray[j]);
    	}
    	fprintf(fout, "\n");
    	

  6. For the first 20 User-Agents in the input file, perform a match then write the User-Agent along with the values for chosen properties to the CSV.

    	for (i=0;i<20;i++) {
    		fgets(userAgent, sizeof(userAgent), fin);
    		userAgent[strlen(userAgent)-1] = '\0';
    		fprintf(fout, "%s", userAgent);
    		fiftyoneDegreesMatch(ws, userAgent);
    		for (j=0;j<propertiesCount;j++) {
    			value = getValue(ws, propertiesArray[j]);
    			fprintf(fout, "|%s", value);
    		}
    		fprintf(fout, "\n");
    	}
    	

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

    	fiftyoneDegreesWorksetRelease(ws);
    	

  8. 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.

This example demonstrates one possible use of the API and device data for the offline data processing. It also demostrates that you can reuse the retrieved workset for multiple uses and only then return it to the pool.

Full Source File
#include "../src/pattern/51Degrees.h"

// Global settings and properties.
static fiftyoneDegreesProvider provider;
char *properties[3];

// Function declarations.
static void reportDatasetInitStatus(
    fiftyoneDegreesDataSetInitStatus status,
    const char* fileName);
const char* getValue(fiftyoneDegreesWorkset* ws, char* propertyName);
void run(fiftyoneDegreesProvider* provider, char* properties[],
    int propertiesCount, const char *inputFile);

int main(int argc, char* argv[]) {
    properties[0] = "IsMobile";
    properties[1] = "PlatformName";
    properties[2] = "PlatformVersion";
    int propertiesCount = 3;
    const char* fileName = argc > 1 ? argv[1] : "../../../data/51Degrees-LiteV3.2.dat";
    const char* inputFile = argc > 2 ? argv[2] : "../../../data/20000 User Agents.csv";

#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 =
        fiftyoneDegreesInitProviderWithPropertyArray(
        fileName, &provider, (const char**)properties, propertiesCount, 4, 1000);
    if (status != DATA_SET_INIT_STATUS_SUCCESS) {
        reportDatasetInitStatus(status, fileName);
        fgetc(stdin);
        return 1;
    }

    run(&provider, properties, propertiesCount, inputFile);

    // 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, char* properties[],
         int propertiesCount, const char *inputFile) {
    char userAgent[1000];
    const char* value;
    int i, j;
    fiftyoneDegreesWorkset *ws = NULL;

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

    printf("Starting Offline Processing Example.\n");

    // Opens input and output files.
    char* outputFile = "offlineProcessingOutput.csv";
    FILE* fin = fopen(inputFile, "r");
    FILE* fout = fopen(outputFile, "w");

    // Print CSV headers to output file.
    fprintf(fout, "User-Agent");
    for (j=0;j<propertiesCount;j++) {
        fprintf(fout, "|%s", properties[j]);
    }
    fprintf(fout, "\n");

    // Carries out match for first 20 User-Agents and prints results to
    // output file.
    for (i=0;i<20;i++) {
        fgets(userAgent, sizeof(userAgent), fin);
        userAgent[strlen(userAgent)-1] = '\0';
        fprintf(fout, "%s", userAgent);
        fiftyoneDegreesMatch(ws, userAgent);
        for (j=0;j<propertiesCount;j++) {
            value = getValue(ws, properties[j]);
            fprintf(fout, "|%s", value);
        }
        fprintf(fout, "\n");
    }

    printf("Output Written to %s\n", outputFile);

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

/**
 * Returns a string representation of the value associated with the required
 * property name. If the property name is not valid an empty string is
 * returned.If the property relates to a list with more than one value then
 * values are separated by | characters.
 * @param propertyName pointer to a string containing the property name
 * @returns a string representation of the value for the property
 */
const char* getValue(fiftyoneDegreesWorkset* ws, char* propertyName) {
    int requiredPropertyIndex;
    const char* result;
    const fiftyoneDegreesAsciiString* valueName;

    requiredPropertyIndex = fiftyoneDegreesGetRequiredPropertyIndex(ws->dataSet, propertyName);
    if (requiredPropertyIndex != -1) {
        fiftyoneDegreesSetValues(ws, requiredPropertyIndex);
        valueName = fiftyoneDegreesGetString(ws->dataSet, ws->values[0]->nameOffset);
        result = &(valueName->firstByte);
        return result;
    }
    else {
        return "";
    }
}

/**
* 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

Offline device detection is frequently required for a variety of reasons such as generating reports. The example is based on an actual support request where several properties had to be added to the CSV file before it could be passed on for another department to use.

This tutorial covered how to use the detector offline to append the first 20 lines of a CSV file with Lite properties: IsMobile, PlatformName and PlatformVersion. Using a Premium or an Enterprise data file gives you access to a far greater number of properties including HardwareVendor, PriceBand, ScreenInchesWidth, IsCrawler and more. A full list of properties and the data file version they are present in can be viewed in the Property Dictionary.