le_avdata_interface.h

    1 /*
    2  * ====================== WARNING ======================
    3  *
    4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    5  * DO NOT MODIFY IN ANY WAY.
    6  *
    7  * ====================== WARNING ======================
    8  */
    9 
   10 /**
   11  * @page c_le_avdata AirVantage Data
   12  *
   13  * @ref le_avdata_interface.h "API Reference" <br>
   14  * @ref howToAVData "How To Manage Data"
   15  *
   16  * <HR>
   17  *
   18  * This API provides a data service to allow apps to manage app-specific
   19  * data on the AirVantage server.
   20  *
   21  * Data is setup as @b assets &mdash;  a collection of fields that can be managed by the AirVantage
   22  * server.
   23  *
   24  * An asset field is a single piece of information that can be managed by the AirVantage server.
   25  * There can be multiple fields in an asset.
   26  *
   27  * A field can be:
   28  * - @c variable allows an app to set the value, and can be read from the AV server.
   29  * - @c setting allows the AV server to set the value, and can be read by an app.
   30  * - @c command allows the AV server to invoke a command or function in the app.
   31  *
   32  * All fields have names. Variable and setting fields also have a type. The possible field types,
   33  * along with the default value are:
   34  * - string (empty string)
   35  * - integer (0)
   36  * - float (0.0)
   37  * - boolean (false)
   38  * - binary (zero-length block).
   39  *
   40  * Default values can be overwritten in the asset definition. Currently, string, integer, float
   41  * and boolean fields are supported; binary fields will be supported in the future.
   42  *
   43  *
   44  * @section le_avdata_instance Asset Data Instances
   45  *
   46  * An app that needs to send data to the AirVantage server must first create an asset instance
   47  * using le_avc_Create() with the name of the asset definition.
   48  * Once an asset instance is created, the app can begin accessing the instance's fields.
   49  *
   50  * Multiple instances of the same asset can be created, as well as multiple instances of different
   51  * assets.
   52  *
   53  * Asset definitions are specified in the @ref defFilesCdef_assets section of the app's @c cdef file.
   54  *
   55  * @section le_avdata_field Field Values and Activity
   56  *
   57  * Set functions are available to set variable field values. Get functions are
   58  * available to get settings fields' values.
   59  *
   60  * An app can register a handler so that it can be called when activity occurs on a field.
   61  * This is optional for variable and setting fields, but is required for command fields.
   62  * - @c variable called when the field is read by the AV server. The
   63  * app can then call the appropriate set function to provide a new value for the field.
   64  * - @c setting called when the field has been updated by the AV server
   65  * with a new value. The app can use the appropriate get function to retrieve the new value.
   66  * - @c command called when the AV server wants to invoke a command. The
   67  * app should perform an appropriate action or call a function to execute this command.
   68  *
   69  * Registered handlers are only called when the server performs the associated activity on
   70  * a specific field of an asset instance. For example, a handler registered on a variable field will
   71  * be called if the server reads only that field of an instance; it will not be called if the
   72  * server reads the whole instance of an asset.
   73  *
   74  * Leaving it optional to register handlers for variable and setting fields allows an
   75  * app to decide how it wants to access variable and setting fields. It can decide to
   76  * only do something in response to the AV server, or it can work independently of the AV server
   77  * updating variables when it has a new value, and reading settings only when it needs the value.
   78  *
   79  * @section le_avdata_observe Observe
   80  *
   81  * If the @ref howToAVData_enableObserve "Observe" is enabled, the AirVantage Server will send
   82  * observe requests on all user-defined assets of an app.
   83  *
   84  * Whenever an app (asset) changes a field value by using le_avdata_Set*(), it'll trigger a
   85  * notify if Observe is enabled on that asset. The notify contains only the value of the changed
   86  * field.
   87  *
   88  * @section le_avdata_fatal Fatal Behavior
   89  *
   90  * An invalid asset name or field name is treated as a fatal error (i.e. non-recoverable)
   91  * and will result in the client app being terminated.
   92  *
   93  * <HR>
   94  *
   95  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   96  */
   97 /**
   98  * @file le_avdata_interface.h
   99  *
  100  * Legato @ref c_le_avdata include file.
  101  *
  102  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
  103  */
  104 
  105 #ifndef LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
  106 #define LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
  107 
  108 
  109 #include "legato.h"
  110 
  111 //--------------------------------------------------------------------------------------------------
  112 /**
  113  *
  114  * Connect the current client thread to the service providing this API. Block until the service is
  115  * available.
  116  *
  117  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  118  * called before any other functions in this API.  Normally, ConnectService is automatically called
  119  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  120  *
  121  * This function is created automatically.
  122  */
  123 //--------------------------------------------------------------------------------------------------
  124 void le_avdata_ConnectService
  125 (
  126     void
  127 );
  128 
  129 //--------------------------------------------------------------------------------------------------
  130 /**
  131  *
  132  * Try to connect the current client thread to the service providing this API. Return with an error
  133  * if the service is not available.
  134  *
  135  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  136  * called before any other functions in this API.  Normally, ConnectService is automatically called
  137  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  138  *
  139  * This function is created automatically.
  140  *
  141  * @return
  142  *  - LE_OK if the client connected successfully to the service.
  143  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  144  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  145  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  146  */
  147 //--------------------------------------------------------------------------------------------------
  148 le_result_t le_avdata_TryConnectService
  149 (
  150     void
  151 );
  152 
  153 //--------------------------------------------------------------------------------------------------
  154 /**
  155  *
  156  * Disconnect the current client thread from the service providing this API.
  157  *
  158  * Normally, this function doesn't need to be called. After this function is called, there's no
  159  * longer a connection to the service, and the functions in this API can't be used. For details, see
  160  * @ref apiFilesC_client.
  161  *
  162  * This function is created automatically.
  163  */
  164 //--------------------------------------------------------------------------------------------------
  165 void le_avdata_DisconnectService
  166 (
  167     void
  168 );
  169 
  170 
  171 //--------------------------------------------------------------------------------------------------
  172 /**
  173  * An asset data instance reference
  174  */
  175 //--------------------------------------------------------------------------------------------------
  176 typedef struct le_avdata_AssetInstance* le_avdata_AssetInstanceRef_t;
  177 
  178 
  179 //--------------------------------------------------------------------------------------------------
  180 /**
  181  * Define the maximum length of an asset name (TODO: verify value)
  182  */
  183 //--------------------------------------------------------------------------------------------------
  184 #define LE_AVDATA_ASSET_NAME_LEN 47
  185 
  186 
  187 //--------------------------------------------------------------------------------------------------
  188 /**
  189  * Define the maximum length of a field name (TODO: verify value)
  190  */
  191 //--------------------------------------------------------------------------------------------------
  192 #define LE_AVDATA_FIELD_NAME_LEN 47
  193 
  194 
  195 //--------------------------------------------------------------------------------------------------
  196 /**
  197  * Define the maximum length of a string field (TODO: verify value)
  198  */
  199 //--------------------------------------------------------------------------------------------------
  200 #define LE_AVDATA_STRING_VALUE_LEN 255
  201 
  202 
  203 //--------------------------------------------------------------------------------------------------
  204 /**
  205  * Define the maximum length of a binary data field (TODO: verify value)
  206  */
  207 //--------------------------------------------------------------------------------------------------
  208 #define LE_AVDATA_BINARY_VALUE_LEN 255
  209 
  210 
  211 //--------------------------------------------------------------------------------------------------
  212 /**
  213  * Reference type used by Add/Remove functions for EVENT 'le_avdata_FieldEvent'
  214  */
  215 //--------------------------------------------------------------------------------------------------
  216 typedef struct le_avdata_FieldEventHandler* le_avdata_FieldEventHandlerRef_t;
  217 
  218 
  219 //--------------------------------------------------------------------------------------------------
  220 /**
  221  * Handler for field activity
  222  *
  223  * @param instRef
  224  * @param fieldName
  225  * @param contextPtr
  226  */
  227 //--------------------------------------------------------------------------------------------------
  228 typedef void (*le_avdata_FieldHandlerFunc_t)
  229 (
  230     le_avdata_AssetInstanceRef_t instRef,
  231     const char* fieldName,
  232     void* contextPtr
  233 );
  234 
  235 //--------------------------------------------------------------------------------------------------
  236 /**
  237  * Add handler function for EVENT 'le_avdata_FieldEvent'
  238  *
  239  * This event provides information on field activity
  240  */
  241 //--------------------------------------------------------------------------------------------------
  242 le_avdata_FieldEventHandlerRef_t le_avdata_AddFieldEventHandler
  243 (
  244     le_avdata_AssetInstanceRef_t instRef,
  245         ///< [IN]
  246 
  247     const char* fieldName,
  248         ///< [IN]
  249 
  250     le_avdata_FieldHandlerFunc_t handlerPtr,
  251         ///< [IN]
  252 
  253     void* contextPtr
  254         ///< [IN]
  255 );
  256 
  257 //--------------------------------------------------------------------------------------------------
  258 /**
  259  * Remove handler function for EVENT 'le_avdata_FieldEvent'
  260  */
  261 //--------------------------------------------------------------------------------------------------
  262 void le_avdata_RemoveFieldEventHandler
  263 (
  264     le_avdata_FieldEventHandlerRef_t addHandlerRef
  265         ///< [IN]
  266 );
  267 
  268 //--------------------------------------------------------------------------------------------------
  269 /**
  270  * Create an instance of AirVantage asset
  271  *
  272  * @return Reference to the asset instance
  273  *
  274  * @note It is a fatal error if the asset isn't defined.
  275  */
  276 //--------------------------------------------------------------------------------------------------
  277 le_avdata_AssetInstanceRef_t le_avdata_Create
  278 (
  279     const char* assetName
  280         ///< [IN]
  281 );
  282 
  283 //--------------------------------------------------------------------------------------------------
  284 /**
  285  * Delete an instance of AirVantage asset
  286  *
  287  * @note It's a fatal error if the instRef isn't valid
  288  */
  289 //--------------------------------------------------------------------------------------------------
  290 void le_avdata_Delete
  291 (
  292     le_avdata_AssetInstanceRef_t instRef
  293         ///< [IN]
  294 );
  295 
  296 //--------------------------------------------------------------------------------------------------
  297 /**
  298  * Get the value of an integer setting field
  299  *
  300  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
  301  */
  302 //--------------------------------------------------------------------------------------------------
  303 void le_avdata_GetInt
  304 (
  305     le_avdata_AssetInstanceRef_t instRef,
  306         ///< [IN]
  307 
  308     const char* fieldName,
  309         ///< [IN]
  310 
  311     int32_t* valuePtr
  312         ///< [OUT]
  313 );
  314 
  315 //--------------------------------------------------------------------------------------------------
  316 /**
  317  * Set the value of an integer variable field
  318  *
  319  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
  320  */
  321 //--------------------------------------------------------------------------------------------------
  322 void le_avdata_SetInt
  323 (
  324     le_avdata_AssetInstanceRef_t instRef,
  325         ///< [IN]
  326 
  327     const char* fieldName,
  328         ///< [IN]
  329 
  330     int32_t value
  331         ///< [IN]
  332 );
  333 
  334 //--------------------------------------------------------------------------------------------------
  335 /**
  336  * Get the value of a float setting field
  337  *
  338  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
  339  */
  340 //--------------------------------------------------------------------------------------------------
  341 void le_avdata_GetFloat
  342 (
  343     le_avdata_AssetInstanceRef_t instRef,
  344         ///< [IN]
  345 
  346     const char* fieldName,
  347         ///< [IN]
  348 
  349     double* valuePtr
  350         ///< [OUT]
  351 );
  352 
  353 //--------------------------------------------------------------------------------------------------
  354 /**
  355  * Set the value of a float variable field
  356  *
  357  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
  358  */
  359 //--------------------------------------------------------------------------------------------------
  360 void le_avdata_SetFloat
  361 (
  362     le_avdata_AssetInstanceRef_t instRef,
  363         ///< [IN]
  364 
  365     const char* fieldName,
  366         ///< [IN]
  367 
  368     double value
  369         ///< [IN]
  370 );
  371 
  372 //--------------------------------------------------------------------------------------------------
  373 /**
  374  * Get the value of a boolean setting field
  375  *
  376  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
  377  */
  378 //--------------------------------------------------------------------------------------------------
  379 void le_avdata_GetBool
  380 (
  381     le_avdata_AssetInstanceRef_t instRef,
  382         ///< [IN]
  383 
  384     const char* fieldName,
  385         ///< [IN]
  386 
  387     bool* valuePtr
  388         ///< [OUT]
  389 );
  390 
  391 //--------------------------------------------------------------------------------------------------
  392 /**
  393  * Set the value of a boolean variable field
  394  *
  395  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
  396  */
  397 //--------------------------------------------------------------------------------------------------
  398 void le_avdata_SetBool
  399 (
  400     le_avdata_AssetInstanceRef_t instRef,
  401         ///< [IN]
  402 
  403     const char* fieldName,
  404         ///< [IN]
  405 
  406     bool value
  407         ///< [IN]
  408 );
  409 
  410 //--------------------------------------------------------------------------------------------------
  411 /**
  412  * Get the value of a string setting field
  413  *
  414  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
  415  */
  416 //--------------------------------------------------------------------------------------------------
  417 void le_avdata_GetString
  418 (
  419     le_avdata_AssetInstanceRef_t instRef,
  420         ///< [IN]
  421 
  422     const char* fieldName,
  423         ///< [IN]
  424 
  425     char* value,
  426         ///< [OUT]
  427 
  428     size_t valueNumElements
  429         ///< [IN]
  430 );
  431 
  432 //--------------------------------------------------------------------------------------------------
  433 /**
  434  * Set the value of a string variable field
  435  *
  436  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
  437  */
  438 //--------------------------------------------------------------------------------------------------
  439 void le_avdata_SetString
  440 (
  441     le_avdata_AssetInstanceRef_t instRef,
  442         ///< [IN]
  443 
  444     const char* fieldName,
  445         ///< [IN]
  446 
  447     const char* value
  448         ///< [IN]
  449 );
  450 
  451 //--------------------------------------------------------------------------------------------------
  452 /**
  453  * Get the value of a binary data setting field
  454  *
  455  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
  456  */
  457 //--------------------------------------------------------------------------------------------------
  458 void le_avdata_GetBinary
  459 (
  460     le_avdata_AssetInstanceRef_t instRef,
  461         ///< [IN]
  462 
  463     const char* fieldName,
  464         ///< [IN]
  465 
  466     uint8_t* valuePtr,
  467         ///< [OUT]
  468 
  469     size_t* valueNumElementsPtr
  470         ///< [INOUT]
  471 );
  472 
  473 //--------------------------------------------------------------------------------------------------
  474 /**
  475  * Set the value of a binary data variable field
  476  *
  477  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
  478  */
  479 //--------------------------------------------------------------------------------------------------
  480 void le_avdata_SetBinary
  481 (
  482     le_avdata_AssetInstanceRef_t instRef,
  483         ///< [IN]
  484 
  485     const char* fieldName,
  486         ///< [IN]
  487 
  488     const uint8_t* valuePtr,
  489         ///< [IN]
  490 
  491     size_t valueNumElements
  492         ///< [IN]
  493 );
  494 
  495 
  496 #endif // LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
  497 
