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