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_data_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_data_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 an App to read/write the value, and can be read from the AV server.
   44  * - @b setting allowing the AirVantage server to read/write the value, and can be read by an App.
   45  * - @b command allowing the AirVantage server to invoke a function in the App.
   46  *
   47  * A field is referred to by a path, much like a path in Unix-like OSes. A path is separated by a
   48  * slash ("/"), a parent path @b cannot contain a field, and a parent path cannot contain a parent
   49  * path and a child path of the same name.
   50  *
   51  * Variable and setting fields also have types. The available field types are:
   52  * - string
   53  * - integer
   54  * - float
   55  * - boolean
   56  *
   57  * Variable and setting fields have no default values. When they are first created with the
   58  * le_avdata_CreateResource() , all values are "null". They can also be set to "null" values with
   59  * the le_avdata_SetNull() .
   60  *
   61  * Fields do not have a fixed data type, so any of the SetInt/Float/Bool/String can
   62  * be called for a certain field to change its value and its type. However, A
   63  * GetInt/Float/Bool/String API must be called on a field with the matching type. In other words,
   64  * a Get API does not perform type-casting.
   65  *
   66  * @note If a user enters a value 0 for float data type, an error will be returned (LE_NOT_FOUND),
   67  * as the system infers 0 as an integer value and the data type doesn't match.  0.0 needs to be set
   68  * for the float data type to be zero.
   69  *
   70  * @section le_avdata_field Field Values and Activity
   71  *
   72  * Set functions are available to set field values (including "null"). Get functions are
   73  * available to get field values.
   74  *
   75  * An App can register a handler so that it can be called when an activity occurs on a field.
   76  * This is optional for variable and setting fields, but is @b required for command fields.
   77  * Registered handlers are called only when activities from AV server occurs. Client activities do
   78  * not trigger handlers.
   79  *
   80  * A handler registered with a command field is invoked with an optional argument list sent from the
   81  * AirVantage server. The APIs GetInt/Float/Bool/StringArg and le_avdata_GetStringArgLength() are
   82  * available to extract the arguments in the handler definition. AV server does not send argument
   83  * lists for handlers registered with variable and setting fields.
   84  *
   85  * A handler registered with a command field must call the le_avdata_ReplyExecResult() at the end of
   86  * its definition, in order to reply the command execution result to the AV server.
   87  *
   88  * Sometimes instead of waiting for activity to occur on a field, users may want to have their
   89  * application notify the server of their asset data details. Asset data can also be pushed from
   90  * the device to the server by using le_avdata_Push().
   91  *
   92  * This code sample shows how to push asset data to the server (assuming session is opened)
   93  *
   94  * @code
   95  * static void PushCallbackHandler
   96  * (
   97  *     le_avdata_PushStatus_t status,
   98  *     void* contextPtr
   99  * )
  100  * {
  101  *     if (status == LE_AVDATA_PUSH_SUCCESS)
  102  *     {
  103  *         // data pushed successfully
  104  *     }
  105  * }
  106  *
  107  * COMPONENT_INIT
  108  * {
  109  *       le_result_t result;
  110  *       result = le_avdata_CreateResource("/livingRoom/sensor1", LE_AVDATA_ACCESS_VARIABLE);
  111  *       if (result != LE_OK)
  112  *       {
  113  *           LE_FATAL("Error in creating livingRoom resource.");
  114  *       }
  115  *
  116  *       result = le_avdata_SetInt("/livingRoom/sensor1", 5) == LE_OK);
  117  *       if (result != LE_OK)
  118  *       {
  119  *           LE_FATAL("Failed to set value for livingRoom resource.");
  120  *       }
  121  *
  122  *       le_avdata_Push("/livingRoom/sensor1", PushCallbackHandler, NULL);
  123  * }
  124  * @endcode
  125  *
  126  * If users simply want to push a data dump to the server without creating resources,
  127  * le_avdata_PushStream() is available.
  128  * @note The push stream API has a limit of 20K.
  129  *
  130  * @code
  131  * COMPONENT_INIT
  132  * {
  133  *       int fd = open("data.txt", O_RDONLY);
  134  *       if (fd == -1)
  135  *       {
  136  *          LE_FATAL("Failed to open file.");
  137  *       }
  138  *
  139  *       // The data dump sent to the server will be display under <Path>
  140  *       le_avdata_PushStream("<Path>", fd, PushCallbackHandler, NULL);
  141  * }
  142  * @endcode
  143  *
  144  * @section le_avdata_timeseries Time Series
  145  *
  146  * This feature enables user Apps to collect and keep in memory data when the device is off-line and
  147  * send the data to the AirVantage Server when the device is on-line.
  148  *
  149  * Time series records can be initialized using le_avdata_CreateRecord().
  150  * Data can be accumulated using the following data types along with a specified time stamp
  151  * (milliseconds elapsed since epoch).
  152  * - le_avdata_RecordInt()
  153  * - le_avdata_RecordFloat()
  154  * - le_avdata_RecordBool
  155  * - le_avdata_RecordString
  156  *
  157  * User apps can then open an @c avms session, and push the collected history data using
  158  * le_avdata_PushRecord(). The callback used when calling le_avdata_PushRecord() will indicate
  159  * whether the push has been successful or not.
  160  *
  161  * This code sample shows how to collect data and send to the server (assuming session is opened)
  162  *
  163  * @code
  164  *
  165  * static void PushCallbackHandler
  166  * (
  167  *     le_avdata_PushStatus_t status,
  168  *     void* contextPtr
  169  * )
  170  * {
  171  *     if (status == LE_AVDATA_PUSH_SUCCESS)
  172  *     {
  173  *         // data pushed successfully
  174  *     }
  175  * }
  176  *
  177  * static void SendData()
  178  * {
  179  *     struct timeval tv;
  180  *     uint64_t utcMilliSec;
  181  *     le_result_t result;
  182  *
  183  *     le_avdata_RecordRef_t recRef = le_avdata_CreateRecord();
  184  *
  185  *     gettimeofday(&tv, NULL);
  186  *     utcMilliSec = (uint64_t)(tv.tv_sec) * 1000 + (uint64_t)(tv.tv_usec) / 1000; // get current time
  187  *     result = le_avdata_RecordFloat(recRef, "speed", 0.08, utcMilliSec);
  188  *
  189  *     if (result == LE_OK)
  190  *     {
  191  *          le_avdata_PushRecord(recRef, PushCallbackHandler, NULL);
  192  *     }
  193  *
  194  *     le_avdata_DeleteRecord(recRef);
  195  * }
  196  * @endcode
  197  *
  198  * @section le_avdata_session User App Session Management
  199  *
  200  * An App can request to open a session and register a handler to get notified of a session
  201  * events. le_avdata_RequestSession() and le_avdata_ReleaseSession() can be used to
  202  * open a session and close a session respectively. If the session was initiated by an
  203  * user app, the session will be closed when all apps release their session reference.
  204  * le_avdata_AddSessionStateHandler() and le_avdata_RemoveSessionStateHandler() can be used to add
  205  * and remove notification handlers.
  206  *
  207  * @section le_avdata_fatal Fatal Behavior
  208  *
  209  * An invalid asset name or field name is treated as a fatal error (i.e. non-recoverable)
  210  * and will result in the client App being terminated.
  211  *
  212  * Copyright (C) Sierra Wireless Inc.
  213  */
  214 /**
  215  * @file le_avdata_interface.h
  216  *
  217  * Legato @ref c_le_avdata include file.
  218  *
  219  * Copyright (C) Sierra Wireless Inc.
  220  */
  221 
  222 #ifndef LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
  223 #define LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
  224 
  225 
  226 #include "legato.h"
  227 
  228 
  229 //--------------------------------------------------------------------------------------------------
  230 /**
  231  * Type for handler called when a server disconnects.
  232  */
  233 //--------------------------------------------------------------------------------------------------
  234 typedef void (*le_avdata_DisconnectHandler_t)(void *);
  235 
  236 //--------------------------------------------------------------------------------------------------
  237 /**
  238  *
  239  * Connect the current client thread to the service providing this API. Block until the service is
  240  * available.
  241  *
  242  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  243  * called before any other functions in this API.  Normally, ConnectService is automatically called
  244  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  245  *
  246  * This function is created automatically.
  247  */
  248 //--------------------------------------------------------------------------------------------------
  249 void le_avdata_ConnectService
  250 (
  251     void
  252 );
  253 
  254 //--------------------------------------------------------------------------------------------------
  255 /**
  256  *
  257  * Try to connect the current client thread to the service providing this API. Return with an error
  258  * if the service is not available.
  259  *
  260  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  261  * called before any other functions in this API.  Normally, ConnectService is automatically called
  262  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  263  *
  264  * This function is created automatically.
  265  *
  266  * @return
  267  *  - LE_OK if the client connected successfully to the service.
  268  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  269  *    bound.
  270  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  271  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  272  */
  273 //--------------------------------------------------------------------------------------------------
  274 le_result_t le_avdata_TryConnectService
  275 (
  276     void
  277 );
  278 
  279 //--------------------------------------------------------------------------------------------------
  280 /**
  281  * Set handler called when server disconnection is detected.
  282  *
  283  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  284  * to continue without exiting, it should call longjmp() from inside the handler.
  285  */
  286 //--------------------------------------------------------------------------------------------------
  287 void le_avdata_SetServerDisconnectHandler
  288 (
  289     le_avdata_DisconnectHandler_t disconnectHandler,
  290     void *contextPtr
  291 );
  292 
  293 //--------------------------------------------------------------------------------------------------
  294 /**
  295  *
  296  * Disconnect the current client thread from the service providing this API.
  297  *
  298  * Normally, this function doesn't need to be called. After this function is called, there's no
  299  * longer a connection to the service, and the functions in this API can't be used. For details, see
  300  * @ref apiFilesC_client.
  301  *
  302  * This function is created automatically.
  303  */
  304 //--------------------------------------------------------------------------------------------------
  305 void le_avdata_DisconnectService
  306 (
  307     void
  308 );
  309 
  310 
  311 //--------------------------------------------------------------------------------------------------
  312 /**
  313  * Define the maximum characters and bytes of a path name
  314  */
  315 //--------------------------------------------------------------------------------------------------
  316 #define LE_AVDATA_PATH_NAME_LEN 511
  317 
  318 //--------------------------------------------------------------------------------------------------
  319 /**
  320  */
  321 //--------------------------------------------------------------------------------------------------
  322 #define LE_AVDATA_PATH_NAME_BYTES 512
  323 
  324 //--------------------------------------------------------------------------------------------------
  325 /**
  326  * Define the maximum characters and bytes of a string
  327  */
  328 //--------------------------------------------------------------------------------------------------
  329 #define LE_AVDATA_STRING_VALUE_LEN 255
  330 
  331 //--------------------------------------------------------------------------------------------------
  332 /**
  333  */
  334 //--------------------------------------------------------------------------------------------------
  335 #define LE_AVDATA_STRING_VALUE_BYTES 256
  336 
  337 //--------------------------------------------------------------------------------------------------
  338 /**
  339  * Resource access modes.
  340  *   Variable: read (server), read/write (client)
  341  *   Setting: read/write (server), read (client)
  342  *   Command: execute (server)
  343  */
  344 //--------------------------------------------------------------------------------------------------
  345 typedef enum
  346 {
  347     LE_AVDATA_ACCESS_VARIABLE = 0,
  348         ///<
  349     LE_AVDATA_ACCESS_SETTING = 1,
  350         ///<
  351     LE_AVDATA_ACCESS_COMMAND = 2
  352         ///<
  353 }
  354 le_avdata_AccessMode_t;
  355 
  356 
  357 //--------------------------------------------------------------------------------------------------
  358 /**
  359  * Resource access types
  360  */
  361 //--------------------------------------------------------------------------------------------------
  362 typedef enum
  363 {
  364     LE_AVDATA_ACCESS_READ = 0x1,
  365     LE_AVDATA_ACCESS_WRITE = 0x2,
  366     LE_AVDATA_ACCESS_EXEC = 0x4
  367 }
  368 le_avdata_AccessType_t;
  369 
  370 
  371 //--------------------------------------------------------------------------------------------------
  372 /**
  373  * Data types
  374  */
  375 //--------------------------------------------------------------------------------------------------
  376 typedef enum
  377 {
  378     LE_AVDATA_DATA_TYPE_NONE = 0,
  379         ///<
  380     LE_AVDATA_DATA_TYPE_INT = 1,
  381         ///<
  382     LE_AVDATA_DATA_TYPE_FLOAT = 2,
  383         ///<
  384     LE_AVDATA_DATA_TYPE_BOOL = 3,
  385         ///<
  386     LE_AVDATA_DATA_TYPE_STRING = 4
  387         ///<
  388 }
  389 le_avdata_DataType_t;
  390 
  391 
  392 //--------------------------------------------------------------------------------------------------
  393 /**
  394  * Status of the data push (TODO: Provide additional status to troubleshoot delivery problems)
  395  */
  396 //--------------------------------------------------------------------------------------------------
  397 typedef enum
  398 {
  399     LE_AVDATA_PUSH_SUCCESS = 0,
  400         ///<
  401     LE_AVDATA_PUSH_FAILED = 1
  402         ///<
  403 }
  404 le_avdata_PushStatus_t;
  405 
  406 
  407 //--------------------------------------------------------------------------------------------------
  408 /**
  409  * Argument list reference, for command only.
  410  */
  411 //--------------------------------------------------------------------------------------------------
  412 typedef struct le_avdata_ArgumentList* le_avdata_ArgumentListRef_t;
  413 
  414 
  415 //--------------------------------------------------------------------------------------------------
  416 /**
  417  * Reference type used by Add/Remove functions for EVENT 'le_avdata_ResourceEvent'
  418  */
  419 //--------------------------------------------------------------------------------------------------
  420 typedef struct le_avdata_ResourceEventHandler* le_avdata_ResourceEventHandlerRef_t;
  421 
  422 
  423 //--------------------------------------------------------------------------------------------------
  424 /**
  425  * A record reference
  426  */
  427 //--------------------------------------------------------------------------------------------------
  428 typedef struct le_avdata_Record* le_avdata_RecordRef_t;
  429 
  430 
  431 //--------------------------------------------------------------------------------------------------
  432 /**
  433  * Reference returned by RequestSession function and used by ReleaseSession function
  434  */
  435 //--------------------------------------------------------------------------------------------------
  436 typedef struct le_avdata_RequestSessionObj* le_avdata_RequestSessionObjRef_t;
  437 
  438 
  439 //--------------------------------------------------------------------------------------------------
  440 /**
  441  * AVMS session state
  442  */
  443 //--------------------------------------------------------------------------------------------------
  444 typedef enum
  445 {
  446     LE_AVDATA_SESSION_STARTED = 0,
  447         ///< AVMS session started
  448     LE_AVDATA_SESSION_STOPPED = 1
  449         ///< AVMS session stopped
  450 }
  451 le_avdata_SessionState_t;
  452 
  453 
  454 //--------------------------------------------------------------------------------------------------
  455 /**
  456  * Reference type used by Add/Remove functions for EVENT 'le_avdata_SessionState'
  457  */
  458 //--------------------------------------------------------------------------------------------------
  459 typedef struct le_avdata_SessionStateHandler* le_avdata_SessionStateHandlerRef_t;
  460 
  461 
  462 //--------------------------------------------------------------------------------------------------
  463 /**
  464  * Handler for resource activity
  465  */
  466 //--------------------------------------------------------------------------------------------------
  467 typedef void (*le_avdata_ResourceHandlerFunc_t)
  468 (
  469     const char* LE_NONNULL path,
  470         ///<
  471     le_avdata_AccessType_t accessType,
  472         ///<
  473     le_avdata_ArgumentListRef_t argumentListRef,
  474         ///<
  475     void* contextPtr
  476         ///<
  477 );
  478 
  479 //--------------------------------------------------------------------------------------------------
  480 /**
  481  * Handler for pushing data result.
  482  */
  483 //--------------------------------------------------------------------------------------------------
  484 typedef void (*le_avdata_CallbackResultFunc_t)
  485 (
  486     le_avdata_PushStatus_t status,
  487         ///<
  488     void* contextPtr
  489         ///<
  490 );
  491 
  492 //--------------------------------------------------------------------------------------------------
  493 /**
  494  * Handler for AV session changes
  495  */
  496 //--------------------------------------------------------------------------------------------------
  497 typedef void (*le_avdata_SessionStateHandlerFunc_t)
  498 (
  499     le_avdata_SessionState_t sessionState,
  500         ///< Session started or stopped?
  501     void* contextPtr
  502         ///<
  503 );
  504 
  505 //--------------------------------------------------------------------------------------------------
  506 /**
  507  * Add handler function for EVENT 'le_avdata_ResourceEvent'
  508  *
  509  * Upon resource access on the server side, the registered handler is called.
  510  *
  511  * For "settings" (read/write), the same handler is called for both read and write access.
  512  *
  513  * For "commands", the handler function must call the "ReplyExecResult" function to send the command
  514  * execution result back to the AVC daemon (which then sends the proper response back to the AV
  515  * server).
  516  */
  517 //--------------------------------------------------------------------------------------------------
  518 le_avdata_ResourceEventHandlerRef_t le_avdata_AddResourceEventHandler
  519 (
  520     const char* LE_NONNULL path,
  521         ///< [IN]
  522     le_avdata_ResourceHandlerFunc_t handlerPtr,
  523         ///< [IN]
  524     void* contextPtr
  525         ///< [IN]
  526 );
  527 
  528 //--------------------------------------------------------------------------------------------------
  529 /**
  530  * Remove handler function for EVENT 'le_avdata_ResourceEvent'
  531  */
  532 //--------------------------------------------------------------------------------------------------
  533 void le_avdata_RemoveResourceEventHandler
  534 (
  535     le_avdata_ResourceEventHandlerRef_t handlerRef
  536         ///< [IN]
  537 );
  538 
  539 //--------------------------------------------------------------------------------------------------
  540 /**
  541  * Create an asset data with the provided path. Note that asset data type and value are determined
  542  * upon the first call to a Set function. When an asset data is created, it contains a null value,
  543  * represented by the data type of none.
  544  *
  545  * @return:
  546  *      - LE_OK on success
  547  *      - LE_DUPLICATE if path has already been called by CreateResource before, or path is parent
  548  *        or child to an existing Asset Data path.
  549  *      - LE_FAULT on any other error.
  550  */
  551 //--------------------------------------------------------------------------------------------------
  552 le_result_t le_avdata_CreateResource
  553 (
  554     const char* LE_NONNULL path,
  555         ///< [IN]
  556     le_avdata_AccessMode_t accessMode
  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_OK - access successful.
  700  */
  701 //--------------------------------------------------------------------------------------------------
  702 le_result_t le_avdata_GetString
  703 (
  704     const char* LE_NONNULL path,
  705         ///< [IN]
  706     char* value,
  707         ///< [OUT]
  708     size_t valueSize
  709         ///< [IN]
  710 );
  711 
  712 //--------------------------------------------------------------------------------------------------
  713 /**
  714  * Sets an asset data to a string value.
  715  *
  716  * @return:
  717  *      - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
  718  *      - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
  719  *      - LE_OK - access successful.
  720  */
  721 //--------------------------------------------------------------------------------------------------
  722 le_result_t le_avdata_SetString
  723 (
  724     const char* LE_NONNULL path,
  725         ///< [IN]
  726     const char* LE_NONNULL value
  727         ///< [IN]
  728 );
  729 
  730 //--------------------------------------------------------------------------------------------------
  731 /**
  732  * Get the bool argument with the specified name.
  733  *
  734  * @return:
  735  *      - LE_OK on success
  736  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  737  */
  738 //--------------------------------------------------------------------------------------------------
  739 le_result_t le_avdata_GetBoolArg
  740 (
  741     le_avdata_ArgumentListRef_t argumentListRef,
  742         ///< [IN]
  743     const char* LE_NONNULL argName,
  744         ///< [IN]
  745     bool* boolArgPtr
  746         ///< [OUT]
  747 );
  748 
  749 //--------------------------------------------------------------------------------------------------
  750 /**
  751  * Get the float argument with the specified name.
  752  *
  753  * @return:
  754  *      - LE_OK on success
  755  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  756  */
  757 //--------------------------------------------------------------------------------------------------
  758 le_result_t le_avdata_GetFloatArg
  759 (
  760     le_avdata_ArgumentListRef_t argumentListRef,
  761         ///< [IN]
  762     const char* LE_NONNULL argName,
  763         ///< [IN]
  764     double* floatArgPtr
  765         ///< [OUT]
  766 );
  767 
  768 //--------------------------------------------------------------------------------------------------
  769 /**
  770  * Get the int argument with the specified name.
  771  *
  772  * @return:
  773  *      - LE_OK on success
  774  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  775  */
  776 //--------------------------------------------------------------------------------------------------
  777 le_result_t le_avdata_GetIntArg
  778 (
  779     le_avdata_ArgumentListRef_t argumentListRef,
  780         ///< [IN]
  781     const char* LE_NONNULL argName,
  782         ///< [IN]
  783     int32_t* intArgPtr
  784         ///< [OUT]
  785 );
  786 
  787 //--------------------------------------------------------------------------------------------------
  788 /**
  789  * Get the string argument with the specified name.
  790  *
  791  * @return:
  792  *      - LE_OK on success
  793  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  794  */
  795 //--------------------------------------------------------------------------------------------------
  796 le_result_t le_avdata_GetStringArg
  797 (
  798     le_avdata_ArgumentListRef_t argumentListRef,
  799         ///< [IN]
  800     const char* LE_NONNULL argName,
  801         ///< [IN]
  802     char* strArg,
  803         ///< [OUT]
  804     size_t strArgSize
  805         ///< [IN]
  806 );
  807 
  808 //--------------------------------------------------------------------------------------------------
  809 /**
  810  * Get the length (excluding terminating null byte) of the string argument of the specified name.
  811  *
  812  * @return:
  813  *      - LE_OK on success
  814  *      - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
  815  */
  816 //--------------------------------------------------------------------------------------------------
  817 le_result_t le_avdata_GetStringArgLength
  818 (
  819     le_avdata_ArgumentListRef_t argumentListRef,
  820         ///< [IN]
  821     const char* LE_NONNULL argName,
  822         ///< [IN]
  823     int32_t* strArgLenPtr
  824         ///< [OUT]
  825 );
  826 
  827 //--------------------------------------------------------------------------------------------------
  828 /**
  829  * Reply command execution result to AVC Daemon, which can then respond to AV server. This function
  830  * MUST be called at the end of a command execution, in order for AV server to be notified about the
  831  * execution status.
  832  */
  833 //--------------------------------------------------------------------------------------------------
  834 void le_avdata_ReplyExecResult
  835 (
  836     le_avdata_ArgumentListRef_t argumentListRef,
  837         ///< [IN]
  838     le_result_t result
  839         ///< [IN]
  840 );
  841 
  842 //--------------------------------------------------------------------------------------------------
  843 /**
  844  * Push asset data to the server.
  845  *
  846  * @return:
  847  *      - LE_OK on success.
  848  *      - LE_NOT_FOUND if path doesn't exist.
  849  *      - LE_BUSY if push is queued and will pushed later automatically
  850  *      - LE_NOT_POSSIBLE if push queue is full, try again later
  851  *      - LE_FAULT on any other error
  852  */
  853 //--------------------------------------------------------------------------------------------------
  854 le_result_t le_avdata_Push
  855 (
  856     const char* LE_NONNULL path,
  857         ///< [IN]
  858     le_avdata_CallbackResultFunc_t handlerPtr,
  859         ///< [IN]
  860     void* contextPtr
  861         ///< [IN]
  862 );
  863 
  864 //--------------------------------------------------------------------------------------------------
  865 /**
  866  * Push data dump to a specified path on the server.
  867  *
  868  * @return:
  869  *      - LE_OK on success.
  870  *      - LE_NOT_POSSIBLE if the service is busy pushing other data, try again later
  871  *      - LE_FAULT on any other error
  872  */
  873 //--------------------------------------------------------------------------------------------------
  874 le_result_t le_avdata_PushStream
  875 (
  876     const char* LE_NONNULL path,
  877         ///< [IN]
  878     int fd,
  879         ///< [IN]
  880     le_avdata_CallbackResultFunc_t handlerPtr,
  881         ///< [IN]
  882     void* contextPtr
  883         ///< [IN]
  884 );
  885 
  886 //--------------------------------------------------------------------------------------------------
  887 /**
  888  * Create a timeseries record
  889  *
  890  * @return Reference to the record
  891  */
  892 //--------------------------------------------------------------------------------------------------
  893 le_avdata_RecordRef_t le_avdata_CreateRecord
  894 (
  895     void
  896 );
  897 
  898 //--------------------------------------------------------------------------------------------------
  899 /**
  900  * Delete a timeseries record
  901  */
  902 //--------------------------------------------------------------------------------------------------
  903 void le_avdata_DeleteRecord
  904 (
  905     le_avdata_RecordRef_t recordRef
  906         ///< [IN]
  907 );
  908 
  909 //--------------------------------------------------------------------------------------------------
  910 /**
  911  * Accumulate int data
  912  *
  913  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
  914  *
  915  * @return:
  916  *      - LE_OK on success
  917  *      - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  918  *      - LE_FAULT on any other error
  919  */
  920 //--------------------------------------------------------------------------------------------------
  921 le_result_t le_avdata_RecordInt
  922 (
  923     le_avdata_RecordRef_t recordRef,
  924         ///< [IN]
  925     const char* LE_NONNULL path,
  926         ///< [IN]
  927     int32_t value,
  928         ///< [IN]
  929     uint64_t timestamp
  930         ///< [IN]
  931 );
  932 
  933 //--------------------------------------------------------------------------------------------------
  934 /**
  935  * Accumulate float data
  936  *
  937  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
  938  *
  939  * @return:
  940  *      - LE_OK on success
  941  *      - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  942  *      - LE_FAULT on any other error
  943  */
  944 //--------------------------------------------------------------------------------------------------
  945 le_result_t le_avdata_RecordFloat
  946 (
  947     le_avdata_RecordRef_t recordRef,
  948         ///< [IN]
  949     const char* LE_NONNULL path,
  950         ///< [IN]
  951     double value,
  952         ///< [IN]
  953     uint64_t timestamp
  954         ///< [IN]
  955 );
  956 
  957 //--------------------------------------------------------------------------------------------------
  958 /**
  959  * Accumulate boolean data
  960  *
  961  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
  962  *
  963  * @return:
  964  *      - LE_OK on success
  965  *      - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  966  *      - LE_FAULT on any other error
  967  */
  968 //--------------------------------------------------------------------------------------------------
  969 le_result_t le_avdata_RecordBool
  970 (
  971     le_avdata_RecordRef_t recordRef,
  972         ///< [IN]
  973     const char* LE_NONNULL path,
  974         ///< [IN]
  975     bool value,
  976         ///< [IN]
  977     uint64_t timestamp
  978         ///< [IN]
  979 );
  980 
  981 //--------------------------------------------------------------------------------------------------
  982 /**
  983  * Accumulate string data
  984  *
  985  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
  986  *
  987  * @return:
  988  *      - LE_OK on success
  989  *      - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
  990  *      - LE_FAULT on any other error
  991  */
  992 //--------------------------------------------------------------------------------------------------
  993 le_result_t le_avdata_RecordString
  994 (
  995     le_avdata_RecordRef_t recordRef,
  996         ///< [IN]
  997     const char* LE_NONNULL path,
  998         ///< [IN]
  999     const char* LE_NONNULL value,
 1000         ///< [IN]
 1001     uint64_t timestamp
 1002         ///< [IN]
 1003 );
 1004 
 1005 //--------------------------------------------------------------------------------------------------
 1006 /**
 1007  * Push record to the server
 1008  *
 1009  ** @return:
 1010  *      - LE_OK on success.
 1011  *      - LE_BUSY if push is queued and will pushed later automatically
 1012  *      - LE_NOT_POSSIBLE if push queue is full, try again later
 1013  *      - LE_FAULT on any other error
 1014  *
 1015  * * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1016  *       function will not return.
 1017  */
 1018 //--------------------------------------------------------------------------------------------------
 1019 le_result_t le_avdata_PushRecord
 1020 (
 1021     le_avdata_RecordRef_t recordRef,
 1022         ///< [IN]
 1023     le_avdata_CallbackResultFunc_t handlerPtr,
 1024         ///< [IN]
 1025     void* contextPtr
 1026         ///< [IN]
 1027 );
 1028 
 1029 //--------------------------------------------------------------------------------------------------
 1030 /**
 1031  * Add handler function for EVENT 'le_avdata_SessionState'
 1032  *
 1033  * This event provides information on AV session state changes
 1034  */
 1035 //--------------------------------------------------------------------------------------------------
 1036 le_avdata_SessionStateHandlerRef_t le_avdata_AddSessionStateHandler
 1037 (
 1038     le_avdata_SessionStateHandlerFunc_t handlerPtr,
 1039         ///< [IN]
 1040     void* contextPtr
 1041         ///< [IN]
 1042 );
 1043 
 1044 //--------------------------------------------------------------------------------------------------
 1045 /**
 1046  * Remove handler function for EVENT 'le_avdata_SessionState'
 1047  */
 1048 //--------------------------------------------------------------------------------------------------
 1049 void le_avdata_RemoveSessionStateHandler
 1050 (
 1051     le_avdata_SessionStateHandlerRef_t handlerRef
 1052         ///< [IN]
 1053 );
 1054 
 1055 //--------------------------------------------------------------------------------------------------
 1056 /**
 1057  * Request the avcServer to open a session.
 1058  *
 1059  * @return
 1060  *      - SessionRef if session request succeeded
 1061  *      - NULL if session request failed
 1062  */
 1063 //--------------------------------------------------------------------------------------------------
 1064 le_avdata_RequestSessionObjRef_t le_avdata_RequestSession
 1065 (
 1066     void
 1067 );
 1068 
 1069 //--------------------------------------------------------------------------------------------------
 1070 /**
 1071  * Request the avcServer to close a session.
 1072  *
 1073  */
 1074 //--------------------------------------------------------------------------------------------------
 1075 void le_avdata_ReleaseSession
 1076 (
 1077     le_avdata_RequestSessionObjRef_t requestRef
 1078         ///< [IN] Reference to a previously opened AV session.
 1079 );
 1080 
 1081 #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_AccessMode_t
le_avdata_AccessMode_t
Definition: le_avdata_interface.h:345
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:35
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_RequestSessionObjRef_t
struct le_avdata_RequestSessionObj * le_avdata_RequestSessionObjRef_t
Definition: le_avdata_interface.h:436
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:234
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_AccessType_t
le_avdata_AccessType_t
Definition: le_avdata_interface.h:362
le_avdata_ConnectService
void le_avdata_ConnectService(void)
le_avdata_DataType_t
le_avdata_DataType_t
Definition: le_avdata_interface.h:376
le_avdata_SessionState_t
le_avdata_SessionState_t
Definition: le_avdata_interface.h:444
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_ResourceEventHandlerRef_t
struct le_avdata_ResourceEventHandler * le_avdata_ResourceEventHandlerRef_t
Definition: le_avdata_interface.h:420
le_avdata_TryConnectService
le_result_t le_avdata_TryConnectService(void)
le_avdata_SetServerDisconnectHandler
void le_avdata_SetServerDisconnectHandler(le_avdata_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_avdata_SetFloat
le_result_t le_avdata_SetFloat(const char *LE_NONNULL path, double value)
LE_AVDATA_SESSION_STARTED
AVMS session started. 
Definition: le_avdata_interface.h:446
le_avdata_GetFloatArg
le_result_t le_avdata_GetFloatArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, double *floatArgPtr)
le_avdata_SessionStateHandlerRef_t
struct le_avdata_SessionStateHandler * le_avdata_SessionStateHandlerRef_t
Definition: le_avdata_interface.h:459
le_avdata_SessionStateHandlerFunc_t
void(* le_avdata_SessionStateHandlerFunc_t)(le_avdata_SessionState_t sessionState, void *contextPtr)
Definition: le_avdata_interface.h:498
le_avdata_ArgumentListRef_t
struct le_avdata_ArgumentList * le_avdata_ArgumentListRef_t
Definition: le_avdata_interface.h:412
legato.h
le_avdata_RecordRef_t
struct le_avdata_Record * le_avdata_RecordRef_t
Definition: le_avdata_interface.h:428
le_avdata_AddResourceEventHandler
le_avdata_ResourceEventHandlerRef_t le_avdata_AddResourceEventHandler(const char *LE_NONNULL path, le_avdata_ResourceHandlerFunc_t handlerPtr, void *contextPtr)
le_avdata_CallbackResultFunc_t
void(* le_avdata_CallbackResultFunc_t)(le_avdata_PushStatus_t status, void *contextPtr)
Definition: le_avdata_interface.h:485
LE_AVDATA_SESSION_STOPPED
AVMS session stopped. 
Definition: le_avdata_interface.h:448
le_avdata_PushStatus_t
le_avdata_PushStatus_t
Definition: le_avdata_interface.h:397
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_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_interface.h:468
le_avdata_RemoveSessionStateHandler
void le_avdata_RemoveSessionStateHandler(le_avdata_SessionStateHandlerRef_t handlerRef)