AirVantage Data

API 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 Air Vantage server. There can be multiple fields in an asset.

A field can be:

  • variable allows an app to set the value, and can be read from the AV server.
  • setting allows the AV server to set the value, and can be read by an app.
  • command allows the AV server to invoke a command or function in the app.

All fields have names. Variable and setting fields also have a type. The possible field types, along with the default value are:

  • string (empty string)
  • integer (0)
  • float (0.0)
  • boolean (false)
  • binary (zero-length block).

Default values can be overwritten in the asset definition. Currently, string, integer, float and boolean fields are supported; binary fields will be supported in the future.

Asset Data Instances

An app that needs to send data to the AirVantage server must first create an asset instance using le_avc_Create() with the name of the asset definition. Once an asset instance is created, the app can begin accessing the instance's fields.

Multiple instances of the same asset can be created, as well as multiple instances of different assets.

Asset definitions are specified in the assets section of the app's cdef file.

Field Values and Activity

Set functions are available to set variable field values. Get functions are available to get settings fields' values.

An app can register a handler so that it can be called when activity occurs on a field. This is optional for variable and setting fields, but is required for command fields.

  • variable called when the field is read by the AV server. The app can then call the appropriate set function to provide a new value for the field.
  • setting called when the field has been updated by the AV server with a new value. The app can use the appropriate get function to retrieve the new value.
  • command called when the AV server wants to invoke a command. The app should perform an appropriate action or call a function to execute this command.

Registered handlers are only called when the server performs the associated activity on a specific field of an asset instance. For example, a handler registered on a variable field will be called if the server reads only that field of an instance; it will not be called if the server reads the whole instance of an asset.

Leaving it optional to register handlers for variable and setting fields allows an app to decide how it wants to access variable and setting fields. It can decide to only do something in response to the AV server, or it can work independently of the AV server updating variables when it has a new value, and reading settings only when it needs the value.

Observe

If the Observe is enabled, the AirVantage Server will send observe requests on all user-defined assets of an app.

Whenever an app (asset) changes a field value by using le_avdata_Set*(), it'll trigger a notify if Observe is enabled on that asset. The notify contains only the value of the changed field.

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. Use of this work is subject to license.