le_avdata_interface.h

    1 
    2 
    3 /*
    4  * ====================== WARNING ======================
    5  *
    6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    7  * DO NOT MODIFY IN ANY WAY.
    8  *
    9  * ====================== WARNING ======================
   10  */
   11 
   12 /**
   13  * @page c_le_avdata AirVantage Data API
   14  *
   15  * @ref le_avdata_interface.h "API Reference" <br>
   16  * @ref avData "How To Manage Data"
   17  *
   18  * This API provides a data service to allow Apps to manage App-specific data on the AirVantage
   19  * server.
   20  *
   21  * @section le_avdata_binding IPC Interfaces Binding
   22  *
   23  * All the functions of this API are provided by the @b avcService platform service.
   24  *
   25  * Code sample for binding to avcService:
   26  * @verbatim
   27  bindings:
   28  {
   29     clientExe.clientComponent.le_avdata -> avcService.le_avdata
   30  }
   31  @endverbatim
   32  *
   33  *
   34  * @section le_avdata_overview AirVantage Data Overview
   35  *
   36  * Data is setup as @b Assets &mdash;  a collection of fields that can be managed by the AirVantage
   37  * server.
   38  *
   39  * An @b asset @b field is a single data point taken from a sensor that can be managed by the
   40  * AirVantage server.
   41  *
   42  * A field can be:
   43  * - @b variable allowing the AirVantage server to read the value, and can be read/writtten to by an App.
   44  * - @b setting allowing the AirVantage server to read/write the value, and can be read/written to by an App.
   45  * - @b command allowing the AirVantage server to invoke a function in the App.
   46  *
   47  * Fields are referred to by paths and need to follow these rules:
   48  *
   49  * - A parent path @b can't contain a field, parent path or child path that has the same name.
   50  * - Paths must be separated by a slash ("/") or a dot (".").
   51  * - When using a ("/") the path must start with a ("/") (e.g., /a/b/c)
   52  * - When using a (".") the path must start with the first field, (e.g., a.b.c)
   53  *
   54  * @note There is no leading "." when using "." delimiter.
   55  *
   56  * Variable and setting fields also have types. The available field types are:
   57  * - string
   58  * - integer
   59  * - float
   60  * - boolean
   61  *
   62  * Variable and setting fields have no default values. When they are first created with the
   63  * le_avdata_CreateResource() , all values are "null". They can also be set to "null" values with
   64  * the le_avdata_SetNull() .
   65  *
   66  * Fields do not have a fixed data type, so any of the SetInt/Float/Bool/String can
   67  * be called for a certain field to change its value and its type. However, A
   68  * GetInt/Float/Bool/String API must be called on a field with the matching type. In other words,
   69  * a Get API does not perform type-casting.
   70  *
   71  * @note If a user enters a value 0 for float data type, an error will be returned (LE_NOT_FOUND),
   72  * as the system infers 0 as an integer value and the data type doesn't match.  0.0 needs to be set
   73  * for the float data type to be zero.
   74  *
   75  * @section le_avdata_field Field Values and Activity
   76  *
   77  * Set functions are available to set field values (including "null"). Get functions are
   78  * available to get field values.
   79  *
   80  * An App can register a handler so that it can be called when an activity occurs on a field.
   81  * This is optional for variable and setting fields, but is @b required for command fields.
   82  * Registered handlers are called only when activities from AV server occurs. Client activities do
   83  * not trigger handlers.
   84  *
   85  * A handler registered with a command field is invoked with an optional argument list sent from the
   86  * AirVantage server. The APIs GetInt/Float/Bool/StringArg and le_avdata_GetStringArgLength() are
   87  * available to extract the arguments in the handler definition. AV server does not send argument
   88  * lists for handlers registered with variable and setting fields.
   89  *
   90  * A handler registered with a command field must call the le_avdata_ReplyExecResult() at the end of
   91  * its definition, in order to reply the command execution result to the AV server.
   92  *
   93  * Sometimes instead of waiting for activity to occur on a field, users may want to have their
   94  * application notify the server of their asset data details. Asset data can also be pushed from
   95  * the device to the server by using le_avdata_Push().
   96  *
   97  * This code sample shows how to push asset data to the server (assuming session is opened)
   98  *
   99  * @code
  100  * static void PushCallbackHandler
  101  * (
  102  *     le_avdata_PushStatus_t status,
  103  *     void* contextPtr
  104  * )
  105  * {
  106  *     if (status == LE_AVDATA_PUSH_SUCCESS)
  107  *     {
  108  *         // data pushed successfully
  109  *     }
  110  * }
  111  *
  112  * COMPONENT_INIT
  113  * {
  114  *       le_result_t result;
  115  *       result = le_avdata_CreateResource("/livingRoom/sensor1", LE_AVDATA_ACCESS_VARIABLE);
  116  *       if (result != LE_OK)
  117  *       {
  118  *           LE_FATAL("Error in creating livingRoom resource.");
  119  *       }
  120  *
  121  *       result = le_avdata_SetInt("/livingRoom/sensor1", 5) == LE_OK);
  122  *       if (result != LE_OK)
  123  *       {
  124  *           LE_FATAL("Failed to set value for livingRoom resource.");
  125  *       }
  126  *
  127  *       le_avdata_Push("/livingRoom/sensor1", PushCallbackHandler, NULL);
  128  * }
  129  * @endcode
  130  *
  131  * If users simply want to push a data dump to the server without creating resources,
  132  * le_avdata_PushStream() is available.
  133  * @note The push stream API has a limit of 20K.
  134  *
  135  * @code
  136  * COMPONENT_INIT
  137  * {
  138  *       int fd = open("data.txt", O_RDONLY);
  139  *       if (fd == -1)
  140  *       {
  141  *          LE_FATAL("Failed to open file.");
  142  *       }
  143  *
  144  *       // The data dump sent to the server will be display under <Path>
  145  *       le_avdata_PushStream("<Path>", fd, PushCallbackHandler, NULL);
  146  * }
  147  * @endcode
  148  *
  149  * @section le_avdata_namespace Namespace
  150  *
  151  * By default all asset data paths are created and managed under the application namespace.
  152  * Calling @c le_avdata_GetXXX / @c le_avdata_SetXXX/ le_avdata_AddResourceEventHandler() /
  153  * le_avdata_Push() with the path "/a/b/c" will search for the "/a/b/c" data under the apps
  154  * namespace. In order to query any paths created under an application namespace, user must append
  155  * the app name in front of the request on the server side. If creating asset data under application
  156  * namespace is not desired, users must call le_avdata_SetNamespace() and set the value to global.
  157  * An application that changes its namespace to global will be creating asset data in the global
  158  * space. All asset data API will use the last namespace set until the function is called again and
  159  * the namespace is set to something new.
  160  *
  161  * @note Asset data settings are persistent after an application restart or device reboot,
  162  * regardless of the namespace used to create it. The asset data settings are restored lazily when
  163  * the app or server reads the setting.
  164  *
  165  * Example:
  166  *
  167  * @code
  168  * #define RESOURCE_A         "/test/resourceA"
  169  *
  170  * COMPONENT_INIT
  171  * {
  172  *     int intVal;
  173  *     LE_ASSERT(le_avdata_CreateResource(RESOURCE_A, LE_AVDATA_ACCESS_VARIABLE) == LE_OK);
  174  *     LE_ASSERT(le_avdata_SetInt(RESOURCE_A, 1) == LE_OK);
  175  *     LE_ASSERT(le_avdata_GetInt(RESOURCE_A, &intVal) == LE_OK);
  176  *     LE_ASSERT(intVal == 1); // value obtained under the application namespace
  177  *
  178  *     // Switch to global namespace
  179  *     LE_ASSERT(le_avdata_SetNamespace(LE_AVDATA_NAMESPACE_GLOBAL) == LE_OK);
  180  *
  181  *     LE_ASSERT(le_avdata_CreateResource(RESOURCE_A, LE_AVDATA_ACCESS_VARIABLE) == LE_OK);
  182  *     LE_ASSERT(le_avdata_SetInt(RESOURCE_A, 2) == LE_OK);
  183  *     LE_ASSERT(le_avdata_GetInt(RESOURCE_A, &intVal) == LE_OK);
  184  *     LE_ASSERT(intVal == 2); // value obtained under the global namespace
  185  * }
  186  * @endcode
  187  *
  188  * An application starts by creating a path "/test/resourceA" under the default application
  189  * namespace and sets it to 1. Then it sets the namespace to global and creates another path
  190  * "/test/resourceA" with a value of 2. A read request from the server on "<appName>/test/resourceA"
  191  * will return 1; whereas a read request on "/test/resourceA" will return 2. A read request from the
  192  * server on a parent node will result in reading multiple resources together. For example, a read
  193  * request on "<appName>/test" will result in a response containing relative paths and values of
  194  * resourceA and resourceB.
  195  *
  196  * @section le_avdata_timeseries Time Series
  197  *
  198  * This feature enables user Apps to collect and keep in memory data when the device is off-line and
  199  * send the data to the AirVantage Server when the device is on-line.
  200  *
  201  * Time series records can be initialized using le_avdata_CreateRecord().
  202  * Data can be accumulated using the following data types along with a specified time stamp
  203  * (milliseconds elapsed since epoch).
  204  * - le_avdata_RecordInt()
  205  * - le_avdata_RecordFloat()
  206  * - le_avdata_RecordBool()
  207  * - le_avdata_RecordString()
  208  *
  209  * User apps can then open an @c avms session, and push the collected history data using
  210  * le_avdata_PushRecord(). The callback used when calling le_avdata_PushRecord() will indicate
  211  * whether the push has been successful or not.
  212  *
  213  * This code sample shows how to collect data and send to the server (assuming session is opened)
  214  *
  215  * @code
  216  *
  217  * static void PushCallbackHandler
  218  * (
  219  *     le_avdata_PushStatus_t status,
  220  *     void* contextPtr
  221  * )
  222  * {
  223  *     if (status == LE_AVDATA_PUSH_SUCCESS)
  224  *     {
  225  *         // data pushed successfully
  226  *     }
  227  * }
  228  *
  229  * static void SendData()
  230  * {
  231  *     struct timeval tv;
  232  *     uint64_t utcMilliSec;
  233  *     le_result_t result;
  234  *
  235  *     le_avdata_RecordRef_t recRef = le_avdata_CreateRecord();
  236  *
  237  *     gettimeofday(&tv, NULL);
  238  *     utcMilliSec = (uint64_t)(tv.tv_sec) * 1000 + (uint64_t)(tv.tv_usec) / 1000; // get current time
  239  *     result = le_avdata_RecordFloat(recRef, "speed", 0.08, utcMilliSec);
  240  *
  241  *     if (result == LE_OK)
  242  *     {
  243  *          le_avdata_PushRecord(recRef, PushCallbackHandler, NULL);
  244  *     }
  245  *
  246  *     le_avdata_DeleteRecord(recRef);
  247  * }
  248  * @endcode
  249  *
  250  * @section le_avdata_session User App Session Management
  251  *
  252  * An App can request to open a session and register a handler to get notified of a session
  253  * events. le_avdata_RequestSession() and le_avdata_ReleaseSession() can be used to
  254  * open a session and close a session respectively. If the session was initiated by an
  255  * user app, the session will be closed when all apps release their session reference.
  256  * le_avdata_AddSessionStateHandler() and le_avdata_RemoveSessionStateHandler() can be used to add
  257  * and remove notification handlers.
  258  *
  259  * @section le_avdata_fatal Fatal Behavior
  260  *
  261  * An invalid asset name or field name is treated as a fatal error (i.e. non-recoverable)
  262  * and will result in the client App being terminated.
  263  *
  264  * @section le_avdata_buffer AV Data Buffer Limitation
  265  *
  266  * The number of resources that can be read/written together is limited by the buffer size
  267  * defined by avc client. There are three buffers that determines how many resources can be
  268  * read/written/pushed together.
  269  *
  270  * - COAP_BLOCK1_SIZE - Determines the number of resource that can be written together
  271  * - AVDATA_READ_BUFFER_BYTES - Determines the number of resource that can be read together
  272  * - AVDATA_PUSH_BUFFER_BYTES - Determines the number of resource that can be pushed together
  273  *
  274  * All the buffers are set to 4096 bytes by default. Users can increase the buffer size if an
  275  * application needs to operate on a parent path with a large number of resources under it.
  276  *
  277  * @note Having more than 5000 resources under a parent path is not advisable for
  278  * several reasons: If the network is lost or device resets while the payload is being
  279  * transferred, the read/write operation will fail and has to be re-triggered. Large number
  280  * of settings will also slow down avc startup.
  281  *
  282  * Copyright (C) Sierra Wireless Inc.
  283  */
  284 /**
  285  * @file le_avdata_interface.h
  286  *
  287  * Legato @ref c_le_avdata include file.
  288  *
  289  * Copyright (C) Sierra Wireless Inc.
  290  */
  291 
  292 #ifndef LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
  293 #define LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
  294 
  295 
  296 #include "legato.h"
  297 
  298 // Internal includes for this interface
  299 #include "le_avdata_common.h"
  300 /** @addtogroup le_avdata le_avdata API Reference
  301  * @{
  302  * @file le_avdata_common.h
  303  * @file le_avdata_interface.h **/
  304 //--------------------------------------------------------------------------------------------------
  305 /**
  306  * Type for handler called when a server disconnects.
  307  */
  308 //--------------------------------------------------------------------------------------------------
  309 typedef void (*le_avdata_DisconnectHandler_t)(void *);
  310 
  311 //--------------------------------------------------------------------------------------------------
  312 /**
  313  *
  314  * Connect the current client thread to the service providing this API. Block until the service is
  315  * available.
  316  *
  317  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  318  * called before any other functions in this API.  Normally, ConnectService is automatically called
  319  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  320  *
  321  * This function is created automatically.
  322  */
  323 //--------------------------------------------------------------------------------------------------
  324 void le_avdata_ConnectService
  325 (
  326     void
  327 );
  328 
  329 //--------------------------------------------------------------------------------------------------
  330 /**
  331  *
  332  * Try to connect the current client thread to the service providing this API. Return with an error
  333  * if the service is not available.
  334  *
  335  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  336  * called before any other functions in this API.  Normally, ConnectService is automatically called
  337  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  338  *
  339  * This function is created automatically.
  340  *
  341  * @return
  342  *  - LE_OK if the client connected successfully to the service.
  343  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  344  *    bound.
  345  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  346  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  347  */
  348 //--------------------------------------------------------------------------------------------------
  349 le_result_t le_avdata_TryConnectService
  350 (
  351     void
  352 );
  353 
  354 //--------------------------------------------------------------------------------------------------
  355 /**
  356  * Set handler called when server disconnection is detected.
  357  *
  358  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  359  * to continue without exiting, it should call longjmp() from inside the handler.
  360  */
  361 //--------------------------------------------------------------------------------------------------
  362 LE_FULL_API void le_avdata_SetServerDisconnectHandler
  363 (
  364     le_avdata_DisconnectHandler_t disconnectHandler,
  365     void *contextPtr
  366 );
  367 
  368 //--------------------------------------------------------------------------------------------------
  369 /**
  370  *
  371  * Disconnect the current client thread from the service providing this API.
  372  *
  373  * Normally, this function doesn't need to be called. After this function is called, there's no
  374  * longer a connection to the service, and the functions in this API can't be used. For details, see
  375  * @ref apiFilesC_client.
  376  *
  377  * This function is created automatically.
  378  */
  379 //--------------------------------------------------------------------------------------------------
  380 void le_avdata_DisconnectService
  381 (
  382     void
  383 );
  384 
  385 
  386 //--------------------------------------------------------------------------------------------------
  387 /**
  388  * Resource access modes:
  389  *   - Variable: read (server), read/write (client)
  390  *   - Setting: read/write (server), read/write (client)
  391  *   - Command: execute (server)
  392  */
  393 //--------------------------------------------------------------------------------------------------
  394 
  395 
  396 //--------------------------------------------------------------------------------------------------
  397 /**
  398  * Resource access types
  399  */
  400 //--------------------------------------------------------------------------------------------------
  401 
  402 
  403 //--------------------------------------------------------------------------------------------------
  404 /**
  405  * Resource namespace
  406  */
  407 //--------------------------------------------------------------------------------------------------
  408 
  409 
  410 //--------------------------------------------------------------------------------------------------
  411 /**
  412  * Data types
  413  */
  414 //--------------------------------------------------------------------------------------------------
  415 
  416 
  417 //--------------------------------------------------------------------------------------------------
  418 /**
  419  * Status of the data push
  420  * @todo Provide additional status to troubleshoot delivery problems
  421  */
  422 //--------------------------------------------------------------------------------------------------
  423 
  424 
  425 //--------------------------------------------------------------------------------------------------
  426 /**
  427  * Argument list reference, for command only.
  428  */
  429 //--------------------------------------------------------------------------------------------------
  430 
  431 
  432 //--------------------------------------------------------------------------------------------------
  433 /**
  434  * Handler for resource activity. Note that the path returned by this event follows the unix format
  435  * (e.g. "/a/b/c") even if the app uses the URL format (e.g "a.b.c") when registering
  436  * the handler.
  437  */
  438 //--------------------------------------------------------------------------------------------------
  439 
  440 
  441 //--------------------------------------------------------------------------------------------------
  442 /**
  443  * Handler for pushing data result.
  444  */
  445 //--------------------------------------------------------------------------------------------------
  446 
  447 
  448 //--------------------------------------------------------------------------------------------------
  449 /**
  450  * Reference type used by Add/Remove functions for EVENT 'le_avdata_ResourceEvent'
  451  */
  452 //--------------------------------------------------------------------------------------------------
  453 
  454 
  455 //--------------------------------------------------------------------------------------------------
  456 /**
  457  * A record reference
  458  */
  459 //--------------------------------------------------------------------------------------------------
  460 
  461 
  462 //--------------------------------------------------------------------------------------------------
  463 /**
  464  * Reference returned by RequestSession function and used by ReleaseSession function
  465  */
  466 //--------------------------------------------------------------------------------------------------
  467 
  468 
  469 //--------------------------------------------------------------------------------------------------
  470 /**
  471  * AVMS session state
  472  */
  473 //--------------------------------------------------------------------------------------------------
  474 
  475 
  476 //--------------------------------------------------------------------------------------------------
  477 /**
  478  * Handler for AV session changes
  479  */
  480 //--------------------------------------------------------------------------------------------------
  481 
  482 
  483 //--------------------------------------------------------------------------------------------------
  484 /**
  485  * Reference type used by Add/Remove functions for EVENT 'le_avdata_SessionState'
  486  */
  487 //--------------------------------------------------------------------------------------------------
  488 
  489 
  490 //--------------------------------------------------------------------------------------------------
  491 /**
  492  * Add handler function for EVENT 'le_avdata_ResourceEvent'
  493  *
  494  * Upon resource access on the server side, the registered handler is called.
  495  *
  496  * For "settings" (read/write), the same handler is called for both read and write access.
  497  *
  498  * For "commands", the handler function must call the "ReplyExecResult" function to send the command
  499  * execution result back to the AVC daemon (which then sends the proper response back to the AV
  500  * server).
  501  */
  502 //--------------------------------------------------------------------------------------------------
  503 le_avdata_ResourceEventHandlerRef_t le_avdata_AddResourceEventHandler
  504 (
  505     const char* LE_NONNULL path,
  506         ///< [IN]
  507     le_avdata_ResourceHandlerFunc_t handlerPtr,
  508         ///< [IN]
  509     void* contextPtr
  510         ///< [IN]
  511 );
  512 
  513 //--------------------------------------------------------------------------------------------------
  514 /**
  515  * Remove handler function for EVENT 'le_avdata_ResourceEvent'
  516  */
  517 //--------------------------------------------------------------------------------------------------
  518 void le_avdata_RemoveResourceEventHandler
  519 (
  520     le_avdata_ResourceEventHandlerRef_t handlerRef
  521         ///< [IN]
  522 );
  523 
  524 //--------------------------------------------------------------------------------------------------
  525 /**
  526  * Create an asset data with the provided path. Note that asset data type and value are determined
  527  * upon the first call to a Set function. When an asset data is created, it contains a null value,
  528  * represented by the data type of none.
  529  *
  530  * @return:
  531  *      - LE_OK on success
  532  *      - LE_DUPLICATE if path has already been called by CreateResource before, or path is parent
  533  *        or child to an existing Asset Data path.
  534  *      - LE_FAULT on any other error.
  535  */
  536 //--------------------------------------------------------------------------------------------------
  537 le_result_t le_avdata_CreateResource
  538 (
  539     const char* LE_NONNULL path,
  540         ///< [IN]
  541     le_avdata_AccessMode_t accessMode
  542         ///< [IN]
  543 );
  544 
  545 //--------------------------------------------------------------------------------------------------
  546 /**
  547  * Sets the namespace for asset data.
  548  *
  549  * @return:
  550  *      - LE_OK on success
  551  *      - LE_BAD_PARAMETER if the namespace is unknown
  552  */
  553 //--------------------------------------------------------------------------------------------------
  554 le_result_t le_avdata_SetNamespace
  555 (
  556     le_avdata_Namespace_t _namespace
  557         ///< [IN]
  558 );
  559 
  560 //--------------------------------------------------------------------------------------------------
  561 /**
  562  * Sets an asset data to contain a null value, represented by the data type of none.
  563  *
  564  * @return:
  565  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  566  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  567  *      - LE_OK - access successful.
  568  */
  569 //--------------------------------------------------------------------------------------------------
  570 le_result_t le_avdata_SetNull
  571 (
  572     const char* LE_NONNULL path
  573         ///< [IN]
  574 );
  575 
  576 //--------------------------------------------------------------------------------------------------
  577 /**
  578  * Gets the integer value of an asset data.
  579  *
  580  * @return:
  581  *      - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
  582  *      - LE_UNAVAILABLE - asset data contains null value
  583  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  584  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  585  *      - LE_OK - access successful.
  586  */
  587 //--------------------------------------------------------------------------------------------------
  588 le_result_t le_avdata_GetInt
  589 (
  590     const char* LE_NONNULL path,
  591         ///< [IN]
  592     int32_t* valuePtr
  593         ///< [OUT]
  594 );
  595 
  596 //--------------------------------------------------------------------------------------------------
  597 /**
  598  * Sets an asset data to an integer value.
  599  *
  600  * @return:
  601  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  602  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  603  *      - LE_OK - access successful.
  604  */
  605 //--------------------------------------------------------------------------------------------------
  606 le_result_t le_avdata_SetInt
  607 (
  608     const char* LE_NONNULL path,
  609         ///< [IN]
  610     int32_t value
  611         ///< [IN]
  612 );
  613 
  614 //--------------------------------------------------------------------------------------------------
  615 /**
  616  * Gets the float value of an asset data.
  617  *
  618  * @return:
  619  *      - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
  620  *      - LE_UNAVAILABLE - asset data contains null value
  621  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  622  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  623  *      - LE_OK - access successful.
  624  */
  625 //--------------------------------------------------------------------------------------------------
  626 le_result_t le_avdata_GetFloat
  627 (
  628     const char* LE_NONNULL path,
  629         ///< [IN]
  630     double* valuePtr
  631         ///< [OUT]
  632 );
  633 
  634 //--------------------------------------------------------------------------------------------------
  635 /**
  636  * Sets an asset data to a float value.
  637  *
  638  * @return:
  639  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  640  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  641  *      - LE_OK - access successful.
  642  */
  643 //--------------------------------------------------------------------------------------------------
  644 le_result_t le_avdata_SetFloat
  645 (
  646     const char* LE_NONNULL path,
  647         ///< [IN]
  648     double value
  649         ///< [IN]
  650 );
  651 
  652 //--------------------------------------------------------------------------------------------------
  653 /**
  654  * Gets the bool value of an asset data.
  655  *
  656  * @return:
  657  *      - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
  658  *      - LE_UNAVAILABLE - asset data contains null value
  659  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  660  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  661  *      - LE_OK - access successful.
  662  */
  663 //--------------------------------------------------------------------------------------------------
  664 le_result_t le_avdata_GetBool
  665 (
  666     const char* LE_NONNULL path,
  667         ///< [IN]
  668     bool* valuePtr
  669         ///< [OUT]
  670 );
  671 
  672 //--------------------------------------------------------------------------------------------------
  673 /**
  674  * Sets an asset data to a bool value.
  675  *
  676  * @return:
  677  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  678  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  679  *      - LE_OK - access successful.
  680  */
  681 //--------------------------------------------------------------------------------------------------
  682 le_result_t le_avdata_SetBool
  683 (
  684     const char* LE_NONNULL path,
  685         ///< [IN]
  686     bool value
  687         ///< [IN]
  688 );
  689 
  690 //--------------------------------------------------------------------------------------------------
  691 /**
  692  * Gets the string value of an asset data.
  693  *
  694  * @return:
  695  *      - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
  696  *      - LE_UNAVAILABLE - asset data contains null value
  697  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  698  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  699  *      - LE_OVERFLOW - asset data length exceeds the maximum length
  700  *      - LE_OK - access successful
  701  */
  702 //--------------------------------------------------------------------------------------------------
  703 le_result_t le_avdata_GetString
  704 (
  705     const char* LE_NONNULL path,
  706         ///< [IN]
  707     char* value,
  708         ///< [OUT]
  709     size_t valueSize
  710         ///< [IN]
  711 );
  712 
  713 //--------------------------------------------------------------------------------------------------
  714 /**
  715  * Sets an asset data to a string value.
  716  *
  717  * @return:
  718  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  719  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  720  *      - LE_OK - access successful.
  721  */
  722 //--------------------------------------------------------------------------------------------------
  723 le_result_t le_avdata_SetString
  724 (
  725     const char* LE_NONNULL path,
  726         ///< [IN]
  727     const char* LE_NONNULL value
  728         ///< [IN]
  729 );
  730 
  731 //--------------------------------------------------------------------------------------------------
  732 /**
  733  * Get the bool argument with the specified name.
  734  *
  735  * @return:
  736  *      - LE_OK on success
  737  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  738  */
  739 //--------------------------------------------------------------------------------------------------
  740 le_result_t le_avdata_GetBoolArg
  741 (
  742     le_avdata_ArgumentListRef_t argumentListRef,
  743         ///< [IN]
  744     const char* LE_NONNULL argName,
  745         ///< [IN]
  746     bool* boolArgPtr
  747         ///< [OUT]
  748 );
  749 
  750 //--------------------------------------------------------------------------------------------------
  751 /**
  752  * Get the float argument with the specified name.
  753  *
  754  * @return:
  755  *      - LE_OK on success
  756  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  757  */
  758 //--------------------------------------------------------------------------------------------------
  759 le_result_t le_avdata_GetFloatArg
  760 (
  761     le_avdata_ArgumentListRef_t argumentListRef,
  762         ///< [IN]
  763     const char* LE_NONNULL argName,
  764         ///< [IN]
  765     double* floatArgPtr
  766         ///< [OUT]
  767 );
  768 
  769 //--------------------------------------------------------------------------------------------------
  770 /**
  771  * Get the int argument with the specified name.
  772  *
  773  * @return:
  774  *      - LE_OK on success
  775  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  776  */
  777 //--------------------------------------------------------------------------------------------------
  778 le_result_t le_avdata_GetIntArg
  779 (
  780     le_avdata_ArgumentListRef_t argumentListRef,
  781         ///< [IN]
  782     const char* LE_NONNULL argName,
  783         ///< [IN]
  784     int32_t* intArgPtr
  785         ///< [OUT]
  786 );
  787 
  788 //--------------------------------------------------------------------------------------------------
  789 /**
  790  * Get the string argument with the specified name.
  791  *
  792  * @return:
  793  *      - LE_OK on success
  794  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API
  795  *      - LE_OVERFLOW - argument length exceeds the maximum length
  796  */
  797 //--------------------------------------------------------------------------------------------------
  798 le_result_t le_avdata_GetStringArg
  799 (
  800     le_avdata_ArgumentListRef_t argumentListRef,
  801         ///< [IN]
  802     const char* LE_NONNULL argName,
  803         ///< [IN]
  804     char* strArg,
  805         ///< [OUT]
  806     size_t strArgSize
  807         ///< [IN]
  808 );
  809 
  810 //--------------------------------------------------------------------------------------------------
  811 /**
  812  * Get the length (excluding terminating null byte) of the string argument of the specified name.
  813  *
  814  * @return:
  815  *      - LE_OK on success
  816  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  817  */
  818 //--------------------------------------------------------------------------------------------------
  819 le_result_t le_avdata_GetStringArgLength
  820 (
  821     le_avdata_ArgumentListRef_t argumentListRef,
  822         ///< [IN]
  823     const char* LE_NONNULL argName,
  824         ///< [IN]
  825     int32_t* strArgLenPtr
  826         ///< [OUT]
  827 );
  828 
  829 //--------------------------------------------------------------------------------------------------
  830 /**
  831  * Reply command execution result to AVC Daemon, which can then respond to AV server. This function
  832  * MUST be called at the end of a command execution, in order for AV server to be notified about the
  833  * execution status.
  834  */
  835 //--------------------------------------------------------------------------------------------------
  836 void le_avdata_ReplyExecResult
  837 (
  838     le_avdata_ArgumentListRef_t argumentListRef,
  839         ///< [IN]
  840     le_result_t result
  841         ///< [IN]
  842 );
  843 
  844 //--------------------------------------------------------------------------------------------------
  845 /**
  846  * Push asset data to the server.
  847  *
  848  * @return:
  849  *      - LE_OK on success
  850  *      - LE_NOT_FOUND if the provided path doesn't exist
  851  *      - LE_BUSY if push service is busy. Data added to queue list for later push
  852  *      - LE_OVERFLOW if data size exceeds the maximum allowed size
  853  *      - LE_NO_MEMORY if push queue is full, try again later
  854  *      - LE_FAULT on any other error
  855  */
  856 //--------------------------------------------------------------------------------------------------
  857 le_result_t le_avdata_Push
  858 (
  859     const char* LE_NONNULL path,
  860         ///< [IN]
  861     le_avdata_CallbackResultFunc_t handlerPtr,
  862         ///< [IN]
  863     void* contextPtr
  864         ///< [IN]
  865 );
  866 
  867 //--------------------------------------------------------------------------------------------------
  868 /**
  869  * Push data dump to a specified path on the server.
  870  *
  871  * @return:
  872  *      - LE_OK on success
  873  *      - LE_BUSY if push service is busy. Data added to queue list for later push
  874  *      - LE_OVERFLOW if data size exceeds the maximum allowed size
  875  *      - LE_NO_MEMORY if push queue is full, try again later
  876  *      - LE_FAULT on any other error
  877  */
  878 //--------------------------------------------------------------------------------------------------
  879 le_result_t le_avdata_PushStream
  880 (
  881     const char* LE_NONNULL path,
  882         ///< [IN]
  883     int fd,
  884         ///< [IN]
  885     le_avdata_CallbackResultFunc_t handlerPtr,
  886         ///< [IN]
  887     void* contextPtr
  888         ///< [IN]
  889 );
  890 
  891 //--------------------------------------------------------------------------------------------------
  892 /**
  893  * Create a timeseries record
  894  *
  895  * @return Reference to the record
  896  */
  897 //--------------------------------------------------------------------------------------------------
  898 le_avdata_RecordRef_t le_avdata_CreateRecord
  899 (
  900     void
  901 );
  902 
  903 //--------------------------------------------------------------------------------------------------
  904 /**
  905  * Delete a timeseries record
  906  */
  907 //--------------------------------------------------------------------------------------------------
  908 void le_avdata_DeleteRecord
  909 (
  910     le_avdata_RecordRef_t recordRef
  911         ///< [IN]
  912 );
  913 
  914 //--------------------------------------------------------------------------------------------------
  915 /**
  916  * Accumulate int data
  917  *
  918  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
  919  *
  920  * @return:
  921  *      - LE_OK on success
  922  *      - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  923  *      - LE_FAULT on any other error
  924  */
  925 //--------------------------------------------------------------------------------------------------
  926 le_result_t le_avdata_RecordInt
  927 (
  928     le_avdata_RecordRef_t recordRef,
  929         ///< [IN]
  930     const char* LE_NONNULL path,
  931         ///< [IN]
  932     int32_t value,
  933         ///< [IN]
  934     uint64_t timestamp
  935         ///< [IN]
  936 );
  937 
  938 //--------------------------------------------------------------------------------------------------
  939 /**
  940  * Accumulate float data
  941  *
  942  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
  943  *
  944  * @return:
  945  *      - LE_OK on success
  946  *      - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  947  *      - LE_FAULT on any other error
  948  */
  949 //--------------------------------------------------------------------------------------------------
  950 le_result_t le_avdata_RecordFloat
  951 (
  952     le_avdata_RecordRef_t recordRef,
  953         ///< [IN]
  954     const char* LE_NONNULL path,
  955         ///< [IN]
  956     double value,
  957         ///< [IN]
  958     uint64_t timestamp
  959         ///< [IN]
  960 );
  961 
  962 //--------------------------------------------------------------------------------------------------
  963 /**
  964  * Accumulate boolean data
  965  *
  966  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
  967  *
  968  * @return:
  969  *      - LE_OK on success
  970  *      - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  971  *      - LE_FAULT on any other error
  972  */
  973 //--------------------------------------------------------------------------------------------------
  974 le_result_t le_avdata_RecordBool
  975 (
  976     le_avdata_RecordRef_t recordRef,
  977         ///< [IN]
  978     const char* LE_NONNULL path,
  979         ///< [IN]
  980     bool value,
  981         ///< [IN]
  982     uint64_t timestamp
  983         ///< [IN]
  984 );
  985 
  986 //--------------------------------------------------------------------------------------------------
  987 /**
  988  * Accumulate string data
  989  *
  990  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
  991  *
  992  * @return:
  993  *      - LE_OK on success
  994  *      - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  995  *      - LE_FAULT on any other error
  996  */
  997 //--------------------------------------------------------------------------------------------------
  998 le_result_t le_avdata_RecordString
  999 (
 1000     le_avdata_RecordRef_t recordRef,
 1001         ///< [IN]
 1002     const char* LE_NONNULL path,
 1003         ///< [IN]
 1004     const char* LE_NONNULL value,
 1005         ///< [IN]
 1006     uint64_t timestamp
 1007         ///< [IN]
 1008 );
 1009 
 1010 //--------------------------------------------------------------------------------------------------
 1011 /**
 1012  * Push record to the server
 1013  *
 1014  ** @return:
 1015  *      - LE_OK on success
 1016  *      - LE_BUSY if push service is busy. Data added to queue list for later push
 1017  *      - LE_OVERFLOW if data size exceeds the maximum allowed size
 1018  *      - LE_NO_MEMORY if push queue is full, try again later
 1019  *      - LE_FAULT on any other error
 1020  *
 1021  * * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1022  *       function will not return.
 1023  */
 1024 //--------------------------------------------------------------------------------------------------
 1025 le_result_t le_avdata_PushRecord
 1026 (
 1027     le_avdata_RecordRef_t recordRef,
 1028         ///< [IN]
 1029     le_avdata_CallbackResultFunc_t handlerPtr,
 1030         ///< [IN]
 1031     void* contextPtr
 1032         ///< [IN]
 1033 );
 1034 
 1035 //--------------------------------------------------------------------------------------------------
 1036 /**
 1037  * Add handler function for EVENT 'le_avdata_SessionState'
 1038  *
 1039  * This event provides information on AV session state changes
 1040  */
 1041 //--------------------------------------------------------------------------------------------------
 1042 le_avdata_SessionStateHandlerRef_t le_avdata_AddSessionStateHandler
 1043 (
 1044     le_avdata_SessionStateHandlerFunc_t handlerPtr,
 1045         ///< [IN]
 1046     void* contextPtr
 1047         ///< [IN]
 1048 );
 1049 
 1050 //--------------------------------------------------------------------------------------------------
 1051 /**
 1052  * Remove handler function for EVENT 'le_avdata_SessionState'
 1053  */
 1054 //--------------------------------------------------------------------------------------------------
 1055 void le_avdata_RemoveSessionStateHandler
 1056 (
 1057     le_avdata_SessionStateHandlerRef_t handlerRef
 1058         ///< [IN]
 1059 );
 1060 
 1061 //--------------------------------------------------------------------------------------------------
 1062 /**
 1063  * Request the avcServer to open a session.
 1064  *
 1065  * @return
 1066  *      - SessionRef if session request succeeded
 1067  *      - NULL if session request failed
 1068  */
 1069 //--------------------------------------------------------------------------------------------------
 1070 le_avdata_RequestSessionObjRef_t le_avdata_RequestSession
 1071 (
 1072     void
 1073 );
 1074 
 1075 //--------------------------------------------------------------------------------------------------
 1076 /**
 1077  * Request the avcServer to close a session.
 1078  *
 1079  */
 1080 //--------------------------------------------------------------------------------------------------
 1081 void le_avdata_ReleaseSession
 1082 (
 1083     le_avdata_RequestSessionObjRef_t requestRef
 1084         ///< [IN] Reference to a previously opened AV session.
 1085 );
 1086 
 1087 /** @} **/
 1088 
 1089 #endif // LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
