Type/Function Reference
How To Manage Data

This API provides a data service to allow apps to manage app-specific data on the AirVantage server.

Data is setup as assets -- a collection of fields that can be managed by the AirVantage server.

An asset field is a single piece of information that can be managed by the AirVantage server.

A field can be:

• variable allowing an app to read/write the value, and can be read from the AV server.
• setting allowing the AV server to read/write the value, and can be read by an app.
• command allowing the AV server to invoke a function in the app.

A field is referred to by a path, much like a path in Unix-like OSes. So a path is separated by slashes ("/"), a parent path cannot contain a field, and a parent path cannot contain a parent path and a child path of the same name.

Variable and setting fields also have types. The field types are:

• string
• integer
• float
• boolean

variable and setting fileds have no default values. When they are first created with the CreateResource API, they contain "null" values. They can also be set to "null" values with the SetNull API. A field does not have a fixed data type, so any of the SetInt/Float/Bool/String can be called for a certain field to change its value and its type. However, A GetInt/Float/Bool/String API must be called on a field with the matching type. In other words, a Get API does not perform type-casting.

Field Values and Activity

Set functions are available to set field values (including null). Get functions are available to get field values.

An app can register a handler so that it can be called when an activity occurs on a field. This is optional for variable and setting fields, but is required for command fields. Registered handlers are called only when activities from AV server occurs. Client activites do not trigger handlers.

A handler registered with a command field is invoked with an optional argument list sent from the AV server. The APIs GetInt/Float/Bool/StringArg and GetStringArgLength are available to extract the arguments in the handler definition. AV server does not send argument lists for handlers registered with variable and setting fields.

A handler registered with a command field must call the ReplyExecResult API at the end of its definition, in order to reply the command execution result to the AV server.

Time Series

This feature enables user apps to collect data when the device is offline. A time series record can be initialized using le_avdata_CreateRecord() and data can be accumulated using le_avdata_RecordInt(), le_avdata_RecordFloat(), le_avdata_RecordBool and le_avdata_RecordString with a specified time stamp (milliseconds elapsed since epoch). User apps can then open an avms session, and push the collected history data using le_avdata_PushRecord(). The callback used when calling le_avdata_PushRecord() will indicate whether the push has been successful or not.

This code sample shows how to collect data and send to the server (assuming session is opened)

static void PushCallbackHandler
(
    le_avdata_PushStatus_t status,
    void* contextPtr
)
{
    if (status == LE_AVDATA_PUSH_SUCCESS)
    {
        // data pushed successfully
    }
}
 
static void SendData()
{
    struct timeval tv;
    uint64_t utcMilliSec;
    le_result_t result;
 
    le_avdata_RecordRef_t recRef = le_avdata_CreateRecord();
 
    gettimeofday(&tv, NULL);
    utcMilliSec = (uint64_t)(tv.tv_sec) * 1000 + (uint64_t)(tv.tv_usec) / 1000; // get current time
    result = le_avdata_RecordFloat(recRef, "speed", 0.08, utcMilliSec);
 
    if (result != LE_OK)
    {
         le_avdata_PushRecord(recRef, PushCallbackHandler, NULL);
    }
 
    le_avdata_DeleteRecord(recRef);
}

User app session management

An app can request to open avms session and register a handler to get notified of avms session events. le_avdata_RequestSession() and le_avdata_ReleaseSession() can be used to open an avms session and close an avms session respectively. If the session was initiated by an user app, avms session will be closed when all apps release their session reference. le_avdata_AddSessionStateHandler() and le_avdata_RemoveSessionStateHandler() can be used to add and remove notification handlers.

Fatal Behavior

An invalid asset name or field name is treated as a fatal error (i.e. non-recoverable) and will result in the client app being terminated.

Copyright (C) Sierra Wireless Inc.