All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
swi_airvantage.h File Reference
#include <stdlib.h>
#include "returncodes.h"
#include "swi_dset.h"

Go to the source code of this file.

General functionalities.

#define SWI_AV_ERROR   1
 
#define SWI_AV_INFO   1
 
#define SWI_AV_CX_SYNC   UINT_MAX
 Value to be used to request synchronous connection to server using swi_av_ConnectToServer.
 
typedef struct swi_av_Asset swi_av_Asset_t
 
rc_ReturnCode_t swi_av_Init ()
 
rc_ReturnCode_t swi_av_Destroy ()
 
rc_ReturnCode_t swi_av_ConnectToServer (unsigned int latency)
 
rc_ReturnCode_t swi_av_TriggerPolicy (const char *policyPtr)
 
rc_ReturnCode_t swi_av_asset_Create (swi_av_Asset_t **asset, const char *assetIdPtr)
 
rc_ReturnCode_t swi_av_asset_Start (swi_av_Asset_t *asset)
 
rc_ReturnCode_t swi_av_asset_Destroy (swi_av_Asset_t *asset)
 

Data Sending Simple API

enum  swi_av_timestamp_t { SWI_AV_TSTAMP_NO = 0, SWI_AV_TSTAMP_AUTO = 1 }
 
rc_ReturnCode_t swi_av_asset_PushString (swi_av_Asset_t *asset, const char *pathPtr, const char *policyPtr, uint32_t timestamp, const char *valuePtr)
 
rc_ReturnCode_t swi_av_asset_PushInteger (swi_av_Asset_t *asset, const char *pathPtr, const char *policyPtr, uint32_t timestamp, int64_t value)
 
rc_ReturnCode_t swi_av_asset_PushFloat (swi_av_Asset_t *asset, const char *pathPtr, const char *policyPtr, uint32_t timestamp, double value)
 

Data Sending Advanced API

enum  swi_av_Table_Storage_t { STORAGE_RAM = 0, STORAGE_FLASH }
 
typedef struct swi_av_Table swi_av_Table_t
 
rc_ReturnCode_t swi_av_table_Create (swi_av_Asset_t *asset, swi_av_Table_t **table, const char *pathPtr, size_t numColumns, const char **columnNamesPtr, const char *policyPtr, swi_av_Table_Storage_t persisted, int purge)
 
rc_ReturnCode_t swi_av_table_Destroy (swi_av_Table_t *table)
 
rc_ReturnCode_t swi_av_table_PushFloat (swi_av_Table_t *table, double value)
 
rc_ReturnCode_t swi_av_table_PushInteger (swi_av_Table_t *table, int value)
 
rc_ReturnCode_t swi_av_table_PushString (swi_av_Table_t *table, const char *value)
 
rc_ReturnCode_t swi_av_table_PushRow (swi_av_Table_t *table)
 

Data Reception

typedef void(* swi_av_DataWriteCB )(swi_av_Asset_t *asset, const char *pathPtr, swi_dset_Iterator_t *data, int ack_id, void *userDataPtr)
 
rc_ReturnCode_t swi_av_RegisterDataWrite (swi_av_Asset_t *asset, swi_av_DataWriteCB cb, void *userDataPtr)
 
rc_ReturnCode_t swi_av_Acknowledge (int ackId, int status, const char *errMsgPtr, const char *policyPtr, int persisted)
 

Asset Update

Using those APIs and types, the application can receive update request, coming with update files from update package sent by AirVantage Services platform.

typedef rc_ReturnCode_t(* swi_av_updateNotificationCB )(swi_av_Asset_t *asset, const char *componentNamePtr, const char *versionPtr, const char *updateFilePathPtr, swi_dset_Iterator_t *customParams, void *userDataPtr)
 
rc_ReturnCode_t swi_av_RegisterUpdateNotification (swi_av_Asset_t *asset, swi_av_updateNotificationCB cb, void *userDataPtr)
 
rc_ReturnCode_t swi_av_SendUpdateResult (swi_av_Asset_t *asset, const char *componentNamePtr, int updateResult)
 

