le_avc_interface.h File Reference

#include "legato.h"
#include "le_limit_interface.h"

Go to the source code of this file.

Macros

#define LE_AVC_APN_NAME_MAX_LEN   48
 
#define LE_AVC_APN_NAME_MAX_LEN_BYTES   49
 
#define LE_AVC_USERNAME_MAX_LEN   28
 
#define LE_AVC_USERNAME_MAX_LEN_BYTES   29
 
#define LE_AVC_PASSWORD_MAX_LEN   28
 
#define LE_AVC_PASSWORD_MAX_LEN_BYTES   29
 
#define LE_AVC_NUM_RETRY_TIMERS   8
 
#define LE_AVC_POLLING_TIMER_MAX_VAL   525600
 
#define LE_AVC_POLLING_TIMER_MIN_VAL   0
 
#define LE_AVC_RETRY_TIMER_MAX_VAL   20160
 
#define LE_AVC_RETRY_TIMER_MIN_VAL   0
 
#define LE_AVC_HTTP_STATUS_INVALID   65535
 

Typedefs

typedef void(* le_avc_DisconnectHandler_t) (void *)
 
typedef struct le_avc_StatusEventHandler * le_avc_StatusEventHandlerRef_t
 
typedef struct le_avc_SessionRequestEventHandler * le_avc_SessionRequestEventHandlerRef_t
 
typedef struct le_avc_BlockRequest * le_avc_BlockRequestRef_t
 
typedef void(* le_avc_StatusHandlerFunc_t) (le_avc_Status_t updateStatus, int32_t totalNumBytes, int32_t dloadProgress, void *contextPtr)
 
typedef void(* le_avc_SessionRequestHandlerFunc_t) (le_avc_SessionRequest_t request, void *contextPtr)
 

Enumerations

enum  le_avc_Status_t {
  LE_AVC_NO_UPDATE = 0, LE_AVC_DOWNLOAD_PENDING = 1, LE_AVC_DOWNLOAD_IN_PROGRESS = 2, LE_AVC_DOWNLOAD_COMPLETE = 3,
  LE_AVC_DOWNLOAD_FAILED = 4, LE_AVC_INSTALL_PENDING = 5, LE_AVC_INSTALL_IN_PROGRESS = 6, LE_AVC_INSTALL_COMPLETE = 7,
  LE_AVC_INSTALL_FAILED = 8, LE_AVC_UNINSTALL_PENDING = 9, LE_AVC_UNINSTALL_IN_PROGRESS = 10, LE_AVC_UNINSTALL_COMPLETE = 11,
  LE_AVC_UNINSTALL_FAILED = 12, LE_AVC_SESSION_STARTED = 13, LE_AVC_SESSION_STOPPED = 14, LE_AVC_REBOOT_PENDING = 15,
  LE_AVC_CONNECTION_PENDING = 16, LE_AVC_AUTH_STARTED = 17, LE_AVC_AUTH_FAILED = 18
}
 
enum  le_avc_UserAgreement_t {
  LE_AVC_USER_AGREEMENT_CONNECTION = 0, LE_AVC_USER_AGREEMENT_DOWNLOAD = 1, LE_AVC_USER_AGREEMENT_INSTALL = 2, LE_AVC_USER_AGREEMENT_UNINSTALL = 3,
  LE_AVC_USER_AGREEMENT_REBOOT = 4
}
 
enum  le_avc_SessionRequest_t { LE_AVC_SESSION_ACQUIRE = 0, LE_AVC_SESSION_RELEASE = 1 }
 
enum  le_avc_UpdateType_t { LE_AVC_UNKNOWN_UPDATE = 0, LE_AVC_FIRMWARE_UPDATE = 1, LE_AVC_FRAMEWORK_UPDATE = 2, LE_AVC_APPLICATION_UPDATE = 3 }
 
