Contextual History: Getting the Device Usage Profiles

This tutorial demonstrates how you can get device usage history profiles, and enumerate retrieved profile data lists.

This feature is supported in mobile applications only.

Warm-up

Become familiar with the Contextual History API basics by learning about:

• Getting a Profile Data List

  Get the device usage history profiles as a list of data records.

• Enumerating Profile Data Lists

  Enumerate the records contained in the retrieved profile data list.

Getting a Profile Data List

To retrieve a contextual history profile:

1. To use the functions and data types of the Contextual History API, include the <context_history.h> header file in your application:

   #include <context_history.h>
   

2. Create 2 handles: 1 for using the Contextual History API and 1 for the filter:

   // Contextual History API handle
   context_history_h handle;
   context_history_create(&handle);
   
   // Filter handle
   context_history_filter_h filter;
   context_history_filter_create(&filter);
   

3. Get information about the 5 applications used most frequently during the last 2 weeks (14 days) while a headphone has been connected:

   // Requesting the top 5 applications
   context_history_filter_set_int(filter, CONTEXT_HISTORY_FILTER_RESULT_SIZE, 5);
   
   // Limiting the time span of usage logs to 14 days
   context_history_filter_set_int(filter, CONTEXT_HISTORY_FILTER_TIME_SPAN, 14);
   
   // Limiting the context to the applications used while a headphone is connected
   context_history_filter_set_int(filter, CONTEXT_HISTORY_FILTER_AUDIO_JACK, CONTEXT_HISTORY_FILTER_AUDIO_JACK_CONNECTED);
   

4. Retrieve profile data based on the defined filter:

   context_history_list_h list;
   
   // Getting the list of records
   context_history_get_list(handle, CONTEXT_HISTORY_FREQUENTLY_USED_APP, filter, &list);
   
   // Release the filter after use
   context_history_filter_destroy(filter);
   

Enumerating Profile Data Lists

The list retrieved using the context_history_get_list() function contains a sorted list of records, each of which consists of a key and value pair.

To enumerate the list:

1. Check the number of records in the list.

   In some cases, the retrieved list can contain less records than the result size set in the filter.

   int size;
   context_history_list_get_count(list, &size);
   

2. Enumerate the list using a loop:

   int i, count;
   char* app_id;
   context_history_record_h record;
   
   for (i = 0; i < size; ++i)
   {
      // Getting the current record
      context_history_list_get_current(list, &record);
   
      // Retrieving the application ID and the total use count from the record
      context_history_record_get_string(record, CONTEXT_HISTORY_APP_ID, &app_id);
      context_history_record_get_int(record, CONTEXT_HISTORY_TOTAL_COUNT, &count);
   
      // Freeing the application ID string
      free(app_id);
   
      // Releasing the memory occupied by the record
      context_history_record_destroy(record);
   
      // Iterating to the next record
      context_history_list_move_next(list);
   }
   

3. Release the list to prevent any resource leaks:

   context_history_list_destroy(list);
   

4. When no longer needed, release and destroy the handle:

   context_history_destroy(handle);