le_avdata_DeleteRecord
void le_avdata_DeleteRecord(le_avdata_RecordRef_t recordRef)
le_avdata_RecordRef_t
struct le_avdata_Record * le_avdata_RecordRef_t
Definition: le_avdata_common.h:158
le_avdata_RecordInt
le_result_t le_avdata_RecordInt(le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, int32_t value, uint64_t timestamp)
le_avdata_RemoveSessionStateHandler
void le_avdata_RemoveSessionStateHandler(le_avdata_SessionStateHandlerRef_t handlerRef)
le_avdata_DisconnectService
void le_avdata_DisconnectService(void)
le_result_t
le_result_t
Definition: le_basics.h:46
le_avdata_SetNull
le_result_t le_avdata_SetNull(const char *LE_NONNULL path)
le_avdata_DisconnectHandler_t
void(* le_avdata_DisconnectHandler_t)(void *)
Definition: le_avdata_interface.h:309
le_avdata_GetStringArg
le_result_t le_avdata_GetStringArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, char *strArg, size_t strArgSize)
le_avdata_SetString
le_result_t le_avdata_SetString(const char *LE_NONNULL path, const char *LE_NONNULL value)
le_avdata_RecordFloat
le_result_t le_avdata_RecordFloat(le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, double value, uint64_t timestamp)
le_avdata_RecordString
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_avdata_GetInt
le_result_t le_avdata_GetInt(const char *LE_NONNULL path, int32_t *valuePtr)
le_avdata_SetInt
le_result_t le_avdata_SetInt(const char *LE_NONNULL path, int32_t value)
le_avdata_RemoveResourceEventHandler
void le_avdata_RemoveResourceEventHandler(le_avdata_ResourceEventHandlerRef_t handlerRef)
le_avdata_SetServerDisconnectHandler
LE_FULL_API void le_avdata_SetServerDisconnectHandler(le_avdata_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_avdata_AccessMode_t
le_avdata_AccessMode_t
Definition: le_avdata_common.h:62
le_avdata_GetIntArg
le_result_t le_avdata_GetIntArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, int32_t *intArgPtr)
le_avdata_SetNamespace
le_result_t le_avdata_SetNamespace(le_avdata_Namespace_t _namespace)
le_avdata_CreateResource
le_result_t le_avdata_CreateResource(const char *LE_NONNULL path, le_avdata_AccessMode_t accessMode)
le_avdata_ConnectService
void le_avdata_ConnectService(void)
le_avdata_ReplyExecResult
void le_avdata_ReplyExecResult(le_avdata_ArgumentListRef_t argumentListRef, le_result_t result)
le_avdata_common.h
le_avdata_SetFloat
le_result_t le_avdata_SetFloat(const char *LE_NONNULL path, double value)
le_avdata_RecordBool
le_result_t le_avdata_RecordBool(le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, bool value, uint64_t timestamp)
le_avdata_ResourceEventHandlerRef_t
struct le_avdata_ResourceEventHandler * le_avdata_ResourceEventHandlerRef_t
Definition: le_avdata_common.h:150
le_avdata_AddSessionStateHandler
le_avdata_SessionStateHandlerRef_t le_avdata_AddSessionStateHandler(le_avdata_SessionStateHandlerFunc_t handlerPtr, void *contextPtr)
le_avdata_RequestSession
le_avdata_RequestSessionObjRef_t le_avdata_RequestSession(void)
le_avdata_GetBool
le_result_t le_avdata_GetBool(const char *LE_NONNULL path, bool *valuePtr)
le_avdata_SessionStateHandlerRef_t
struct le_avdata_SessionStateHandler * le_avdata_SessionStateHandlerRef_t
Definition: le_avdata_common.h:189
le_avdata_PushStream
le_result_t le_avdata_PushStream(const char *LE_NONNULL path, int fd, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
le_avdata_GetFloatArg
le_result_t le_avdata_GetFloatArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, double *floatArgPtr)
le_avdata_TryConnectService
le_result_t le_avdata_TryConnectService(void)
le_avdata_ReleaseSession
void le_avdata_ReleaseSession(le_avdata_RequestSessionObjRef_t requestRef)
le_avdata_CallbackResultFunc_t
void(* le_avdata_CallbackResultFunc_t)(le_avdata_PushStatus_t status, void *contextPtr)
Definition: le_avdata_common.h:217
le_avdata_PushRecord
le_result_t le_avdata_PushRecord(le_avdata_RecordRef_t recordRef, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
legato.h
le_avdata_ResourceHandlerFunc_t
void(* le_avdata_ResourceHandlerFunc_t)(const char *LE_NONNULL path, le_avdata_AccessType_t accessType, le_avdata_ArgumentListRef_t argumentListRef, void *contextPtr)
Definition: le_avdata_common.h:200
le_avdata_Push
le_result_t le_avdata_Push(const char *LE_NONNULL path, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
le_avdata_AddResourceEventHandler
le_avdata_ResourceEventHandlerRef_t le_avdata_AddResourceEventHandler(const char *LE_NONNULL path, le_avdata_ResourceHandlerFunc_t handlerPtr, void *contextPtr)
le_avdata_GetBoolArg
le_result_t le_avdata_GetBoolArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, bool *boolArgPtr)
le_avdata_CreateRecord
le_avdata_RecordRef_t le_avdata_CreateRecord(void)
le_avdata_RequestSessionObjRef_t
struct le_avdata_RequestSessionObj * le_avdata_RequestSessionObjRef_t
Definition: le_avdata_common.h:166
le_avdata_SetBool
le_result_t le_avdata_SetBool(const char *LE_NONNULL path, bool value)
le_avdata_GetFloat
le_result_t le_avdata_GetFloat(const char *LE_NONNULL path, double *valuePtr)
le_avdata_SessionStateHandlerFunc_t
void(* le_avdata_SessionStateHandlerFunc_t)(le_avdata_SessionState_t sessionState, void *contextPtr)
Definition: le_avdata_common.h:230
le_avdata_ArgumentListRef_t
struct le_avdata_ArgumentList * le_avdata_ArgumentListRef_t
Definition: le_avdata_common.h:142
le_avdata_GetStringArgLength
le_result_t le_avdata_GetStringArgLength(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, int32_t *strArgLenPtr)
le_avdata_GetString
le_result_t le_avdata_GetString(const char *LE_NONNULL path, char *value, size_t valueSize)
le_avdata_Namespace_t
le_avdata_Namespace_t
Definition: le_avdata_common.h:90