Detailed Description

Using this API, an application can work with Sierra Wireless AirVantage Services Platform to:

  • request connection to AirVantage server
  • send data
  • receive data
  • receive asset update request

This module relies on Agent process, which is responsible for queuing data, managing the flush timers and sending the data to the remote AirVantage server. Many of the APIs in this module relay the data to the Agent; the Agent then manages the data as described.

Two methods are supported for sending data to the AirVantage servers:

  • The swi_av_asset_Push* functions: this is a simple API for managing how to send data, this is the recommended method for most use cases.
  • Tables API (via swi_av_table_Create): this allows for more advanced control of the transfer of data.

Macro Definition Documentation

#define SWI_AV_ERROR   1

Defines whether the library displays error traces (on stdout) to help debugging errors. Using 0 for this setting will ensure no printing is done by the library.

Typedef Documentation

typedef struct swi_av_Asset swi_av_Asset_t

An Asset is the AirVantage Application Services object used to send data to the AirVantage Application Services server. Instances of this object must be created through swi_av_asset_Create.

typedef void(* swi_av_DataWriteCB)(swi_av_Asset_t *asset,const char *pathPtr,swi_dset_Iterator_t *data,int ack_id,void *userDataPtr)

DataWrite callback to receive data coming from the server.

No automatic acknowledge of received data will be done, so application that wants the server to receive acknowledge needs to call swi_av_Acknowledge function.

String parameters given to this function will be released when the callback returns.

Parameters
asset[IN] Asset receiving the data
pathPtr[IN] Path targeted by the data sent by the server.
data[IN] Data iterator containing the received data. The data contained in the iterator will be automatically released when the callback returns.
ack_id[IN] ID to be used to acknowledge the received data. If ack_id=0 then there is no need to acknowledge.
userDataPtr[IN] User data given at callback registration.
typedef struct swi_av_Table swi_av_Table_t

A Table is the Airvantage objects handling staging database tables, to buffer, consolidate and send structured data. Instances of this object must be created through swi_av_table_Create.

typedef rc_ReturnCode_t(* swi_av_updateNotificationCB)(swi_av_Asset_t *asset,const char *componentNamePtr,const char *versionPtr,const char *updateFilePathPtr,swi_dset_Iterator_t *customParams,void *userDataPtr)

asset update notification callback.

The callback will be called when the associated asset is responsible to manage a software update request coming from AirVantage services platform.

The application must call swi_av_SendUpdateResult explicitly to send update result, otherwise no result is sent, retry mechanism will be started and eventually the update status will be set to failed.

String parameters will be released when the callback returns.