enum  le_avc_ErrorCode_t { LE_AVC_ERR_NONE = 0, LE_AVC_ERR_BAD_PACKAGE = 1, LE_AVC_ERR_INTERNAL = 2, LE_AVC_ERR_SECURITY_FAILURE = 3 }
 
enum  le_avc_SessionType_t { LE_AVC_BOOTSTRAP_SESSION = 0, LE_AVC_DM_SESSION = 1, LE_AVC_SESSION_INVALID = 2 }
 
enum  le_avc_CredentialStatus_t { LE_AVC_NO_CREDENTIAL_PROVISIONED = 1, LE_AVC_BS_CREDENTIAL_PROVISIONED = 2, LE_AVC_DM_CREDENTIAL_PROVISIONED = 3 }
 

Functions

void le_avc_ConnectService (void)
 
le_result_t le_avc_TryConnectService (void)
 
void le_avc_SetServerDisconnectHandler (le_avc_DisconnectHandler_t disconnectHandler, void *contextPtr)
 
void le_avc_DisconnectService (void)
 
le_avc_StatusEventHandlerRef_t le_avc_AddStatusEventHandler (le_avc_StatusHandlerFunc_t handlerPtr, void *contextPtr)
 
void le_avc_RemoveStatusEventHandler (le_avc_StatusEventHandlerRef_t handlerRef)
 
le_avc_SessionRequestEventHandlerRef_t le_avc_AddSessionRequestEventHandler (le_avc_SessionRequestHandlerFunc_t handlerPtr, void *contextPtr)
 
void le_avc_RemoveSessionRequestEventHandler (le_avc_SessionRequestEventHandlerRef_t handlerRef)
 
le_result_t le_avc_StartSession (void)
 
le_result_t le_avc_StopSession (void)
 
le_result_t le_avc_CheckRoute (void)
 
le_result_t le_avc_DeferConnect (uint32_t deferMinutes)
 
le_result_t le_avc_AcceptDownload (void)
 
le_result_t le_avc_DeferDownload (uint32_t deferMinutes)
 
le_result_t le_avc_AcceptInstall (void)
 
le_result_t le_avc_DeferInstall (uint32_t deferMinutes)
 
le_result_t le_avc_AcceptUninstall (void)
 
le_result_t le_avc_DeferUninstall (uint32_t deferMinutes)
 
le_result_t le_avc_AcceptReboot (void)
 
le_result_t le_avc_DeferReboot (uint32_t deferMinutes)
 
le_result_t le_avc_GetUpdateType (le_avc_UpdateType_t *updateTypePtr)
 
le_result_t le_avc_GetAppUpdateName (char *updateName, size_t updateNameSize)
 
le_avc_BlockRequestRef_t le_avc_BlockInstall (void)
 
void le_avc_UnblockInstall (le_avc_BlockRequestRef_t blockRef)
 
le_avc_ErrorCode_t le_avc_GetErrorCode (void)
 
le_avc_SessionType_t le_avc_GetSessionType (void)
 
uint16_t le_avc_GetHttpStatus (void)
 
le_result_t le_avc_GetPollingTimer (uint32_t *pollingTimerPtr)
 
le_result_t le_avc_GetRetryTimers (uint16_t *timerValuePtr, size_t *timerValueSizePtr)
 
le_result_t le_avc_GetApnConfig (char *apnName, size_t apnNameSize, char *userName, size_t userNameSize, char *userPwd, size_t userPwdSize)
 
le_result_t le_avc_SetApnConfig (const char *LE_NONNULL apnName, const char *LE_NONNULL userName, const char *LE_NONNULL userPwd)
 
le_result_t le_avc_SetPollingTimer (uint32_t pollingTimer)
 
le_result_t le_avc_SetRetryTimers (const uint16_t *timerValuePtr, size_t timerValueSize)
 
le_avc_CredentialStatus_t le_avc_GetCredentialStatus (void)
 
le_result_t le_avc_SetUserAgreement (le_avc_UserAgreement_t updateStatus, bool enable)
 