le_avdata_Delete
void le_avdata_Delete(le_avdata_AssetInstanceRef_t instRef)
le_avdata_SetBool
void le_avdata_SetBool(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, bool value)
le_avdata_RemoveFieldEventHandler
void le_avdata_RemoveFieldEventHandler(le_avdata_FieldEventHandlerRef_t addHandlerRef)
le_result_t
le_result_t
Definition: le_basics.h:35
le_avdata_GetString
void le_avdata_GetString(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, char *value, size_t valueNumElements)
le_avdata_SetBinary
void le_avdata_SetBinary(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, const uint8_t *valuePtr, size_t valueNumElements)
le_avdata_FieldHandlerFunc_t
void(* le_avdata_FieldHandlerFunc_t)(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, void *contextPtr)
Definition: le_avdata_interface.h:229
le_avdata_DisconnectService
void le_avdata_DisconnectService(void)
le_avdata_AssetInstanceRef_t
struct le_avdata_AssetInstance * le_avdata_AssetInstanceRef_t
Definition: le_avdata_interface.h:176
le_avdata_ConnectService
void le_avdata_ConnectService(void)
le_avdata_GetFloat
void le_avdata_GetFloat(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, double *valuePtr)
le_avdata_TryConnectService
le_result_t le_avdata_TryConnectService(void)
legato.h
le_avdata_GetBinary
void le_avdata_GetBinary(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, uint8_t *valuePtr, size_t *valueNumElementsPtr)
le_avdata_FieldEventHandlerRef_t
struct le_avdata_FieldEventHandler * le_avdata_FieldEventHandlerRef_t
Definition: le_avdata_interface.h:216
le_avdata_GetInt
void le_avdata_GetInt(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, int32_t *valuePtr)
le_avdata_SetFloat
void le_avdata_SetFloat(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, double value)
le_avdata_Create
le_avdata_AssetInstanceRef_t le_avdata_Create(const char *assetName)
le_avdata_AddFieldEventHandler
le_avdata_FieldEventHandlerRef_t le_avdata_AddFieldEventHandler(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, le_avdata_FieldHandlerFunc_t handlerPtr, void *contextPtr)
le_avdata_GetBool
void le_avdata_GetBool(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, bool *valuePtr)
le_avdata_SetString
void le_avdata_SetString(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, const char *value)
le_avdata_SetInt
void le_avdata_SetInt(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, int32_t value)