Hash/MatchMetrics.c

Match metrics example of using 51Degrees device detection.

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

1. Specify the name of the data file and properties the data set should be initialised with.
   const char* fileName = argv[1];

   fiftyoneDegreesPropertiesRequired properties =

   fiftyoneDegreesPropertiesDefault;

   properties.string = "IsMobile";

   fiftyoneDegreesPropertiesRequired

   Defines a set of properties which are required by a caller.

   Definition properties.h:240

   fiftyoneDegreesPropertiesRequired::string

   const char * string

   Separated list of required properties or NULL if all properties are required.

   Definition properties.h:245
2. Instantiate the 51Degrees data set within a resource manager from the specified data file with the required properties and the specified configuration.
   fiftyoneDegreesStatusCode status =

   fiftyoneDegreesHashInitManagerFromFile(

   &manager,

   &config,

   &properties,

   dataFilePath,

   exception);

   fiftyoneDegreesHashInitManagerFromFile

   fiftyoneDegreesStatusCode fiftyoneDegreesHashInitManagerFromFile(fiftyoneDegreesResourceManager *manager, fiftyoneDegreesConfigHash *config, fiftyoneDegreesPropertiesRequired *properties, const char *fileName, fiftyoneDegreesException *exception)

   Initialises the resource manager with a Hash data set resource populated from the Hash data file refe...

   fiftyoneDegreesStatusCode

   fiftyoneDegreesStatusCode

   Status returned from the initialisation of a resource.

   Definition status.h:81
3. Create a results instance ready to be populated by the data set.
   fiftyoneDegreesResultsHash *results =

   fiftyoneDegreesResultsHashCreate(

   &manager,

   1,

   0);

   fiftyoneDegreesResultsHash

   fiftyoneDegreesResultHashArray fiftyoneDegreesResultsHash

   Array of Hash results used to easily access and track the size of the array.

   Definition hash.h:383

   fiftyoneDegreesResultsHashCreate

   fiftyoneDegreesResultsHash * fiftyoneDegreesResultsHashCreate(fiftyoneDegreesResourceManager *manager, uint32_t userAgentCapacity, uint32_t overridesCapacity)

   Allocates a results structure containing a reference to the Hash data set managed by the resource man...
4. Process a single HTTP User-Agent string to retrieve the values associated with the User-Agent for the selected properties.
   fiftyoneDegreesResultsHashFromUserAgent(

   results,

   mobileUserAgent,

   strlen(mobileUserAgent),

   exception);

   fiftyoneDegreesResultsHashFromUserAgent

   void fiftyoneDegreesResultsHashFromUserAgent(fiftyoneDegreesResultsHash *results, const char *userAgent, size_t userAgentLength, fiftyoneDegreesException *exception)

   Process a single User-Agent and populate the device offsets in the results structure.
5. Obtain the match metrics. The results hold a result for each component, such as the hardware or the browser, and the metrics are taken across them. A walk of a component's graph sets the metrics of its result, so any graph not yet walked is walked first. A metric that is not needed can be passed as NULL.
   fiftyoneDegreesHashMatchMethod method;

   int32_t drift, difference, iterations;

   fiftyoneDegreesResultsHashGetMatchMetrics(

   results,

   &method,

   &difference,

   &drift,

   &iterations,

   NULL,

   exception);

   fiftyoneDegreesResultsHashGetMatchMetrics

   void fiftyoneDegreesResultsHashGetMatchMetrics(fiftyoneDegreesResultsHash *results, fiftyoneDegreesHashMatchMethod *method, int32_t *difference, int32_t *drift, int32_t *iterations, int32_t *matchedNodes, fiftyoneDegreesException *exception)

   Gets the match metrics of the results, taken across every result.

   fiftyoneDegreesHashMatchMethod

   fiftyoneDegreesHashMatchMethod

   DATA STRUCTURES.

   Definition hash.h:130
6. The drift is the largest number of characters a matched substring of a result was from where it was expected to be found, added up over the results. The maximum drift to allow when finding a match can be set through the configuration structure.
7. The difference is the total difference in hash code values between the matched substrings and the actual substrings. The maximum difference to allow when finding a match can be set through the configuration structure.
8. The iterations are the number of iterations required to get the device offset in the devices collection in the graph of nodes. This is indicative of the time taken to fetch the result.
9. The method is the highest method any result used, which provides information about the algorithm that was used to perform detection for a particular User-Agent. For more information on what each method means please see: How device detection works.
10. Obtain the matched User-Agent of the first result, which holds the matched substrings of the User-Agent separated with underscores.
    const char *matchedUserAgent =

    fiftyoneDegreesResultsHashGetMatchedUserAgent(results, 0, exception);

    fiftyoneDegreesResultsHashGetMatchedUserAgent

    const char * fiftyoneDegreesResultsHashGetMatchedUserAgent(fiftyoneDegreesResultsHash *results, uint32_t resultIndex, fiftyoneDegreesException *exception)

    Gets the matched User-Agent of one result, being the evidence value its component was matched from,...
11. Release the memory used by the results.
    fiftyoneDegreesResultsHashFree(results);

    fiftyoneDegreesResultsHashFree

    void fiftyoneDegreesResultsHashFree(fiftyoneDegreesResultsHash *results)

    Frees the results structure created by the fiftyoneDegreesResultsHashCreate method.
12. Finally release the memory used by the data set resource.
    fiftyoneDegreesResourceManagerFree(&manager);