le_result_t le_avc_GetUserAgreement (le_avc_UserAgreement_t updateStatus, bool *enablePtr)
 

Detailed Description

Legato AirVantage Connector API include file.

Macro Definition Documentation

#define LE_AVC_APN_NAME_MAX_LEN   48

Maximum APN name length without NULL terminator.

#define LE_AVC_APN_NAME_MAX_LEN_BYTES   49

Maximum APN name length including NULL terminator.

#define LE_AVC_HTTP_STATUS_INVALID   65535

Default HTTP status.

#define LE_AVC_NUM_RETRY_TIMERS   8

Maximum number of retry timers.

#define LE_AVC_PASSWORD_MAX_LEN   28

Maximum password length without NULL terminator..

#define LE_AVC_PASSWORD_MAX_LEN_BYTES   29

Maximum password length including NULL terminator.

#define LE_AVC_POLLING_TIMER_MAX_VAL   525600

Polling timer value range in minutes. 525600 minutes = 1 year.

#define LE_AVC_RETRY_TIMER_MAX_VAL   20160

Retry timer value range in minutes. 20160 minutes = 2 weeks.

#define LE_AVC_USERNAME_MAX_LEN   28

Maximum user name length without NULL terminator.

#define LE_AVC_USERNAME_MAX_LEN_BYTES   29

Maximum user name length including NULL terminator.

Typedef Documentation

typedef struct le_avc_BlockRequest* le_avc_BlockRequestRef_t

Reference returned by BlockInstall function and used by UnblockInstall function

typedef void(* le_avc_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

typedef struct le_avc_SessionRequestEventHandler* le_avc_SessionRequestEventHandlerRef_t

Reference type used by Add/Remove functions for EVENT 'le_avc_SessionRequestEvent'

typedef void(* le_avc_SessionRequestHandlerFunc_t) (le_avc_SessionRequest_t request,void *contextPtr)

Handler for receiving session open or close request.

typedef struct le_avc_StatusEventHandler* le_avc_StatusEventHandlerRef_t

Reference type used by Add/Remove functions for EVENT 'le_avc_StatusEvent'

typedef void(* le_avc_StatusHandlerFunc_t) (le_avc_Status_t updateStatus,int32_t totalNumBytes,int32_t dloadProgress,void *contextPtr)

Handler for update availability status

Enumeration Type Documentation

Status of the device credentials

Enumerator
LE_AVC_NO_CREDENTIAL_PROVISIONED 

Neither Bootstrap nor Device Management credential is provisioned.

LE_AVC_BS_CREDENTIAL_PROVISIONED 

Bootstrap credential is provisioned but Device Management credential is not provisioned.

LE_AVC_DM_CREDENTIAL_PROVISIONED 

Device Management credential is provisioned.

Error code used to provide diagnostic information after a failure (includes both download and install failure).

Note
Additional information may also be available in the target device's system log.
Enumerator
LE_AVC_ERR_NONE 

No error.

LE_AVC_ERR_BAD_PACKAGE 

Encountered a bad package.

LE_AVC_ERR_INTERNAL 

Something failed while doing install/download.

LE_AVC_ERR_SECURITY_FAILURE 

Security check failure while installing the package.

Request to open or close avms session.

Enumerator
LE_AVC_SESSION_ACQUIRE 

Request by user app to open AV session.

LE_AVC_SESSION_RELEASE 

Request by user app to close AV session.

Session type indicates whether the device is connected to the bootstrap server or the device management server.

Enumerator
LE_AVC_BOOTSTRAP_SESSION 

Bootstrap session.

LE_AVC_DM_SESSION 

Device Management session.

LE_AVC_SESSION_INVALID 

Session type invalid.

Status of session or update

If an update is pending, it must first be downloaded and then installed.

Enumerator
LE_AVC_NO_UPDATE 

No updates pending.

LE_AVC_DOWNLOAD_PENDING 

Update pending download.

LE_AVC_DOWNLOAD_IN_PROGRESS 

Download in progress.

LE_AVC_DOWNLOAD_COMPLETE 

Download has completed.

LE_AVC_DOWNLOAD_FAILED 

An error occurred downloading the update.

LE_AVC_INSTALL_PENDING 

Install is pending (implies download complete)

LE_AVC_INSTALL_IN_PROGRESS 

Install in progress.

LE_AVC_INSTALL_COMPLETE 

Update has been successfully installed.

LE_AVC_INSTALL_FAILED 

An error occurred installing the update.

LE_AVC_UNINSTALL_PENDING 

Uninstall is pending.

LE_AVC_UNINSTALL_IN_PROGRESS 

Uninstall in progress.

LE_AVC_UNINSTALL_COMPLETE 

App has been successfully uninstalled.

LE_AVC_UNINSTALL_FAILED 

An error occurred uninstalling the update.

LE_AVC_SESSION_STARTED 

Session with AV server started.

LE_AVC_SESSION_STOPPED 

Session with AV server stopped.

LE_AVC_REBOOT_PENDING 

Device reboot is pending.

LE_AVC_CONNECTION_PENDING 

Connection to the server is required. This is necessary when firmware package is installed (after a platform reboot). Also necessary after software update if device reboots(or session stops) in the middle of software update.

LE_AVC_AUTH_STARTED 

Authentication with AV server started.

LE_AVC_AUTH_FAILED 

Authentication with AV server failed.

The type of pending update

Operations which require user agreement

Enumerator
LE_AVC_USER_AGREEMENT_CONNECTION 

User agreement for connection.

LE_AVC_USER_AGREEMENT_DOWNLOAD 

User agreement for download.

LE_AVC_USER_AGREEMENT_INSTALL 

User agreement for install.

LE_AVC_USER_AGREEMENT_UNINSTALL 

User agreement for uninstall.

LE_AVC_USER_AGREEMENT_REBOOT 

User agreement for reboot.

Function Documentation

le_result_t le_avc_AcceptDownload ( void  )

Accept the currently pending download

Returns
  • LE_OK on success
  • LE_FAULT on failure
le_result_t le_avc_AcceptInstall ( void  )

Accept the currently pending install

Returns
  • LE_OK on success
  • LE_FAULT on failure
le_result_t le_avc_AcceptReboot ( void  )

Accept the currently pending reboot

Returns
  • LE_OK on success
  • LE_FAULT on failure
le_result_t le_avc_AcceptUninstall ( void  )

Accept the currently pending uninstall

Returns
  • LE_OK on success
  • LE_FAULT on failure
le_avc_SessionRequestEventHandlerRef_t le_avc_AddSessionRequestEventHandler ( le_avc_SessionRequestHandlerFunc_t  handlerPtr,
void *  contextPtr 
)

Add handler function for EVENT 'le_avc_SessionRequestEvent'

This event provides information on session open or close request.

Parameters
[in]handlerPtr
[in]contextPtr
le_avc_StatusEventHandlerRef_t le_avc_AddStatusEventHandler ( le_avc_StatusHandlerFunc_t  handlerPtr,
void *  contextPtr 
)

Add handler function for EVENT 'le_avc_StatusEvent'

This event provides information on update availability status

Parameters
[in]handlerPtr
[in]contextPtr
le_avc_BlockRequestRef_t le_avc_BlockInstall ( void  )

Prevent any pending updates from being installed.

Returns
  • Reference for block update request (to be used later for unblocking updates)
  • NULL if the operation was not successful
le_result_t le_avc_CheckRoute ( void  )

Send a specific message to the server to be sure that the route between the device and the server is available. This API needs to be called when any package download is over (successfully or not) and before sending any notification on asset data to the server.

Returns
  • LE_OK when the treatment is launched
  • LE_FAULT on failure
  • LE_UNSUPPORTED when the API is not supported
void le_avc_ConnectService ( void  )

Connect the current client thread to the service providing this API. Block until the service is available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

le_result_t le_avc_DeferConnect ( uint32_t  deferMinutes)

Defer the currently pending connection, for the given number of minutes

Returns
  • LE_OK on success
  • LE_FAULT on failure
Parameters
[in]deferMinutes
le_result_t le_avc_DeferDownload ( uint32_t  deferMinutes)

Defer the currently pending download, for the given number of minutes

Returns
  • LE_OK on success
  • LE_FAULT on failure
Parameters
[in]deferMinutes
le_result_t le_avc_DeferInstall ( uint32_t  deferMinutes)

Defer the currently pending install

Returns
  • LE_OK on success
  • LE_FAULT on failure
Parameters
[in]deferMinutes
le_result_t le_avc_DeferReboot ( uint32_t  deferMinutes)

Defer the currently pending reboot

Returns
  • LE_OK on success
  • LE_FAULT on failure
Parameters
[in]deferMinutes
le_result_t le_avc_DeferUninstall ( uint32_t  deferMinutes)

Defer the currently pending uninstall

Returns
  • LE_OK on success
  • LE_FAULT on failure
Parameters
[in]deferMinutes
void le_avc_DisconnectService ( void  )

Disconnect the current client thread from the service providing this API.

Normally, this function doesn't need to be called. After this function is called, there's no longer a connection to the service, and the functions in this API can't be used. For details, see Client-specific Functions.

This function is created automatically.

le_result_t le_avc_GetApnConfig ( char *  apnName,
size_t  apnNameSize,
char *  userName,
size_t  userNameSize,
char *  userPwd,
size_t  userPwdSize 
)

Function to read APN configuration.

Returns
  • LE_OK on success.
  • LE_FAULT if there is any error while reading.
  • LE_OVERFLOW if the buffer provided is too small.
Parameters
[out]apnName
[in]apnNameSize
[out]userName
[in]userNameSize
[out]userPwd
[in]userPwdSize
le_result_t le_avc_GetAppUpdateName ( char *  updateName,
size_t  updateNameSize 
)

Get the name for the currently pending app update

Returns
  • LE_OK on success
  • LE_FAULT if not available, or isn't APPL_UPDATE type
Parameters
[out]updateName
[in]updateNameSize
le_avc_CredentialStatus_t le_avc_GetCredentialStatus ( void  )

Function to retrieve status of the credentials provisioned on the device.

Returns
LE_AVC_NO_CREDENTIAL_PROVISIONED
  • If neither Bootstrap nor Device Management credential is provisioned. LE_AVC_BS_CREDENTIAL_PROVISIONED
  • If Bootstrap credential is provisioned but Device Management credential is not provisioned. LE_AVC_DM_CREDENTIAL_PROVISIONED
  • If Device management key is provisioned.
le_avc_ErrorCode_t le_avc_GetErrorCode ( void  )

Function to get error code when update fails.

Returns
  • Error code of encountered error.
  • ERR_NONE if update is in any other state.
uint16_t le_avc_GetHttpStatus ( void  )

Function to read the http status of the last download.

Returns
  • HttpStatus as defined in RFC 7231, Section 6.
le_result_t le_avc_GetPollingTimer ( uint32_t *  pollingTimerPtr)

Function to read the polling timer.

Returns
  • LE_OK on success
  • LE_FAULT if not available
  • LE_OUT_OF_RANGE if the polling timer value is out of range (0 to 525600).
Parameters
[out]pollingTimerPtrPolling timer
le_result_t le_avc_GetRetryTimers ( uint16_t *  timerValuePtr,
size_t *  timerValueSizePtr 
)

Function to read the retry timers.

Returns
  • LE_OK on success.
  • LE_FAULT if not able to read the timers.
  • LE_OUT_OF_RANGE if one of the retry timers is out of range (0 to 20160).
Parameters
[out]timerValuePtrArray of the retry timers.
[in,out]timerValueSizePtr
le_avc_SessionType_t le_avc_GetSessionType ( void  )

Function to read the current session type, or the last session type if there is no active session.

Returns
  • SessionType
le_result_t le_avc_GetUpdateType ( le_avc_UpdateType_t updateTypePtr)

Get the update type of the currently pending update

Returns
  • LE_OK on success
  • LE_FAULT if not available
Parameters
[out]updateTypePtr
le_result_t le_avc_GetUserAgreement ( le_avc_UserAgreement_t  updateStatus,
bool *  enablePtr 
)

Function to get user agreements for download, install, reboot, connection and uninstall.

Returns
  • LE_OK on success.
  • LE_FAULT if failed to read user agreement state.
Parameters
[in]updateStatusOperation for which user agreements has to be read.
[out]enablePtrtrue = enable, false = disable.
void le_avc_RemoveSessionRequestEventHandler ( le_avc_SessionRequestEventHandlerRef_t  handlerRef)

Remove handler function for EVENT 'le_avc_SessionRequestEvent'

Parameters
[in]handlerRef
void le_avc_RemoveStatusEventHandler ( le_avc_StatusEventHandlerRef_t  handlerRef)

Remove handler function for EVENT 'le_avc_StatusEvent'

Parameters
[in]handlerRef
le_result_t le_avc_SetApnConfig ( const char *LE_NONNULL  apnName,
const char *LE_NONNULL  userName,
const char *LE_NONNULL  userPwd 
)

Function to write APN configuration.

Returns
  • LE_OK on success.
  • LE_OVERFLOW if one of the input strings is too long.
Parameters
[in]apnName
[in]userName
[in]userPwd
le_result_t le_avc_SetPollingTimer ( uint32_t  pollingTimer)

Function to set the polling timer.

Returns
  • LE_OK on success.
  • LE_OUT_OF_RANGE if the polling timer value is out of range (0 to 525600).
Parameters
[in]pollingTimerPolling timer
le_result_t le_avc_SetRetryTimers ( const uint16_t *  timerValuePtr,
size_t  timerValueSize 
)

Function to set the retry timers.

Returns
  • LE_OK on success.
  • LE_FAULT if not able to set the timers.
  • LE_OUT_OF_RANGE if one of the retry timers is out of range (0 to 20160).
Parameters
[in]timerValuePtrArray of 8 retry timers.
[in]timerValueSize
void le_avc_SetServerDisconnectHandler ( le_avc_DisconnectHandler_t  disconnectHandler,
void *  contextPtr 
)

Set handler called when server disconnection is detected.

When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants to continue without exiting, it should call longjmp() from inside the handler.

le_result_t le_avc_SetUserAgreement ( le_avc_UserAgreement_t  updateStatus,
bool  enable 
)

Function to set user agreements for download, install, reboot, connection and uninstall.

Returns
  • LE_OK on success.
  • LE_FAULT if failed to configure user agreement.
Parameters
[in]updateStatusOperation for which user agreements has to be set.
[in]enabletrue = enable, false = disable.
le_result_t le_avc_StartSession ( void  )

Start a session with the AirVantage server

This will cause a query to be sent to the server, for pending updates.

Returns
  • LE_OK if connection request has been sent.
  • LE_FAULT on failure
  • LE_DUPLICATE if already connected.
le_result_t le_avc_StopSession ( void  )

Stop a session with the AirVantage server

If a download is in progress, then this suspends the download.

Returns
  • LE_OK on success
  • LE_FAULT on failure
le_result_t le_avc_TryConnectService ( void  )

Try to connect the current client thread to the service providing this API. Return with an error if the service is not available.

For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.

This function is created automatically.

Returns
  • LE_OK if the client connected successfully to the service.
  • LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  • LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  • LE_COMM_ERROR if the Service Directory cannot be reached.
void le_avc_UnblockInstall ( le_avc_BlockRequestRef_t  blockRef)

Allow any pending updates to be installed

Parameters
[in]blockRefblock request ref returned by le_avc_BlockInstall