Parameters
asset[IN] Asset receiving the update notification
componentNamePtr[IN] Identifier of the component to update, (the component name is a path in dotted notation) the name is defined in update package manifest file, here it is provided without the assetid at the beginning.
versionPtr[IN] Version of the component to install. Version can be empty string (but not NULL!) to specify de-installation request, non empty string for regular update/install of software component.
updateFilePathPtr[IN] Absolute path to local file to use on the device to do the update, can be empty string when version is empty too. The file will be automatically deleted when the update process ends, so once swi_av_SendUpdateResult has been called, or all retries have been done for a single component update, the file existence on file system is not guaranteed anymore.
customParams[IN] Application specifics parameters, defined in update package, can be NULL if no custom parameter was defined. To be processed using #swi_dset_Iterator_t API, embedded data in the iterator will be automatically released when this callback returns.
userDataPtr[IN] User data given at callback registration
Returns
RC_OK when the callback ran correctly (it doesn't necessarily means the update was successful, see swi_av_SendUpdateResult), any other return value will be interpreted as error.

Enumeration Type Documentation

Specific values for storage.

Enumerator
STORAGE_RAM 

Non persistent, everything is saved only in RAM.

STORAGE_FLASH 

Persistent, everything is saved to the FLASH memory.

Specific values for timestamps to be used with swi_av_asset_Push* functions. (Those values are not meant to be used with advanced swi_av_table_Push* functions). Timestamps values 0 and 1 (in second since Unix Epoch) are reserved for those special timestamp requests.

Enumerator
SWI_AV_TSTAMP_NO 

Explicitly request no timestamp to send alongside the data.

SWI_AV_TSTAMP_AUTO 

Timestamp will be automatically generated when the data is added.

Function Documentation

rc_ReturnCode_t swi_av_Acknowledge ( int  ackId,
int  status,
const char *  errMsgPtr,
const char *  policyPtr,
int  persisted 
)

Acknowledges a server message received with an acknowledgment ticket id. No automatic acknowledge will be done, so application that wants the server to receive acknowledge needs to call this function.

Returns
RC_OK on success
RC_BAD_PARAMETER if the requested policy name is not found.
Parameters
[in]ackIdID to acknowledge, as given to the data reception callback.
[in]statusStatus of the acknowledge: 0 means success, other values mean error
[in]errMsgPtrOptional error message string
[in]policyPtrOptional triggering policy to send the acknowledgment, defaults to "now".
[in]persistedBoolean, if true, the ACK message will be persisted in flash by the agent, and kept even if a reboot occurs before the policy is triggered.
rc_ReturnCode_t swi_av_asset_Create ( swi_av_Asset_t **  asset,
const char *  assetIdPtr 
)

Creates and returns a new asset instance. The newly created asset is not started when returned, it can therefore neither send nor receive messages at this point. This intermediate, non-started asset allows to configure message/update handlers before any message/update is actually transferred to the asset.

See swi_av_asset_Start to start the newly created instance.

Returns
RC_OK on success
RC_NOT_AVAILABLE if the Agent cannot be accessed.
RC_BAD_PARAMETER if the supplied parameters are invalid
Parameters
[out]assetPointer to hold the newly created asset, AirVantage library is responsible for allocating the resources of this asset. User is responsible of releasing resources using swi_av_asset_Destroy.
[in]assetIdPtrString defining the assetId identifying the instance of this new asset, NULL and empty string values are forbidden. The assetId must be unique on the same device, otherwise asset starting will fail.
rc_ReturnCode_t swi_av_asset_Destroy ( swi_av_Asset_t asset)

Closes an asset instance, releasing the associated resources. Once this destructor method has been called, no more message can be sent nor received by the instance and update for this asset will be automatically rejected.

Returns
RC_OK on success
RC_BAD_FORMAT if asset parameter is invalid
Parameters
[in]assetAsset to stop
rc_ReturnCode_t swi_av_asset_PushFloat ( swi_av_Asset_t asset,
const char *  pathPtr,
const char *  policyPtr,
uint32_t  timestamp,
double  value 
)

Pushes a float value to the agent. The data are not necessarily moved forward from the agent to the server immediately: agent-to-server data transfers are managed through policies, as described in the Agent product documentation. This API is optimized for ease of use: it will internally try to reformat data in the most sensible, server-compatible way. Applications requiring a tight control over how data are structured, buffered, consolidated and reported should consider the more advanced Table API, especially it is not possible to send correlated data using this API.

String parameters can be released by user once the call has returned.

Returns
RC_OK on success
RC_NOT_AVAILABLE if the Agent cannot be accessed.
Parameters
[in]assetAsset used to send the data
[in]pathPtrDatastore path under which data will be stored relative to the asset node. Last path segment will be used as a datastore key
[in]policyPtrOptional name of the policy controlling when the data must be sent to the server. If omitted, the default policy is used.
[in]timestampOptional timestamp, in second since Unix Epoch, swi_av_timestamp_t values can be used Request automatic or no timestamp.
[in]valuefloat value to push
rc_ReturnCode_t swi_av_asset_PushInteger ( swi_av_Asset_t asset,
const char *  pathPtr,
const char *  policyPtr,
uint32_t  timestamp,
int64_t  value 
)

Pushes an integer value to the agent. The data are not necessarily moved forward from the agent to the server immediately: agent-to-server data transfers are managed through policies, as described in the Agent product documentation. This API is optimized for ease of use: it will internally try to reformat data in the most sensible, server-compatible way. Applications requiring a tight control over how data are structured, buffered, consolidated and reported should consider the more advanced Table API, especially it is not possible to send correlated data using this API.

String parameters can be released by user once the call has returned.

Returns
RC_OK on success
RC_NOT_AVAILABLE if the Agent cannot be accessed.
Parameters
[in]assetAsset used to send the data.
[in]pathPtrDatastore path under which data will be stored relative to the asset node. Last path segment will be used as a datastore key.
[in]policyPtrOptional, name of the policy controlling when the data must be sent to the server. If omitted, the default policy is used.
[in]timestampOptional timestamp, in second since Unix Epoch, swi_av_timestamp_t values can be used Request automatic or no timestamp.
[in]valueInteger value to push
rc_ReturnCode_t swi_av_asset_PushString ( swi_av_Asset_t asset,
const char *  pathPtr,
const char *  policyPtr,
uint32_t  timestamp,
const char *  valuePtr 
)

Pushes a string value to the agent. The data are not necessarily moved forward from the agent to the server immediately: agent-to-server data transfers are managed through policies, as described in the Agent product documentation. This API is optimized for ease of use: it will internally try to reformat data in the most sensible, server-compatible way. Applications requiring a tight control over how data are structured, buffered, consolidated and reported should consider the more advanced Table API, especially it is not possible to send correlated data using this API.

String parameters can be released by user once the call has returned.

Returns
RC_OK on success
RC_NOT_AVAILABLE if the Agent cannot be accessed.
Parameters
[in]assetAsset used to send the data.
[in]pathPtrDatastore path under which data will be stored relative to the asset node, Last path segment will be used as a datastore key. NULL and empty string values are forbidden.
[in]policyPtrOptional name of the policy controlling when the data must be sent to the server. If omitted, the default policy is used.
[in]timestampOptional timestamp, in second since Unix Epoch, swi_av_timestamp_t values can be used Request automatic or no timestamp.
[in]valuePtrString value to push.
rc_ReturnCode_t swi_av_asset_Start ( swi_av_Asset_t asset)

Starts a newly created asset. Allows the asset instance to send and receive messages to/from the servers.

Returns
RC_OK on success
RC_NOT_AVAILABLE if the Agent cannot be accessed.
Parameters
[in]assetAsset to start
rc_ReturnCode_t swi_av_ConnectToServer ( unsigned int  latency)

Forces a connection to the server. This connection will not flush outgoing data handled through policies, but it will poll the server for new messages addressed to assets on this gateway device.

If using SWI_AV_CX_SYNC, the connection is synchronous, i.e. once this function returns, the requested connection to the server is closed. Otherwise the connection will happen after this call returns.

Notes:

  • valid values for latency are 0 to INT_MAX.
  • 0 value means the connection will be asynchronous, but will be done as soon as possible.
Returns
RC_OK on success
RC_NOT_AVAILABLE if the Agent cannot be accessed.
Parameters
[in]latencyLatency in seconds before initiating the connection to the server, use SWI_AV_CX_SYNC to specify synchronous connection.
rc_ReturnCode_t swi_av_Destroy ( )

Destroys the AirVantage library.

Returns
RC_OK on success
rc_ReturnCode_t swi_av_Init ( )

Initializes the AirVantage library. A call to swi_av_Init is mandatory to enable AirVantage library APIs.

Returns
RC_OK on success
RC_NOT_AVAILABLE if the Agent cannot be accessed.
rc_ReturnCode_t swi_av_RegisterDataWrite ( swi_av_Asset_t asset,
swi_av_DataWriteCB  cb,
void *  userDataPtr 
)

Registers a callback to receive DataWrite notifications. The callback will be called in a new pthread.

Usage example of the datawrite callback function:

int my_datacallback(swi_av_Asset *asset, const char *path, swi_dset_Iterator* data, int ack_id, void *userData){
if(! strncmp(path, "command.setvalue", strlen("command.setvalue")) ){
int64_t cmd_value;
assert(RC_OK == swi_dset_GetIntegerByName(data, "cmd_value", &cmd_value) );
setvalue(cmd_value);
}
else{ //unknown command
printf("received data on path[%s]:\n", path);
while(RC_NOT_FOUND != swi_dset_Next(data) ){
printf("data name: [%s]\n", swi_dset_GetName(data));
//...
}
}
if(ack_id)
swi_av_Acknowledge(ack_id, 0, NULL, "now", 1);
return 0;
}
main(...){
swi_av_RegisterDataWrite(asset, my_datacallback, NULL)
}
Returns
RC_OK on success
RC_BAD_FORMAT if provided asset param is invalid
Parameters
[in]assetAsset listening to incoming data.
[in]cbCallback function to register to receive the data.
[in]userDataPtrUser data that will be given back in callback.
rc_ReturnCode_t swi_av_RegisterUpdateNotification ( swi_av_Asset_t asset,
swi_av_updateNotificationCB  cb,
void *  userDataPtr 
)

Registers the hook function to be called when the asset receives a software update request from the AirVantage services platform.

The callback will be called in a new pthread.

This feature targets applications that want to process their own update or applications that are responsible for updating another pieces of software, taking advantage of the integrated solution provided by AirVantage services.

If the application wants to have a deeper control of the whole update process, it needs to use the functionalities provided by swi_update.h.

  • There can be only one pending software update request at a time.
  • Only one hook can be registered for the whole asset
  • If no user update hook is set, the error code 472 (meaning "not supported / not implemented") will be reported to the server.
  • Any error coming from this update request means that the whole update process will be considered as failed.
  • When an update request tries to install a version that is already installed, the application should return success value. Indeed, in some cases the asset instance won't receive and report the hook's result (e.g. because of a poorly timed reboot). As a result, the update request will be sent again, and the hook should report a success immediately.
Returns
RC_OK on success
RC_BAD_FORMAT if provided asset param is invalid
Parameters
[in]assetAsset listening to update notification, can be a started or non-started asset.
[in]cbCallback function to register to receive asset update notification Giving NULL as parameter will be treated as unregister of previous callback.
[in]userDataPtrUser data that will be given back in callback
rc_ReturnCode_t swi_av_SendUpdateResult ( swi_av_Asset_t asset,
const char *  componentNamePtr,
int  updateResult 
)

Sends the result of the software update request previously received by an asset.

Returns
RC_OK on success
RC_BAD_PARAMETER when no update request is matching asset and component name, the update result is discarded.
Parameters
[in]assetAsset that was targeted by the software update request.
[in]componentNamePtrMust be the same value as the one that was given as argument to the swi_av_updateNotificationCB. As only one software update is possible for the same component at the same time, the couple asset+componentName fully identifies the software update request.
[in]updateResultResult of the update, 200 for success, any other value means error. Values from 480 to 499 are reserved for applicative error codes,so it is highly recommended to use one (or more) of those to signify an error coming from an asset update.
rc_ReturnCode_t swi_av_table_Create ( swi_av_Asset_t asset,
swi_av_Table_t **  table,
const char *  pathPtr,
size_t  numColumns,
const char **  columnNamesPtr,
const char *  policyPtr,
swi_av_Table_Storage_t  persisted,
int  purge 
)

Creates a table, the AirVantage objects handling staging database tables, to buffer, consolidate and send structured data.

String parameters can be released by user once the call has returned.

Returns
RC_OK on success
RC_NOT_AVAILABLE if the Agent cannot be accessed.
RC_BAD_FORMAT if error occurred during the payload generation (internally used to exchange data with the Agent)
Parameters
[in]assetAsset used to send the data
[out]tablePointer to hold the newly created table. AirVantage library is responsible for allocating the resources of this table, User is responsible of releasing the resources using swi_av_Table_Destroy.
[in]pathPtrDatastore path under which data will be stored relative to the asset node
[in]numColumnsNumber of columns of the table
[in]columnNamesPtrPointer to an array of strings (with numColums entries): name of each column.
[in]policyPtrName of the policy controlling when the data must be sent to the server.
[in]persistedValue which describes how the table must be persisted, STORAGE_FLASH meaning file persistence, STORAGE_RAM meaning in ram only.
[in]purgeBoolean value, indicates if existing table (if any) is recreated (true) or reused (false). Recreation means the table will be dropped and then created from scratch (so any data inside table will be lost).
rc_ReturnCode_t swi_av_table_Destroy ( swi_av_Table_t table)

Destroys table instance, releasing associated resources. Partial data not pushed yet to the agent will be lost.

Returns
RC_OK on success
RC_NOT_AVAILABLE if the Agent cannot be accessed.
RC_BAD_FORMAT if error occurred during the payload generation (internally used to exchange data with the Agent)
Parameters
[in]tablethe table to destroy
rc_ReturnCode_t swi_av_table_PushFloat ( swi_av_Table_t table,
double  value 
)

Pushes a float value in the current row of the table.

swi_av_table_Push* functions have be called in the correct order to match the table definition created in swi_av_table_Create. Until a row is complete and sent to the Agent by invoking swi_av_table_PushRow(), data is only pushed locally in the table database.

Returns
RC_OK on success
RC_OUT_OF_RANGE maximum len for the current row has been reached, the value cannot be pushed
Parameters
[in]tableTable where to push the value
[in]valueFloat to push
rc_ReturnCode_t swi_av_table_PushInteger ( swi_av_Table_t table,
int  value 
)

Pushes an integer value in the current row of the table.

swi_av_table_Push* functions have be called in the correct order to match the table definition created in swi_av_table_Create. Until a row is complete and sent to the Agent by invoking swi_av_table_PushRow(), data is only pushed locally in the table database.

Returns
RC_OK on success
RC_OUT_OF_RANGE maximum len for the current row has been reached, the value cannot be pushed
Parameters
[in]tableTable where to push the value
[in]valueInteger to push
rc_ReturnCode_t swi_av_table_PushRow ( swi_av_Table_t table)

Pushes the current row of the database to the Agent.

Once the current row has been pushed to the Agent, it is totally freed in the database, And the table is ready to received new pushed data using swi_av_table_Push*() functions.

Returns
RC_OK on success
RC_NOT_AVAILABLE if the Agent cannot be accessed.
RC_BAD_FORMAT if error occurred during the payload generation (internally used to exchange data with the Agent)
Parameters
[in]tableTable where to push the value
rc_ReturnCode_t swi_av_table_PushString ( swi_av_Table_t table,
const char *  value 
)

Pushes a string value in the current row of the table.

swi_av_table_Push* functions have be called in the correct order to match the table definition created in swi_av_table_Create. Until a row is complete and sent to the Agent by invoking swi_av_table_PushRow(), data is only pushed locally in the table database.

Returns
RC_OK on success
RC_OUT_OF_RANGE maximum len for the current row has been reached, the value cannot be pushed
Parameters
[in]tableTable where to push the value
[in]valueString to push
rc_ReturnCode_t swi_av_TriggerPolicy ( const char *  policyPtr)

Forces data attached to a given policy to be sent or consolidated immediately. This only applies to data sent using simple or advanced Data Sending APIs. Data Reception and Asset Update exchanges are not modified by this function.

A connection to the server is done only if data needs to be sent as the result to this trigger operation. Put another way, if no data is attached to the triggered policy(ies), then no connection to the server is done. See swi_av_ConnectToServer for complementary function.

For a description of how policies allow to manage data reporting from the assets to the server, see Agent product documentation.

Returns
RC_OK on success
RC_BAD_PARAMETER if the requested policy name is not found.
RC_NOT_AVAILABLE if the Agent cannot be accessed.
Parameters
[in]policyPtrName of the policy queue to be flushed. Flush all policies if policy=='*'; only flush the default policy if policy is omitted.