#include <stdlib.h>
#include "returncodes.h"
#include "swi_dset.h"

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

enum swi_av_Table_Storage_t

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.

enum swi_av_timestamp_t

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]	ackId	ID to acknowledge, as given to the data reception callback.
[in]	status	Status of the acknowledge: 0 means success, other values mean error
[in]	errMsgPtr	Optional error message string
[in]	policyPtr	Optional triggering policy to send the acknowledgment, defaults to "now".
[in]	persisted	Boolean, 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]	asset	Pointer 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]	assetIdPtr	String 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] asset Asset 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]	asset	Asset used to send the data
[in]	pathPtr	Datastore path under which data will be stored relative to the asset node. Last path segment will be used as a datastore key
[in]	policyPtr	Optional name of the policy controlling when the data must be sent to the server. If omitted, the default policy is used.
[in]	timestamp	Optional timestamp, in second since Unix Epoch, swi_av_timestamp_t values can be used Request automatic or no timestamp.
[in]	value	float 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]	asset	Asset used to send the data.
[in]	pathPtr	Datastore path under which data will be stored relative to the asset node. Last path segment will be used as a datastore key.
[in]	policyPtr	Optional, name of the policy controlling when the data must be sent to the server. If omitted, the default policy is used.
[in]	timestamp	Optional timestamp, in second since Unix Epoch, swi_av_timestamp_t values can be used Request automatic or no timestamp.
[in]	value	Integer 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]	asset	Asset used to send the data.
[in]	pathPtr	Datastore 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]	policyPtr	Optional name of the policy controlling when the data must be sent to the server. If omitted, the default policy is used.
[in]	timestamp	Optional timestamp, in second since Unix Epoch, swi_av_timestamp_t values can be used Request automatic or no timestamp.
[in]	valuePtr	String 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] asset Asset 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] latency Latency 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]	asset	Asset listening to incoming data.
[in]	cb	Callback function to register to receive the data.
[in]	userDataPtr	User 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]	asset	Asset listening to update notification, can be a started or non-started asset.
[in]	cb	Callback function to register to receive asset update notification Giving NULL as parameter will be treated as unregister of previous callback.
[in]	userDataPtr	User 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]	asset	Asset that was targeted by the software update request.
[in]	componentNamePtr	Must 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]	updateResult	Result 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]	asset	Asset used to send the data
[out]	table	Pointer 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]	pathPtr	Datastore path under which data will be stored relative to the asset node
[in]	numColumns	Number of columns of the table
[in]	columnNamesPtr	Pointer to an array of strings (with numColums entries): name of each column.
[in]	policyPtr	Name of the policy controlling when the data must be sent to the server.
[in]	persisted	Value which describes how the table must be persisted, STORAGE_FLASH meaning file persistence, STORAGE_RAM meaning in ram only.
[in]	purge	Boolean 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] table the 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]	table	Table where to push the value
[in]	value	Float 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]	table	Table where to push the value
[in]	value	Integer 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] table Table 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]	table	Table where to push the value
[in]	value	String 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] policyPtr Name of the policy queue to be flushed. Flush all policies if policy=='*'; only flush the default policy if policy is omitted.

General functionalities.

Data Sending Simple API

Data Sending Advanced API

Data Reception

Asset Update

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation