Macros | Typedefs | Enumerations | Functions

le_avdata_interface.h File Reference

#include "legato.h"

Go to the source code of this file.

Macros

#define LE_AVDATA_PATH_NAME_LEN   511
 
#define LE_AVDATA_PATH_NAME_BYTES   512
 
#define LE_AVDATA_STRING_VALUE_LEN   255
 
#define LE_AVDATA_STRING_VALUE_BYTES   256
 

Typedefs

typedef void(* le_avdata_DisconnectHandler_t) (void *)
 
typedef struct le_avdata_ArgumentList * le_avdata_ArgumentListRef_t
 
typedef struct le_avdata_ResourceEventHandler * le_avdata_ResourceEventHandlerRef_t
 
typedef struct le_avdata_Record * le_avdata_RecordRef_t
 
typedef struct le_avdata_RequestSessionObj * le_avdata_RequestSessionObjRef_t
 
typedef struct le_avdata_SessionStateHandler * le_avdata_SessionStateHandlerRef_t
 
typedef void(* le_avdata_ResourceHandlerFunc_t) (const char *LE_NONNULL path, le_avdata_AccessType_t accessType, le_avdata_ArgumentListRef_t argumentListRef, void *contextPtr)
 
typedef void(* le_avdata_CallbackResultFunc_t) (le_avdata_PushStatus_t status, void *contextPtr)
 
typedef void(* le_avdata_SessionStateHandlerFunc_t) (le_avdata_SessionState_t sessionState, void *contextPtr)
 

Enumerations

enum  le_avdata_AccessMode_t { LE_AVDATA_ACCESS_VARIABLE = 0, LE_AVDATA_ACCESS_SETTING = 1, LE_AVDATA_ACCESS_COMMAND = 2 }
 
enum  le_avdata_AccessType_t { LE_AVDATA_ACCESS_READ = 0x1, LE_AVDATA_ACCESS_WRITE = 0x2, LE_AVDATA_ACCESS_EXEC = 0x4 }
 
enum  le_avdata_DataType_t {
  LE_AVDATA_DATA_TYPE_NONE = 0, LE_AVDATA_DATA_TYPE_INT = 1, LE_AVDATA_DATA_TYPE_FLOAT = 2, LE_AVDATA_DATA_TYPE_BOOL = 3,
  LE_AVDATA_DATA_TYPE_STRING = 4
}
 
enum  le_avdata_PushStatus_t { LE_AVDATA_PUSH_SUCCESS = 0, LE_AVDATA_PUSH_FAILED = 1 }
 
enum  le_avdata_SessionState_t { LE_AVDATA_SESSION_STARTED = 0, LE_AVDATA_SESSION_STOPPED = 1 }
 

Functions

void le_avdata_ConnectService (void)
 
le_result_t le_avdata_TryConnectService (void)
 
void le_avdata_SetServerDisconnectHandler (le_avdata_DisconnectHandler_t disconnectHandler, void *contextPtr)
 
void le_avdata_DisconnectService (void)
 
le_avdata_ResourceEventHandlerRef_t le_avdata_AddResourceEventHandler (const char *LE_NONNULL path, le_avdata_ResourceHandlerFunc_t handlerPtr, void *contextPtr)
 
void le_avdata_RemoveResourceEventHandler (le_avdata_ResourceEventHandlerRef_t handlerRef)
 
le_result_t le_avdata_CreateResource (const char *LE_NONNULL path, le_avdata_AccessMode_t accessMode)
 
le_result_t le_avdata_SetNull (const char *LE_NONNULL path)
 
le_result_t le_avdata_GetInt (const char *LE_NONNULL path, int32_t *valuePtr)
 
le_result_t le_avdata_SetInt (const char *LE_NONNULL path, int32_t value)
 
le_result_t le_avdata_GetFloat (const char *LE_NONNULL path, double *valuePtr)
 
le_result_t le_avdata_SetFloat (const char *LE_NONNULL path, double value)
 
le_result_t le_avdata_GetBool (const char *LE_NONNULL path, bool *valuePtr)
 
le_result_t le_avdata_SetBool (const char *LE_NONNULL path, bool value)
 
le_result_t le_avdata_GetString (const char *LE_NONNULL path, char *value, size_t valueSize)
 
le_result_t le_avdata_SetString (const char *LE_NONNULL path, const char *LE_NONNULL value)
 
le_result_t le_avdata_GetBoolArg (le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, bool *boolArgPtr)
 
le_result_t le_avdata_GetFloatArg (le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, double *floatArgPtr)
 
le_result_t le_avdata_GetIntArg (le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, int32_t *intArgPtr)
 
le_result_t le_avdata_GetStringArg (le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, char *strArg, size_t strArgSize)
 
le_result_t le_avdata_GetStringArgLength (le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, int32_t *strArgLenPtr)
 
void le_avdata_ReplyExecResult (le_avdata_ArgumentListRef_t argumentListRef, le_result_t result)
 
le_result_t le_avdata_Push (const char *LE_NONNULL path, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
 
le_result_t le_avdata_PushStream (const char *LE_NONNULL path, int fd, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
 
le_avdata_RecordRef_t le_avdata_CreateRecord (void)
 
void le_avdata_DeleteRecord (le_avdata_RecordRef_t recordRef)
 
le_result_t le_avdata_RecordInt (le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, int32_t value, uint64_t timestamp)
 
le_result_t le_avdata_RecordFloat (le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, double value, uint64_t timestamp)
 
le_result_t le_avdata_RecordBool (le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, bool value, uint64_t timestamp)
 
le_result_t le_avdata_RecordString (le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, const char *LE_NONNULL value, uint64_t timestamp)
 
le_result_t le_avdata_PushRecord (le_avdata_RecordRef_t recordRef, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
 
le_avdata_SessionStateHandlerRef_t le_avdata_AddSessionStateHandler (le_avdata_SessionStateHandlerFunc_t handlerPtr, void *contextPtr)
 
void le_avdata_RemoveSessionStateHandler (le_avdata_SessionStateHandlerRef_t handlerRef)
 
le_avdata_RequestSessionObjRef_t le_avdata_RequestSession (void)
 
void le_avdata_ReleaseSession (le_avdata_RequestSessionObjRef_t requestRef)
 

Detailed Description

Legato AirVantage Data API include file.

Copyright (C) Sierra Wireless Inc.

Macro Definition Documentation

#define LE_AVDATA_PATH_NAME_LEN   511

Define the maximum characters and bytes of a path name

#define LE_AVDATA_STRING_VALUE_LEN   255

Define the maximum characters and bytes of a string

Typedef Documentation

typedef struct le_avdata_ArgumentList* le_avdata_ArgumentListRef_t

Argument list reference, for command only.

typedef void(* le_avdata_CallbackResultFunc_t) (le_avdata_PushStatus_t status,void *contextPtr)

Handler for pushing data result.

typedef void(* le_avdata_DisconnectHandler_t) (void *)

Type for handler called when a server disconnects.

typedef struct le_avdata_Record* le_avdata_RecordRef_t

A record reference

typedef struct le_avdata_RequestSessionObj* le_avdata_RequestSessionObjRef_t

Reference returned by RequestSession function and used by ReleaseSession function

typedef struct le_avdata_ResourceEventHandler* le_avdata_ResourceEventHandlerRef_t

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

typedef void(* le_avdata_ResourceHandlerFunc_t) (const char *LE_NONNULL path,le_avdata_AccessType_t accessType,le_avdata_ArgumentListRef_t argumentListRef,void *contextPtr)

Handler for resource activity

typedef void(* le_avdata_SessionStateHandlerFunc_t) (le_avdata_SessionState_t sessionState,void *contextPtr)

Handler for AV session changes

typedef struct le_avdata_SessionStateHandler* le_avdata_SessionStateHandlerRef_t

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

Enumeration Type Documentation

enum le_avdata_AccessMode_t

Resource access modes. Variable: read (server), read/write (client) Setting: read/write (server), read (client) Command: execute (server)

enum le_avdata_AccessType_t

Resource access types

enum le_avdata_DataType_t

Data types

enum le_avdata_PushStatus_t

Status of the data push (TODO: Provide additional status to troubleshoot delivery problems)

enum le_avdata_SessionState_t

AVMS session state

Enumerator
LE_AVDATA_SESSION_STARTED 

AVMS session started.

LE_AVDATA_SESSION_STOPPED 

AVMS session stopped.

Function Documentation

le_avdata_ResourceEventHandlerRef_t le_avdata_AddResourceEventHandler ( const char *LE_NONNULL  path,
le_avdata_ResourceHandlerFunc_t  handlerPtr,
void *  contextPtr 
)

Add handler function for EVENT 'le_avdata_ResourceEvent'

Upon resource access on the server side, the registered handler is called.

For "settings" (read/write), the same handler is called for both read and write access.

For "commands", the handler function must call the "ReplyExecResult" function to send the command execution result back to the AVC daemon (which then sends the proper response back to the AV server).

Parameters
[in]path
[in]handlerPtr
[in]contextPtr
le_avdata_SessionStateHandlerRef_t le_avdata_AddSessionStateHandler ( le_avdata_SessionStateHandlerFunc_t  handlerPtr,
void *  contextPtr 
)

Add handler function for EVENT 'le_avdata_SessionState'

This event provides information on AV session state changes

Parameters
[in]handlerPtr
[in]contextPtr
void le_avdata_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_avdata_RecordRef_t le_avdata_CreateRecord ( void  )

Create a timeseries record

Returns
Reference to the record
le_result_t le_avdata_CreateResource ( const char *LE_NONNULL  path,
le_avdata_AccessMode_t  accessMode 
)

Create an asset data with the provided path. Note that asset data type and value are determined upon the first call to a Set function. When an asset data is created, it contains a null value, represented by the data type of none.

Returns
:
  • LE_OK on success
  • LE_DUPLICATE if path has already been called by CreateResource before, or path is parent or child to an existing Asset Data path.
  • LE_FAULT on any other error.
Parameters
[in]path
[in]accessMode
void le_avdata_DeleteRecord ( le_avdata_RecordRef_t  recordRef)

Delete a timeseries record

Parameters
[in]recordRef
void le_avdata_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_avdata_GetBool ( const char *LE_NONNULL  path,
bool *  valuePtr 
)

Gets the bool value of an asset data.

Returns
:
  • LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
  • LE_UNAVAILABLE - asset data contains null value
  • LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  • LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  • LE_OK - access successful.
Parameters
[in]path
[out]valuePtr
le_result_t le_avdata_GetBoolArg ( le_avdata_ArgumentListRef_t  argumentListRef,
const char *LE_NONNULL  argName,
bool *  boolArgPtr 
)

Get the bool argument with the specified name.

Returns
:
  • LE_OK on success
  • LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
Parameters
[in]argumentListRef
[in]argName
[out]boolArgPtr
le_result_t le_avdata_GetFloat ( const char *LE_NONNULL  path,
double *  valuePtr 
)

Gets the float value of an asset data.

Returns
:
  • LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
  • LE_UNAVAILABLE - asset data contains null value
  • LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  • LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  • LE_OK - access successful.
Parameters
[in]path
[out]valuePtr
le_result_t le_avdata_GetFloatArg ( le_avdata_ArgumentListRef_t  argumentListRef,
const char *LE_NONNULL  argName,
double *  floatArgPtr 
)

Get the float argument with the specified name.

Returns
:
  • LE_OK on success
  • LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
Parameters
[in]argumentListRef
[in]argName
[out]floatArgPtr
le_result_t le_avdata_GetInt ( const char *LE_NONNULL  path,
int32_t *  valuePtr 
)

Gets the integer value of an asset data.

Returns
:
  • LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
  • LE_UNAVAILABLE - asset data contains null value
  • LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  • LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  • LE_OK - access successful.
Parameters
[in]path
[out]valuePtr
le_result_t le_avdata_GetIntArg ( le_avdata_ArgumentListRef_t  argumentListRef,
const char *LE_NONNULL  argName,
int32_t *  intArgPtr 
)

Get the int argument with the specified name.

Returns
:
  • LE_OK on success
  • LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
Parameters
[in]argumentListRef
[in]argName
[out]intArgPtr
le_result_t le_avdata_GetString ( const char *LE_NONNULL  path,
char *  value,
size_t  valueSize 
)

Gets the string value of an asset data.

Returns
:
  • LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
  • LE_UNAVAILABLE - asset data contains null value
  • LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  • LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  • LE_OK - access successful.
Parameters
[in]path
[out]value
[in]valueSize
le_result_t le_avdata_GetStringArg ( le_avdata_ArgumentListRef_t  argumentListRef,
const char *LE_NONNULL  argName,
char *  strArg,
size_t  strArgSize 
)

Get the string argument with the specified name.

Returns
:
  • LE_OK on success
  • LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
Parameters
[in]argumentListRef
[in]argName
[out]strArg
[in]strArgSize
le_result_t le_avdata_GetStringArgLength ( le_avdata_ArgumentListRef_t  argumentListRef,
const char *LE_NONNULL  argName,
int32_t *  strArgLenPtr 
)

Get the length (excluding terminating null byte) of the string argument of the specified name.

Returns
:
  • LE_OK on success
  • LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
Parameters
[in]argumentListRef
[in]argName
[out]strArgLenPtr
le_result_t le_avdata_Push ( const char *LE_NONNULL  path,
le_avdata_CallbackResultFunc_t  handlerPtr,
void *  contextPtr 
)

Push asset data to the server.

Returns
:
  • LE_OK on success.
  • LE_NOT_FOUND if path doesn't exist.
  • LE_BUSY if push is queued and will pushed later automatically
  • LE_NOT_POSSIBLE if push queue is full, try again later
  • LE_FAULT on any other error
Parameters
[in]path
[in]handlerPtr
[in]contextPtr
le_result_t le_avdata_PushRecord ( le_avdata_RecordRef_t  recordRef,
le_avdata_CallbackResultFunc_t  handlerPtr,
void *  contextPtr 
)

Push record to the server

Returns
:
  • LE_OK on success.
  • LE_BUSY if push is queued and will pushed later automatically
  • LE_NOT_POSSIBLE if push queue is full, try again later
  • LE_FAULT on any other error
  • Note
    If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]recordRef
[in]handlerPtr
[in]contextPtr
le_result_t le_avdata_PushStream ( const char *LE_NONNULL  path,
int  fd,
le_avdata_CallbackResultFunc_t  handlerPtr,
void *  contextPtr 
)

Push data dump to a specified path on the server.

Returns
:
  • LE_OK on success.
  • LE_NOT_POSSIBLE if the service is busy pushing other data, try again later
  • LE_FAULT on any other error
Parameters
[in]path
[in]fd
[in]handlerPtr
[in]contextPtr
le_result_t le_avdata_RecordBool ( le_avdata_RecordRef_t  recordRef,
const char *LE_NONNULL  path,
bool  value,
uint64_t  timestamp 
)

Accumulate boolean data

Note
The client will be terminated if the recordRef is not valid, or the resource doesn't exist
Returns
:
  • LE_OK on success
  • LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  • LE_FAULT on any other error
Parameters
[in]recordRef
[in]path
[in]value
[in]timestamp
le_result_t le_avdata_RecordFloat ( le_avdata_RecordRef_t  recordRef,
const char *LE_NONNULL  path,
double  value,
uint64_t  timestamp 
)

Accumulate float data

Note
The client will be terminated if the recordRef is not valid, or the resource doesn't exist
Returns
:
  • LE_OK on success
  • LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  • LE_FAULT on any other error
Parameters
[in]recordRef
[in]path
[in]value
[in]timestamp
le_result_t le_avdata_RecordInt ( le_avdata_RecordRef_t  recordRef,
const char *LE_NONNULL  path,
int32_t  value,
uint64_t  timestamp 
)

Accumulate int data

Note
The client will be terminated if the recordRef is not valid, or the resource doesn't exist
Returns
:
  • LE_OK on success
  • LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  • LE_FAULT on any other error
Parameters
[in]recordRef
[in]path
[in]value
[in]timestamp
le_result_t le_avdata_RecordString ( le_avdata_RecordRef_t  recordRef,
const char *LE_NONNULL  path,
const char *LE_NONNULL  value,
uint64_t  timestamp 
)

Accumulate string data

Note
The client will be terminated if the recordRef is not valid, or the resource doesn't exist
Returns
:
  • LE_OK on success
  • LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  • LE_FAULT on any other error
Parameters
[in]recordRef
[in]path
[in]value
[in]timestamp
void le_avdata_ReleaseSession ( le_avdata_RequestSessionObjRef_t  requestRef)

Request the avcServer to close a session.

Parameters
[in]requestRefReference to a previously opened AV session.
void le_avdata_RemoveResourceEventHandler ( le_avdata_ResourceEventHandlerRef_t  handlerRef)

Remove handler function for EVENT 'le_avdata_ResourceEvent'

Parameters
[in]handlerRef
void le_avdata_RemoveSessionStateHandler ( le_avdata_SessionStateHandlerRef_t  handlerRef)

Remove handler function for EVENT 'le_avdata_SessionState'

Parameters
[in]handlerRef
void le_avdata_ReplyExecResult ( le_avdata_ArgumentListRef_t  argumentListRef,
le_result_t  result 
)

Reply command execution result to AVC Daemon, which can then respond to AV server. This function MUST be called at the end of a command execution, in order for AV server to be notified about the execution status.

Parameters
[in]argumentListRef
[in]result
le_avdata_RequestSessionObjRef_t le_avdata_RequestSession ( void  )

Request the avcServer to open a session.

Returns
  • SessionRef if session request succeeded
  • NULL if session request failed
le_result_t le_avdata_SetBool ( const char *LE_NONNULL  path,
bool  value 
)

Sets an asset data to a bool value.

Returns
:
  • LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  • LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  • LE_OK - access successful.
Parameters
[in]path
[in]value
le_result_t le_avdata_SetFloat ( const char *LE_NONNULL  path,
double  value 
)

Sets an asset data to a float value.

Returns
:
  • LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  • LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  • LE_OK - access successful.
Parameters
[in]path
[in]value
le_result_t le_avdata_SetInt ( const char *LE_NONNULL  path,
int32_t  value 
)

Sets an asset data to an integer value.

Returns
:
  • LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  • LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  • LE_OK - access successful.
Parameters
[in]path
[in]value
le_result_t le_avdata_SetNull ( const char *LE_NONNULL  path)

Sets an asset data to contain a null value, represented by the data type of none.

Returns
:
  • LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  • LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  • LE_OK - access successful.
Parameters
[in]path
void le_avdata_SetServerDisconnectHandler ( le_avdata_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_avdata_SetString ( const char *LE_NONNULL  path,
const char *LE_NONNULL  value 
)

Sets an asset data to a string value.

Returns
:
  • LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  • LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  • LE_OK - access successful.
Parameters
[in]path
[in]value
le_result_t le_avdata_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.