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 //--------------------------------------------------------------------------------------------------
  301 /**
  302  * Type for handler called when a server disconnects.
  303  */
  304 //--------------------------------------------------------------------------------------------------
  305 typedef void (*le_avdata_DisconnectHandler_t)(void *);
  306 
  307 //--------------------------------------------------------------------------------------------------
  308 /**
  309  *
  310  * Connect the current client thread to the service providing this API. Block until the service is
  311  * available.
  312  *
  313  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  314  * called before any other functions in this API.  Normally, ConnectService is automatically called
  315  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  316  *
  317  * This function is created automatically.
  318  */
  319 //--------------------------------------------------------------------------------------------------
  320 void le_avdata_ConnectService
  321 (
  322     void
  323 );
  324 
  325 //--------------------------------------------------------------------------------------------------
  326 /**
  327  *
  328  * Try to connect the current client thread to the service providing this API. Return with an error
  329  * if the service is not available.
  330  *
  331  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  332  * called before any other functions in this API.  Normally, ConnectService is automatically called
  333  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  334  *
  335  * This function is created automatically.
  336  *
  337  * @return
  338  *  - LE_OK if the client connected successfully to the service.
  339  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  340  *    bound.
  341  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  342  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  343  */
  344 //--------------------------------------------------------------------------------------------------
  345 le_result_t le_avdata_TryConnectService
  346 (
  347     void
  348 );
  349 
  350 //--------------------------------------------------------------------------------------------------
  351 /**
  352  * Set handler called when server disconnection is detected.
  353  *
  354  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  355  * to continue without exiting, it should call longjmp() from inside the handler.
  356  */
  357 //--------------------------------------------------------------------------------------------------
  358 LE_FULL_API void le_avdata_SetServerDisconnectHandler
  359 (
  360     le_avdata_DisconnectHandler_t disconnectHandler,
  361     void *contextPtr
  362 );
  363 
  364 //--------------------------------------------------------------------------------------------------
  365 /**
  366  *
  367  * Disconnect the current client thread from the service providing this API.
  368  *
  369  * Normally, this function doesn't need to be called. After this function is called, there's no
  370  * longer a connection to the service, and the functions in this API can't be used. For details, see
  371  * @ref apiFilesC_client.
  372  *
  373  * This function is created automatically.
  374  */
  375 //--------------------------------------------------------------------------------------------------
  376 void le_avdata_DisconnectService
  377 (
  378     void
  379 );
  380 
  381 
  382 //--------------------------------------------------------------------------------------------------
  383 /**
  384  * Resource access modes:
  385  *   - Variable: read (server), read/write (client)
  386  *   - Setting: read/write (server), read/write (client)
  387  *   - Command: execute (server)
  388  */
  389 //--------------------------------------------------------------------------------------------------
  390 
  391 
  392 //--------------------------------------------------------------------------------------------------
  393 /**
  394  * Resource access types
  395  */
  396 //--------------------------------------------------------------------------------------------------
  397 
  398 
  399 //--------------------------------------------------------------------------------------------------
  400 /**
  401  * Resource namespace
  402  */
  403 //--------------------------------------------------------------------------------------------------
  404 
  405 
  406 //--------------------------------------------------------------------------------------------------
  407 /**
  408  * Data types
  409  */
  410 //--------------------------------------------------------------------------------------------------
  411 
  412 
  413 //--------------------------------------------------------------------------------------------------
  414 /**
  415  * Status of the data push
  416  * @todo Provide additional status to troubleshoot delivery problems
  417  */
  418 //--------------------------------------------------------------------------------------------------
  419 
  420 
  421 //--------------------------------------------------------------------------------------------------
  422 /**
  423  * Argument list reference, for command only.
  424  */
  425 //--------------------------------------------------------------------------------------------------
  426 
  427 
  428 //--------------------------------------------------------------------------------------------------
  429 /**
  430  * Handler for resource activity. Note that the path returned by this event follows the unix format
  431  * (e.g. "/a/b/c") even if the app uses the URL format (e.g "a.b.c") when registering
  432  * the handler.
  433  */
  434 //--------------------------------------------------------------------------------------------------
  435 
  436 
  437 //--------------------------------------------------------------------------------------------------
  438 /**
  439  * Handler for pushing data result.
  440  */
  441 //--------------------------------------------------------------------------------------------------
  442 
  443 
  444 //--------------------------------------------------------------------------------------------------
  445 /**
  446  * Reference type used by Add/Remove functions for EVENT 'le_avdata_ResourceEvent'
  447  */
  448 //--------------------------------------------------------------------------------------------------
  449 
  450 
  451 //--------------------------------------------------------------------------------------------------
  452 /**
  453  * A record reference
  454  */
  455 //--------------------------------------------------------------------------------------------------
  456 
  457 
  458 //--------------------------------------------------------------------------------------------------
  459 /**
  460  * Reference returned by RequestSession function and used by ReleaseSession function
  461  */
  462 //--------------------------------------------------------------------------------------------------
  463 
  464 
  465 //--------------------------------------------------------------------------------------------------
  466 /**
  467  * AVMS session state
  468  */
  469 //--------------------------------------------------------------------------------------------------
  470 
  471 
  472 //--------------------------------------------------------------------------------------------------
  473 /**
  474  * Handler for AV session changes
  475  */
  476 //--------------------------------------------------------------------------------------------------
  477 
  478 
  479 //--------------------------------------------------------------------------------------------------
  480 /**
  481  * Reference type used by Add/Remove functions for EVENT 'le_avdata_SessionState'
  482  */
  483 //--------------------------------------------------------------------------------------------------
  484 
  485 
  486 //--------------------------------------------------------------------------------------------------
  487 /**
  488  * Add handler function for EVENT 'le_avdata_ResourceEvent'
  489  *
  490  * Upon resource access on the server side, the registered handler is called.
  491  *
  492  * For "settings" (read/write), the same handler is called for both read and write access.
  493  *
  494  * For "commands", the handler function must call the "ReplyExecResult" function to send the command
  495  * execution result back to the AVC daemon (which then sends the proper response back to the AV
  496  * server).
  497  */
  498 //--------------------------------------------------------------------------------------------------
  499 le_avdata_ResourceEventHandlerRef_t le_avdata_AddResourceEventHandler
  500 (
  501     const char* LE_NONNULL path,
  502         ///< [IN]
  503     le_avdata_ResourceHandlerFunc_t handlerPtr,
  504         ///< [IN]
  505     void* contextPtr
  506         ///< [IN]
  507 );
  508 
  509 //--------------------------------------------------------------------------------------------------
  510 /**
  511  * Remove handler function for EVENT 'le_avdata_ResourceEvent'
  512  */
  513 //--------------------------------------------------------------------------------------------------
  514 void le_avdata_RemoveResourceEventHandler
  515 (
  516     le_avdata_ResourceEventHandlerRef_t handlerRef
  517         ///< [IN]
  518 );
  519 
  520 //--------------------------------------------------------------------------------------------------
  521 /**
  522  * Create an asset data with the provided path. Note that asset data type and value are determined
  523  * upon the first call to a Set function. When an asset data is created, it contains a null value,
  524  * represented by the data type of none.
  525  *
  526  * @return:
  527  *      - LE_OK on success
  528  *      - LE_DUPLICATE if path has already been called by CreateResource before, or path is parent
  529  *        or child to an existing Asset Data path.
  530  *      - LE_FAULT on any other error.
  531  */
  532 //--------------------------------------------------------------------------------------------------
  533 le_result_t le_avdata_CreateResource
  534 (
  535     const char* LE_NONNULL path,
  536         ///< [IN]
  537     le_avdata_AccessMode_t accessMode
  538         ///< [IN]
  539 );
  540 
  541 //--------------------------------------------------------------------------------------------------
  542 /**
  543  * Sets the namespace for asset data.
  544  *
  545  * @return:
  546  *      - LE_OK on success
  547  *      - LE_BAD_PARAMETER if the namespace is unknown
  548  */
  549 //--------------------------------------------------------------------------------------------------
  550 le_result_t le_avdata_SetNamespace
  551 (
  552     le_avdata_Namespace_t _namespace
  553         ///< [IN]
  554 );
  555 
  556 //--------------------------------------------------------------------------------------------------
  557 /**
  558  * Sets an asset data to contain a null value, represented by the data type of none.
  559  *
  560  * @return:
  561  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  562  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  563  *      - LE_OK - access successful.
  564  */
  565 //--------------------------------------------------------------------------------------------------
  566 le_result_t le_avdata_SetNull
  567 (
  568     const char* LE_NONNULL path
  569         ///< [IN]
  570 );
  571 
  572 //--------------------------------------------------------------------------------------------------
  573 /**
  574  * Gets the integer value of an asset data.
  575  *
  576  * @return:
  577  *      - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
  578  *      - LE_UNAVAILABLE - asset data contains null value
  579  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  580  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  581  *      - LE_OK - access successful.
  582  */
  583 //--------------------------------------------------------------------------------------------------
  584 le_result_t le_avdata_GetInt
  585 (
  586     const char* LE_NONNULL path,
  587         ///< [IN]
  588     int32_t* valuePtr
  589         ///< [OUT]
  590 );
  591 
  592 //--------------------------------------------------------------------------------------------------
  593 /**
  594  * Sets an asset data to an integer value.
  595  *
  596  * @return:
  597  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  598  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  599  *      - LE_OK - access successful.
  600  */
  601 //--------------------------------------------------------------------------------------------------
  602 le_result_t le_avdata_SetInt
  603 (
  604     const char* LE_NONNULL path,
  605         ///< [IN]
  606     int32_t value
  607         ///< [IN]
  608 );
  609 
  610 //--------------------------------------------------------------------------------------------------
  611 /**
  612  * Gets the float value of an asset data.
  613  *
  614  * @return:
  615  *      - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
  616  *      - LE_UNAVAILABLE - asset data contains null value
  617  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  618  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  619  *      - LE_OK - access successful.
  620  */
  621 //--------------------------------------------------------------------------------------------------
  622 le_result_t le_avdata_GetFloat
  623 (
  624     const char* LE_NONNULL path,
  625         ///< [IN]
  626     double* valuePtr
  627         ///< [OUT]
  628 );
  629 
  630 //--------------------------------------------------------------------------------------------------
  631 /**
  632  * Sets an asset data to a float value.
  633  *
  634  * @return:
  635  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  636  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  637  *      - LE_OK - access successful.
  638  */
  639 //--------------------------------------------------------------------------------------------------
  640 le_result_t le_avdata_SetFloat
  641 (
  642     const char* LE_NONNULL path,
  643         ///< [IN]
  644     double value
  645         ///< [IN]
  646 );
  647 
  648 //--------------------------------------------------------------------------------------------------
  649 /**
  650  * Gets the bool value of an asset data.
  651  *
  652  * @return:
  653  *      - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
  654  *      - LE_UNAVAILABLE - asset data contains null value
  655  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  656  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  657  *      - LE_OK - access successful.
  658  */
  659 //--------------------------------------------------------------------------------------------------
  660 le_result_t le_avdata_GetBool
  661 (
  662     const char* LE_NONNULL path,
  663         ///< [IN]
  664     bool* valuePtr
  665         ///< [OUT]
  666 );
  667 
  668 //--------------------------------------------------------------------------------------------------
  669 /**
  670  * Sets an asset data to a bool value.
  671  *
  672  * @return:
  673  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  674  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  675  *      - LE_OK - access successful.
  676  */
  677 //--------------------------------------------------------------------------------------------------
  678 le_result_t le_avdata_SetBool
  679 (
  680     const char* LE_NONNULL path,
  681         ///< [IN]
  682     bool value
  683         ///< [IN]
  684 );
  685 
  686 //--------------------------------------------------------------------------------------------------
  687 /**
  688  * Gets the string value of an asset data.
  689  *
  690  * @return:
  691  *      - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
  692  *      - LE_UNAVAILABLE - asset data contains null value
  693  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  694  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  695  *      - LE_OVERFLOW - asset data length exceeds the maximum length
  696  *      - LE_OK - access successful
  697  */
  698 //--------------------------------------------------------------------------------------------------
  699 le_result_t le_avdata_GetString
  700 (
  701     const char* LE_NONNULL path,
  702         ///< [IN]
  703     char* value,
  704         ///< [OUT]
  705     size_t valueSize
  706         ///< [IN]
  707 );
  708 
  709 //--------------------------------------------------------------------------------------------------
  710 /**
  711  * Sets an asset data to a string value.
  712  *
  713  * @return:
  714  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  715  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  716  *      - LE_OK - access successful.
  717  */
  718 //--------------------------------------------------------------------------------------------------
  719 le_result_t le_avdata_SetString
  720 (
  721     const char* LE_NONNULL path,
  722         ///< [IN]
  723     const char* LE_NONNULL value
  724         ///< [IN]
  725 );
  726 
  727 //--------------------------------------------------------------------------------------------------
  728 /**
  729  * Get the bool argument with the specified name.
  730  *
  731  * @return:
  732  *      - LE_OK on success
  733  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  734  */
  735 //--------------------------------------------------------------------------------------------------
  736 le_result_t le_avdata_GetBoolArg
  737 (
  738     le_avdata_ArgumentListRef_t argumentListRef,
  739         ///< [IN]
  740     const char* LE_NONNULL argName,
  741         ///< [IN]
  742     bool* boolArgPtr
  743         ///< [OUT]
  744 );
  745 
  746 //--------------------------------------------------------------------------------------------------
  747 /**
  748  * Get the float argument with the specified name.
  749  *
  750  * @return:
  751  *      - LE_OK on success
  752  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  753  */
  754 //--------------------------------------------------------------------------------------------------
  755 le_result_t le_avdata_GetFloatArg
  756 (
  757     le_avdata_ArgumentListRef_t argumentListRef,
  758         ///< [IN]
  759     const char* LE_NONNULL argName,
  760         ///< [IN]
  761     double* floatArgPtr
  762         ///< [OUT]
  763 );
  764 
  765 //--------------------------------------------------------------------------------------------------
  766 /**
  767  * Get the int argument with the specified name.
  768  *
  769  * @return:
  770  *      - LE_OK on success
  771  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  772  */
  773 //--------------------------------------------------------------------------------------------------
  774 le_result_t le_avdata_GetIntArg
  775 (
  776     le_avdata_ArgumentListRef_t argumentListRef,
  777         ///< [IN]
  778     const char* LE_NONNULL argName,
  779         ///< [IN]
  780     int32_t* intArgPtr
  781         ///< [OUT]
  782 );
  783 
  784 //--------------------------------------------------------------------------------------------------
  785 /**
  786  * Get the string argument with the specified name.
  787  *
  788  * @return:
  789  *      - LE_OK on success
  790  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API
  791  *      - LE_OVERFLOW - argument length exceeds the maximum length
  792  */
  793 //--------------------------------------------------------------------------------------------------
  794 le_result_t le_avdata_GetStringArg
  795 (
  796     le_avdata_ArgumentListRef_t argumentListRef,
  797         ///< [IN]
  798     const char* LE_NONNULL argName,
  799         ///< [IN]
  800     char* strArg,
  801         ///< [OUT]
  802     size_t strArgSize
  803         ///< [IN]
  804 );
  805 
  806 //--------------------------------------------------------------------------------------------------
  807 /**
  808  * Get the length (excluding terminating null byte) of the string argument of the specified name.
  809  *
  810  * @return:
  811  *      - LE_OK on success
  812  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  813  */
  814 //--------------------------------------------------------------------------------------------------
  815 le_result_t le_avdata_GetStringArgLength
  816 (
  817     le_avdata_ArgumentListRef_t argumentListRef,
  818         ///< [IN]
  819     const char* LE_NONNULL argName,
  820         ///< [IN]
  821     int32_t* strArgLenPtr
  822         ///< [OUT]
  823 );
  824 
  825 //--------------------------------------------------------------------------------------------------
  826 /**
  827  * Reply command execution result to AVC Daemon, which can then respond to AV server. This function
  828  * MUST be called at the end of a command execution, in order for AV server to be notified about the
  829  * execution status.
  830  */
  831 //--------------------------------------------------------------------------------------------------
  832 void le_avdata_ReplyExecResult
  833 (
  834     le_avdata_ArgumentListRef_t argumentListRef,
  835         ///< [IN]
  836     le_result_t result
  837         ///< [IN]
  838 );
  839 
  840 //--------------------------------------------------------------------------------------------------
  841 /**
  842  * Push asset data to the server.
  843  *
  844  * @return:
  845  *      - LE_OK on success
  846  *      - LE_NOT_FOUND if the provided path doesn't exist
  847  *      - LE_BUSY if push service is busy. Data added to queue list for later push
  848  *      - LE_OVERFLOW if data size exceeds the maximum allowed size
  849  *      - LE_NO_MEMORY if push queue is full, try again later
  850  *      - LE_FAULT on any other error
  851  */
  852 //--------------------------------------------------------------------------------------------------
  853 le_result_t le_avdata_Push
  854 (
  855     const char* LE_NONNULL path,
  856         ///< [IN]
  857     le_avdata_CallbackResultFunc_t handlerPtr,
  858         ///< [IN]
  859     void* contextPtr
  860         ///< [IN]
  861 );
  862 
  863 //--------------------------------------------------------------------------------------------------
  864 /**
  865  * Push data dump to a specified path on the server.
  866  *
  867  * @return:
  868  *      - LE_OK on success
  869  *      - LE_BUSY if push service is busy. Data added to queue list for later push
  870  *      - LE_OVERFLOW if data size exceeds the maximum allowed size
  871  *      - LE_NO_MEMORY if push queue is full, try again later
  872  *      - LE_FAULT on any other error
  873  */
  874 //--------------------------------------------------------------------------------------------------
  875 le_result_t le_avdata_PushStream
  876 (
  877     const char* LE_NONNULL path,
  878         ///< [IN]
  879     int fd,
  880         ///< [IN]
  881     le_avdata_CallbackResultFunc_t handlerPtr,
  882         ///< [IN]
  883     void* contextPtr
  884         ///< [IN]
  885 );
  886 
  887 //--------------------------------------------------------------------------------------------------
  888 /**
  889  * Create a timeseries record
  890  *
  891  * @return Reference to the record
  892  */
  893 //--------------------------------------------------------------------------------------------------
  894 le_avdata_RecordRef_t le_avdata_CreateRecord
  895 (
  896     void
  897 );
  898 
  899 //--------------------------------------------------------------------------------------------------
  900 /**
  901  * Delete a timeseries record
  902  */
  903 //--------------------------------------------------------------------------------------------------
  904 void le_avdata_DeleteRecord
  905 (
  906     le_avdata_RecordRef_t recordRef
  907         ///< [IN]
  908 );
  909 
  910 //--------------------------------------------------------------------------------------------------
  911 /**
  912  * Accumulate int data
  913  *
  914  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
  915  *
  916  * @return:
  917  *      - LE_OK on success
  918  *      - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  919  *      - LE_FAULT on any other error
  920  */
  921 //--------------------------------------------------------------------------------------------------
  922 le_result_t le_avdata_RecordInt
  923 (
  924     le_avdata_RecordRef_t recordRef,
  925         ///< [IN]
  926     const char* LE_NONNULL path,
  927         ///< [IN]
  928     int32_t value,
  929         ///< [IN]
  930     uint64_t timestamp
  931         ///< [IN]
  932 );
  933 
  934 //--------------------------------------------------------------------------------------------------
  935 /**
  936  * Accumulate float data
  937  *
  938  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
  939  *
  940  * @return:
  941  *      - LE_OK on success
  942  *      - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  943  *      - LE_FAULT on any other error
  944  */
  945 //--------------------------------------------------------------------------------------------------
  946 le_result_t le_avdata_RecordFloat
  947 (
  948     le_avdata_RecordRef_t recordRef,
  949         ///< [IN]
  950     const char* LE_NONNULL path,
  951         ///< [IN]
  952     double value,
  953         ///< [IN]
  954     uint64_t timestamp
  955         ///< [IN]
  956 );
  957 
  958 //--------------------------------------------------------------------------------------------------
  959 /**
  960  * Accumulate boolean data
  961  *
  962  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
  963  *
  964  * @return:
  965  *      - LE_OK on success
  966  *      - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  967  *      - LE_FAULT on any other error
  968  */
  969 //--------------------------------------------------------------------------------------------------
  970 le_result_t le_avdata_RecordBool
  971 (
  972     le_avdata_RecordRef_t recordRef,
  973         ///< [IN]
  974     const char* LE_NONNULL path,
  975         ///< [IN]
  976     bool value,
  977         ///< [IN]
  978     uint64_t timestamp
  979         ///< [IN]
  980 );
  981 
  982 //--------------------------------------------------------------------------------------------------
  983 /**
  984  * Accumulate string data
  985  *
  986  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
  987  *
  988  * @return:
  989  *      - LE_OK on success
  990  *      - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  991  *      - LE_FAULT on any other error
  992  */
  993 //--------------------------------------------------------------------------------------------------
  994 le_result_t le_avdata_RecordString
  995 (
  996     le_avdata_RecordRef_t recordRef,
  997         ///< [IN]
  998     const char* LE_NONNULL path,
  999         ///< [IN]
 1000     const char* LE_NONNULL value,
 1001         ///< [IN]
 1002     uint64_t timestamp
 1003         ///< [IN]
 1004 );
 1005 
 1006 //--------------------------------------------------------------------------------------------------
 1007 /**
 1008  * Push record to the server
 1009  *
 1010  ** @return:
 1011  *      - LE_OK on success
 1012  *      - LE_BUSY if push service is busy. Data added to queue list for later push
 1013  *      - LE_OVERFLOW if data size exceeds the maximum allowed size
 1014  *      - LE_NO_MEMORY if push queue is full, try again later
 1015  *      - LE_FAULT on any other error
 1016  *
 1017  * * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1018  *       function will not return.
 1019  */
 1020 //--------------------------------------------------------------------------------------------------
 1021 le_result_t le_avdata_PushRecord
 1022 (
 1023     le_avdata_RecordRef_t recordRef,
 1024         ///< [IN]
 1025     le_avdata_CallbackResultFunc_t handlerPtr,
 1026         ///< [IN]
 1027     void* contextPtr
 1028         ///< [IN]
 1029 );
 1030 
 1031 //--------------------------------------------------------------------------------------------------
 1032 /**
 1033  * Add handler function for EVENT 'le_avdata_SessionState'
 1034  *
 1035  * This event provides information on AV session state changes
 1036  */
 1037 //--------------------------------------------------------------------------------------------------
 1038 le_avdata_SessionStateHandlerRef_t le_avdata_AddSessionStateHandler
 1039 (
 1040     le_avdata_SessionStateHandlerFunc_t handlerPtr,
 1041         ///< [IN]
 1042     void* contextPtr
 1043         ///< [IN]
 1044 );
 1045 
 1046 //--------------------------------------------------------------------------------------------------
 1047 /**
 1048  * Remove handler function for EVENT 'le_avdata_SessionState'
 1049  */
 1050 //--------------------------------------------------------------------------------------------------
 1051 void le_avdata_RemoveSessionStateHandler
 1052 (
 1053     le_avdata_SessionStateHandlerRef_t handlerRef
 1054         ///< [IN]
 1055 );
 1056 
 1057 //--------------------------------------------------------------------------------------------------
 1058 /**
 1059  * Request the avcServer to open a session.
 1060  *
 1061  * @return
 1062  *      - SessionRef if session request succeeded
 1063  *      - NULL if session request failed
 1064  */
 1065 //--------------------------------------------------------------------------------------------------
 1066 le_avdata_RequestSessionObjRef_t le_avdata_RequestSession
 1067 (
 1068     void
 1069 );
 1070 
 1071 //--------------------------------------------------------------------------------------------------
 1072 /**
 1073  * Request the avcServer to close a session.
 1074  *
 1075  */
 1076 //--------------------------------------------------------------------------------------------------
 1077 void le_avdata_ReleaseSession
 1078 (
 1079     le_avdata_RequestSessionObjRef_t requestRef
 1080         ///< [IN] Reference to a previously opened AV session.
 1081 );
 1082 
 1083 #endif // LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
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_GetInt
le_result_t le_avdata_GetInt(const char *LE_NONNULL path, int32_t *valuePtr)
le_avdata_GetFloat
le_result_t le_avdata_GetFloat(const char *LE_NONNULL path, double *valuePtr)
le_avdata_CreateResource
le_result_t le_avdata_CreateResource(const char *LE_NONNULL path, le_avdata_AccessMode_t accessMode)
le_result_t
le_result_t
Definition: le_basics.h:45
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_SetNull
le_result_t le_avdata_SetNull(const char *LE_NONNULL path)
le_avdata_AddSessionStateHandler
le_avdata_SessionStateHandlerRef_t le_avdata_AddSessionStateHandler(le_avdata_SessionStateHandlerFunc_t handlerPtr, void *contextPtr)
le_avdata_ReleaseSession
void le_avdata_ReleaseSession(le_avdata_RequestSessionObjRef_t requestRef)
le_avdata_RemoveResourceEventHandler
void le_avdata_RemoveResourceEventHandler(le_avdata_ResourceEventHandlerRef_t handlerRef)
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_DisconnectService
void le_avdata_DisconnectService(void)
le_avdata_GetBool
le_result_t le_avdata_GetBool(const char *LE_NONNULL path, bool *valuePtr)
le_avdata_PushRecord
le_result_t le_avdata_PushRecord(le_avdata_RecordRef_t recordRef, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
le_avdata_ReplyExecResult
void le_avdata_ReplyExecResult(le_avdata_ArgumentListRef_t argumentListRef, le_result_t result)
le_avdata_Push
le_result_t le_avdata_Push(const char *LE_NONNULL path, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
le_avdata_GetStringArgLength
le_result_t le_avdata_GetStringArgLength(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, int32_t *strArgLenPtr)
le_avdata_RequestSession
le_avdata_RequestSessionObjRef_t le_avdata_RequestSession(void)
le_avdata_DisconnectHandler_t
void(* le_avdata_DisconnectHandler_t)(void *)
Definition: le_avdata_interface.h:305
le_avdata_SetString
le_result_t le_avdata_SetString(const char *LE_NONNULL path, const char *LE_NONNULL value)
le_avdata_GetBoolArg
le_result_t le_avdata_GetBoolArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, bool *boolArgPtr)
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_RecordBool
le_result_t le_avdata_RecordBool(le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, bool value, uint64_t timestamp)
le_avdata_SetServerDisconnectHandler
LE_FULL_API void le_avdata_SetServerDisconnectHandler(le_avdata_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_avdata_ConnectService
void le_avdata_ConnectService(void)
le_avdata_GetString
le_result_t le_avdata_GetString(const char *LE_NONNULL path, char *value, size_t valueSize)
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_TryConnectService
le_result_t le_avdata_TryConnectService(void)
le_avdata_SetFloat
le_result_t le_avdata_SetFloat(const char *LE_NONNULL path, double value)
le_avdata_GetFloatArg
le_result_t le_avdata_GetFloatArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, double *floatArgPtr)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_avdata_SetNamespace
le_result_t le_avdata_SetNamespace(le_avdata_Namespace_t _namespace)
le_avdata_AddResourceEventHandler
le_avdata_ResourceEventHandlerRef_t le_avdata_AddResourceEventHandler(const char *LE_NONNULL path, le_avdata_ResourceHandlerFunc_t handlerPtr, void *contextPtr)
le_avdata_GetIntArg
le_result_t le_avdata_GetIntArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, int32_t *intArgPtr)
le_avdata_SetInt
le_result_t le_avdata_SetInt(const char *LE_NONNULL path, int32_t value)
le_avdata_CreateRecord
le_avdata_RecordRef_t le_avdata_CreateRecord(void)
le_avdata_DeleteRecord
void le_avdata_DeleteRecord(le_avdata_RecordRef_t recordRef)
le_avdata_SetBool
le_result_t le_avdata_SetBool(const char *LE_NONNULL path, bool value)
le_avdata_RemoveSessionStateHandler
void le_avdata_RemoveSessionStateHandler(le_avdata_SessionStateHandlerRef_t handlerRef)