le_avdata_interface.h

Go to the documentation of this file.
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 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  * 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 path are created and managed under the application namespace.
152  * Calling le_avdata_GetXXX/le_avdata_SetXXX/le_avdata_AddResourceEventHandler/le_avdata_Push with the
153  * path "/a/b/c" will search for the "/a/b/c" data under the apps namespace. In order to query any
154  * paths created under an application namespace, user must append the app name in front of the request
155  * on the server side. If creating asset data under application namespace is not desired, users must
156  * call le_avdata_SetNamespace and set the value to global. An application that changes its namespace
157  * to global will be creating asset data in the global space. All asset data API will use the last
158  * namespace set until the function is called again and the namespace is set to something new.
159  *
160  * Example:
161  *
162  * @code
163  * #define RESOURCE_A "/test/resourceA"
164  *
165  * COMPONENT_INIT
166  * {
167  * int intVal;
168  * LE_ASSERT(le_avdata_CreateResource(RESOURCE_A, LE_AVDATA_ACCESS_VARIABLE) == LE_OK);
169  * LE_ASSERT(le_avdata_SetInt(RESOURCE_A, 1) == LE_OK);
170  * LE_ASSERT(le_avdata_GetInt(RESOURCE_A, &intVal) == LE_OK);
171  * LE_ASSERT(intVal == 1); // value obtained under the application namespace
172  *
173  * // Switch to global namespace
174  * LE_ASSERT(le_avdata_SetNamespace(LE_AVDATA_NAMESPACE_GLOBAL) == LE_OK);
175  *
176  * LE_ASSERT(le_avdata_CreateResource(RESOURCE_A, LE_AVDATA_ACCESS_VARIABLE) == LE_OK);
177  * LE_ASSERT(le_avdata_SetInt(RESOURCE_A, 2) == LE_OK);
178  * LE_ASSERT(le_avdata_GetInt(RESOURCE_A, &intVal) == LE_OK);
179  * LE_ASSERT(intVal == 2); // value obtained under the global namespace
180  * }
181  *
182  * An application starts by creating a path "/test/resourceA" under the default application namespace
183  * and sets it to 1. Then it sets the namespace to global and creates another path "/test/resourceA"
184  * with a value of 2. A read request from the server on "<appName>/test/resourceA" will return 1;
185  * whereas a read request on "/test/resourceA" will return 2.
186  *
187  * @section le_avdata_timeseries Time Series
188  *
189  * This feature enables user Apps to collect and keep in memory data when the device is off-line and
190  * send the data to the AirVantage Server when the device is on-line.
191  *
192  * Time series records can be initialized using le_avdata_CreateRecord().
193  * Data can be accumulated using the following data types along with a specified time stamp
194  * (milliseconds elapsed since epoch).
195  * - le_avdata_RecordInt()
196  * - le_avdata_RecordFloat()
197  * - le_avdata_RecordBool()
198  * - le_avdata_RecordString()
199  *
200  * User apps can then open an @c avms session, and push the collected history data using
201  * le_avdata_PushRecord(). The callback used when calling le_avdata_PushRecord() will indicate
202  * whether the push has been successful or not.
203  *
204  * This code sample shows how to collect data and send to the server (assuming session is opened)
205  *
206  * @code
207  *
208  * static void PushCallbackHandler
209  * (
210  * le_avdata_PushStatus_t status,
211  * void* contextPtr
212  * )
213  * {
214  * if (status == LE_AVDATA_PUSH_SUCCESS)
215  * {
216  * // data pushed successfully
217  * }
218  * }
219  *
220  * static void SendData()
221  * {
222  * struct timeval tv;
223  * uint64_t utcMilliSec;
224  * le_result_t result;
225  *
226  * le_avdata_RecordRef_t recRef = le_avdata_CreateRecord();
227  *
228  * gettimeofday(&tv, NULL);
229  * utcMilliSec = (uint64_t)(tv.tv_sec) * 1000 + (uint64_t)(tv.tv_usec) / 1000; // get current time
230  * result = le_avdata_RecordFloat(recRef, "speed", 0.08, utcMilliSec);
231  *
232  * if (result == LE_OK)
233  * {
234  * le_avdata_PushRecord(recRef, PushCallbackHandler, NULL);
235  * }
236  *
237  * le_avdata_DeleteRecord(recRef);
238  * }
239  * @endcode
240  *
241  * @section le_avdata_session User App Session Management
242  *
243  * An App can request to open a session and register a handler to get notified of a session
244  * events. le_avdata_RequestSession() and le_avdata_ReleaseSession() can be used to
245  * open a session and close a session respectively. If the session was initiated by an
246  * user app, the session will be closed when all apps release their session reference.
247  * le_avdata_AddSessionStateHandler() and le_avdata_RemoveSessionStateHandler() can be used to add
248  * and remove notification handlers.
249  *
250  * @section le_avdata_fatal Fatal Behavior
251  *
252  * An invalid asset name or field name is treated as a fatal error (i.e. non-recoverable)
253  * and will result in the client App being terminated.
254  *
255  * Copyright (C) Sierra Wireless Inc.
256  */
257 /**
258  * @file le_avdata_interface.h
259  *
260  * Legato @ref c_le_avdata include file.
261  *
262  * Copyright (C) Sierra Wireless Inc.
263  */
264 
265 #ifndef LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
266 #define LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
267 
268 
269 #include "legato.h"
270 
271 
272 //--------------------------------------------------------------------------------------------------
273 /**
274  * Type for handler called when a server disconnects.
275  */
276 //--------------------------------------------------------------------------------------------------
277 typedef void (*le_avdata_DisconnectHandler_t)(void *);
278 
279 //--------------------------------------------------------------------------------------------------
280 /**
281  *
282  * Connect the current client thread to the service providing this API. Block until the service is
283  * available.
284  *
285  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
286  * called before any other functions in this API. Normally, ConnectService is automatically called
287  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
288  *
289  * This function is created automatically.
290  */
291 //--------------------------------------------------------------------------------------------------
293 (
294  void
295 );
296 
297 //--------------------------------------------------------------------------------------------------
298 /**
299  *
300  * Try to connect the current client thread to the service providing this API. Return with an error
301  * if the service is not available.
302  *
303  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
304  * called before any other functions in this API. Normally, ConnectService is automatically called
305  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
306  *
307  * This function is created automatically.
308  *
309  * @return
310  * - LE_OK if the client connected successfully to the service.
311  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
312  * bound.
313  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
314  * - LE_COMM_ERROR if the Service Directory cannot be reached.
315  */
316 //--------------------------------------------------------------------------------------------------
318 (
319  void
320 );
321 
322 //--------------------------------------------------------------------------------------------------
323 /**
324  * Set handler called when server disconnection is detected.
325  *
326  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
327  * to continue without exiting, it should call longjmp() from inside the handler.
328  */
329 //--------------------------------------------------------------------------------------------------
331 (
332  le_avdata_DisconnectHandler_t disconnectHandler,
333  void *contextPtr
334 );
335 
336 //--------------------------------------------------------------------------------------------------
337 /**
338  *
339  * Disconnect the current client thread from the service providing this API.
340  *
341  * Normally, this function doesn't need to be called. After this function is called, there's no
342  * longer a connection to the service, and the functions in this API can't be used. For details, see
343  * @ref apiFilesC_client.
344  *
345  * This function is created automatically.
346  */
347 //--------------------------------------------------------------------------------------------------
349 (
350  void
351 );
352 
353 
354 //--------------------------------------------------------------------------------------------------
355 /**
356  * Define the maximum characters and bytes of a path name
357  */
358 //--------------------------------------------------------------------------------------------------
359 #define LE_AVDATA_PATH_NAME_LEN 511
360 
361 //--------------------------------------------------------------------------------------------------
362 /**
363  */
364 //--------------------------------------------------------------------------------------------------
365 #define LE_AVDATA_PATH_NAME_BYTES 512
366 
367 //--------------------------------------------------------------------------------------------------
368 /**
369  * Define the maximum characters and bytes of a string
370  */
371 //--------------------------------------------------------------------------------------------------
372 #define LE_AVDATA_STRING_VALUE_LEN 255
373 
374 //--------------------------------------------------------------------------------------------------
375 /**
376  */
377 //--------------------------------------------------------------------------------------------------
378 #define LE_AVDATA_STRING_VALUE_BYTES 256
379 
380 //--------------------------------------------------------------------------------------------------
381 /**
382  * Resource access modes:
383  * - Variable: read (server), read/write (client)
384  * - Setting: read/write (server), read (client)
385  * - Command: execute (server)
386  */
387 //--------------------------------------------------------------------------------------------------
388 typedef enum
389 {
391  ///< read(server) or read/write(client)
393  ///< read/write (server) or read (client)
395  ///< execute (server)
396 }
398 
399 
400 //--------------------------------------------------------------------------------------------------
401 /**
402  * Resource access types
403  */
404 //--------------------------------------------------------------------------------------------------
405 typedef enum
406 {
407  LE_AVDATA_ACCESS_READ = 0x1, ///< read access type
408  LE_AVDATA_ACCESS_WRITE = 0x2, ///< write access type
409  LE_AVDATA_ACCESS_EXEC = 0x4 ///< execute access type
410 }
412 
413 
414 //--------------------------------------------------------------------------------------------------
415 /**
416  * Resource namespace
417  */
418 //--------------------------------------------------------------------------------------------------
419 typedef enum
420 {
421  LE_AVDATA_NAMESPACE_APPLICATION = 0,
422  ///<
423  LE_AVDATA_NAMESPACE_GLOBAL = 1
424  ///<
425 }
427 
428 
429 //--------------------------------------------------------------------------------------------------
430 /**
431  * Data types
432  */
433 //--------------------------------------------------------------------------------------------------
434 typedef enum
435 {
437  ///< Null Data Type
439  ///< Integer Data Type
441  ///< Float Data Type
443  ///< Boolean Data Type
445  ///< String Data Type
446 }
448 
449 
450 //--------------------------------------------------------------------------------------------------
451 /**
452  * Status of the data push
453  * @todo Provide additional status to troubleshoot delivery problems
454  */
455 //--------------------------------------------------------------------------------------------------
456 typedef enum
457 {
459  ///< Push was successful
461  ///< Push has failed
462 }
464 
465 
466 //--------------------------------------------------------------------------------------------------
467 /**
468  * Argument list reference, for command only.
469  */
470 //--------------------------------------------------------------------------------------------------
471 typedef struct le_avdata_ArgumentList* le_avdata_ArgumentListRef_t;
472 
473 
474 //--------------------------------------------------------------------------------------------------
475 /**
476  * Reference type used by Add/Remove functions for EVENT 'le_avdata_ResourceEvent'
477  */
478 //--------------------------------------------------------------------------------------------------
479 typedef struct le_avdata_ResourceEventHandler* le_avdata_ResourceEventHandlerRef_t;
480 
481 
482 //--------------------------------------------------------------------------------------------------
483 /**
484  * A record reference
485  */
486 //--------------------------------------------------------------------------------------------------
487 typedef struct le_avdata_Record* le_avdata_RecordRef_t;
488 
489 
490 //--------------------------------------------------------------------------------------------------
491 /**
492  * Reference returned by RequestSession function and used by ReleaseSession function
493  */
494 //--------------------------------------------------------------------------------------------------
495 typedef struct le_avdata_RequestSessionObj* le_avdata_RequestSessionObjRef_t;
496 
497 
498 //--------------------------------------------------------------------------------------------------
499 /**
500  * AVMS session state
501  */
502 //--------------------------------------------------------------------------------------------------
503 typedef enum
504 {
506  ///< AVMS session started
508  ///< AVMS session stopped
509 }
511 
512 
513 //--------------------------------------------------------------------------------------------------
514 /**
515  * Reference type used by Add/Remove functions for EVENT 'le_avdata_SessionState'
516  */
517 //--------------------------------------------------------------------------------------------------
518 typedef struct le_avdata_SessionStateHandler* le_avdata_SessionStateHandlerRef_t;
519 
520 
521 //--------------------------------------------------------------------------------------------------
522 /**
523  * Handler for resource activity. Note that the path returned by this event follows the unix format
524  * (e.g. "/a/b/c") even if the app uses the URL format (e.g "a.b.c") when registering
525  * the handler.
526  */
527 //--------------------------------------------------------------------------------------------------
528 typedef void (*le_avdata_ResourceHandlerFunc_t)
529 (
530  const char* LE_NONNULL path,
531  ///<
532  le_avdata_AccessType_t accessType,
533  ///<
534  le_avdata_ArgumentListRef_t argumentListRef,
535  ///<
536  void* contextPtr
537  ///<
538 );
539 
540 //--------------------------------------------------------------------------------------------------
541 /**
542  * Handler for pushing data result.
543  */
544 //--------------------------------------------------------------------------------------------------
545 typedef void (*le_avdata_CallbackResultFunc_t)
546 (
547  le_avdata_PushStatus_t status,
548  ///<
549  void* contextPtr
550  ///<
551 );
552 
553 //--------------------------------------------------------------------------------------------------
554 /**
555  * Handler for AV session changes
556  */
557 //--------------------------------------------------------------------------------------------------
559 (
560  le_avdata_SessionState_t sessionState,
561  ///< Session started or stopped?
562  void* contextPtr
563  ///<
564 );
565 
566 //--------------------------------------------------------------------------------------------------
567 /**
568  * Add handler function for EVENT 'le_avdata_ResourceEvent'
569  *
570  * Upon resource access on the server side, the registered handler is called.
571  *
572  * For "settings" (read/write), the same handler is called for both read and write access.
573  *
574  * For "commands", the handler function must call the "ReplyExecResult" function to send the command
575  * execution result back to the AVC daemon (which then sends the proper response back to the AV
576  * server).
577  */
578 //--------------------------------------------------------------------------------------------------
580 (
581  const char* LE_NONNULL path,
582  ///< [IN]
584  ///< [IN]
585  void* contextPtr
586  ///< [IN]
587 );
588 
589 //--------------------------------------------------------------------------------------------------
590 /**
591  * Remove handler function for EVENT 'le_avdata_ResourceEvent'
592  */
593 //--------------------------------------------------------------------------------------------------
595 (
597  ///< [IN]
598 );
599 
600 //--------------------------------------------------------------------------------------------------
601 /**
602  * Create an asset data with the provided path. Note that asset data type and value are determined
603  * upon the first call to a Set function. When an asset data is created, it contains a null value,
604  * represented by the data type of none.
605  *
606  * @return:
607  * - LE_OK on success
608  * - LE_DUPLICATE if path has already been called by CreateResource before, or path is parent
609  * or child to an existing Asset Data path.
610  * - LE_FAULT on any other error.
611  */
612 //--------------------------------------------------------------------------------------------------
614 (
615  const char* LE_NONNULL path,
616  ///< [IN]
617  le_avdata_AccessMode_t accessMode
618  ///< [IN]
619 );
620 
621 //--------------------------------------------------------------------------------------------------
622 /**
623  * Sets the namespace for asset data.
624  *
625  * @return:
626  * - LE_OK on success
627  * - LE_BAD_PARAMETER if the namespace is unknown
628  */
629 //--------------------------------------------------------------------------------------------------
631 (
632  le_avdata_Namespace_t namespace
633  ///< [IN]
634 );
635 
636 //--------------------------------------------------------------------------------------------------
637 /**
638  * Sets an asset data to contain a null value, represented by the data type of none.
639  *
640  * @return:
641  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
642  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
643  * - LE_OK - access successful.
644  */
645 //--------------------------------------------------------------------------------------------------
647 (
648  const char* LE_NONNULL path
649  ///< [IN]
650 );
651 
652 //--------------------------------------------------------------------------------------------------
653 /**
654  * Gets the integer 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 //--------------------------------------------------------------------------------------------------
665 (
666  const char* LE_NONNULL path,
667  ///< [IN]
668  int32_t* valuePtr
669  ///< [OUT]
670 );
671 
672 //--------------------------------------------------------------------------------------------------
673 /**
674  * Sets an asset data to an integer 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 //--------------------------------------------------------------------------------------------------
683 (
684  const char* LE_NONNULL path,
685  ///< [IN]
686  int32_t value
687  ///< [IN]
688 );
689 
690 //--------------------------------------------------------------------------------------------------
691 /**
692  * Gets the float 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 //--------------------------------------------------------------------------------------------------
703 (
704  const char* LE_NONNULL path,
705  ///< [IN]
706  double* valuePtr
707  ///< [OUT]
708 );
709 
710 //--------------------------------------------------------------------------------------------------
711 /**
712  * Sets an asset data to a float value.
713  *
714  * @return:
715  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
716  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
717  * - LE_OK - access successful.
718  */
719 //--------------------------------------------------------------------------------------------------
721 (
722  const char* LE_NONNULL path,
723  ///< [IN]
724  double value
725  ///< [IN]
726 );
727 
728 //--------------------------------------------------------------------------------------------------
729 /**
730  * Gets the bool value of an asset data.
731  *
732  * @return:
733  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
734  * - LE_UNAVAILABLE - asset data contains null value
735  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
736  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
737  * - LE_OK - access successful.
738  */
739 //--------------------------------------------------------------------------------------------------
741 (
742  const char* LE_NONNULL path,
743  ///< [IN]
744  bool* valuePtr
745  ///< [OUT]
746 );
747 
748 //--------------------------------------------------------------------------------------------------
749 /**
750  * Sets an asset data to a bool value.
751  *
752  * @return:
753  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
754  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
755  * - LE_OK - access successful.
756  */
757 //--------------------------------------------------------------------------------------------------
759 (
760  const char* LE_NONNULL path,
761  ///< [IN]
762  bool value
763  ///< [IN]
764 );
765 
766 //--------------------------------------------------------------------------------------------------
767 /**
768  * Gets the string value of an asset data.
769  *
770  * @return:
771  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
772  * - LE_UNAVAILABLE - asset data contains null value
773  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
774  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
775  * - LE_OK - access successful.
776  */
777 //--------------------------------------------------------------------------------------------------
779 (
780  const char* LE_NONNULL path,
781  ///< [IN]
782  char* value,
783  ///< [OUT]
784  size_t valueSize
785  ///< [IN]
786 );
787 
788 //--------------------------------------------------------------------------------------------------
789 /**
790  * Sets an asset data to a string value.
791  *
792  * @return:
793  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
794  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
795  * - LE_OK - access successful.
796  */
797 //--------------------------------------------------------------------------------------------------
799 (
800  const char* LE_NONNULL path,
801  ///< [IN]
802  const char* LE_NONNULL value
803  ///< [IN]
804 );
805 
806 //--------------------------------------------------------------------------------------------------
807 /**
808  * Get the bool argument with 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 //--------------------------------------------------------------------------------------------------
816 (
817  le_avdata_ArgumentListRef_t argumentListRef,
818  ///< [IN]
819  const char* LE_NONNULL argName,
820  ///< [IN]
821  bool* boolArgPtr
822  ///< [OUT]
823 );
824 
825 //--------------------------------------------------------------------------------------------------
826 /**
827  * Get the float argument with the specified name.
828  *
829  * @return:
830  * - LE_OK on success
831  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
832  */
833 //--------------------------------------------------------------------------------------------------
835 (
836  le_avdata_ArgumentListRef_t argumentListRef,
837  ///< [IN]
838  const char* LE_NONNULL argName,
839  ///< [IN]
840  double* floatArgPtr
841  ///< [OUT]
842 );
843 
844 //--------------------------------------------------------------------------------------------------
845 /**
846  * Get the int argument with the specified name.
847  *
848  * @return:
849  * - LE_OK on success
850  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
851  */
852 //--------------------------------------------------------------------------------------------------
854 (
855  le_avdata_ArgumentListRef_t argumentListRef,
856  ///< [IN]
857  const char* LE_NONNULL argName,
858  ///< [IN]
859  int32_t* intArgPtr
860  ///< [OUT]
861 );
862 
863 //--------------------------------------------------------------------------------------------------
864 /**
865  * Get the string argument with the specified name.
866  *
867  * @return:
868  * - LE_OK on success
869  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
870  */
871 //--------------------------------------------------------------------------------------------------
873 (
874  le_avdata_ArgumentListRef_t argumentListRef,
875  ///< [IN]
876  const char* LE_NONNULL argName,
877  ///< [IN]
878  char* strArg,
879  ///< [OUT]
880  size_t strArgSize
881  ///< [IN]
882 );
883 
884 //--------------------------------------------------------------------------------------------------
885 /**
886  * Get the length (excluding terminating null byte) of the string argument of the specified name.
887  *
888  * @return:
889  * - LE_OK on success
890  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
891  */
892 //--------------------------------------------------------------------------------------------------
894 (
895  le_avdata_ArgumentListRef_t argumentListRef,
896  ///< [IN]
897  const char* LE_NONNULL argName,
898  ///< [IN]
899  int32_t* strArgLenPtr
900  ///< [OUT]
901 );
902 
903 //--------------------------------------------------------------------------------------------------
904 /**
905  * Reply command execution result to AVC Daemon, which can then respond to AV server. This function
906  * MUST be called at the end of a command execution, in order for AV server to be notified about the
907  * execution status.
908  */
909 //--------------------------------------------------------------------------------------------------
911 (
912  le_avdata_ArgumentListRef_t argumentListRef,
913  ///< [IN]
914  le_result_t result
915  ///< [IN]
916 );
917 
918 //--------------------------------------------------------------------------------------------------
919 /**
920  * Push asset data to the server.
921  *
922  * @return:
923  * - LE_OK on success.
924  * - LE_NOT_FOUND if path doesn't exist.
925  * - LE_BUSY if push is queued and will pushed later automatically
926  * - LE_NOT_POSSIBLE if push queue is full, try again later
927  * - LE_FAULT on any other error
928  */
929 //--------------------------------------------------------------------------------------------------
931 (
932  const char* LE_NONNULL path,
933  ///< [IN]
935  ///< [IN]
936  void* contextPtr
937  ///< [IN]
938 );
939 
940 //--------------------------------------------------------------------------------------------------
941 /**
942  * Push data dump to a specified path on the server.
943  *
944  * @return:
945  * - LE_OK on success.
946  * - LE_NOT_POSSIBLE if the service is busy pushing other data, try again later
947  * - LE_FAULT on any other error
948  */
949 //--------------------------------------------------------------------------------------------------
951 (
952  const char* LE_NONNULL path,
953  ///< [IN]
954  int fd,
955  ///< [IN]
957  ///< [IN]
958  void* contextPtr
959  ///< [IN]
960 );
961 
962 //--------------------------------------------------------------------------------------------------
963 /**
964  * Create a timeseries record
965  *
966  * @return Reference to the record
967  */
968 //--------------------------------------------------------------------------------------------------
970 (
971  void
972 );
973 
974 //--------------------------------------------------------------------------------------------------
975 /**
976  * Delete a timeseries record
977  */
978 //--------------------------------------------------------------------------------------------------
980 (
981  le_avdata_RecordRef_t recordRef
982  ///< [IN]
983 );
984 
985 //--------------------------------------------------------------------------------------------------
986 /**
987  * Accumulate int data
988  *
989  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
990  *
991  * @return:
992  * - LE_OK on success
993  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
994  * - LE_FAULT on any other error
995  */
996 //--------------------------------------------------------------------------------------------------
998 (
999  le_avdata_RecordRef_t recordRef,
1000  ///< [IN]
1001  const char* LE_NONNULL path,
1002  ///< [IN]
1003  int32_t value,
1004  ///< [IN]
1005  uint64_t timestamp
1006  ///< [IN]
1007 );
1008 
1009 //--------------------------------------------------------------------------------------------------
1010 /**
1011  * Accumulate float data
1012  *
1013  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
1014  *
1015  * @return:
1016  * - LE_OK on success
1017  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
1018  * - LE_FAULT on any other error
1019  */
1020 //--------------------------------------------------------------------------------------------------
1022 (
1023  le_avdata_RecordRef_t recordRef,
1024  ///< [IN]
1025  const char* LE_NONNULL path,
1026  ///< [IN]
1027  double value,
1028  ///< [IN]
1029  uint64_t timestamp
1030  ///< [IN]
1031 );
1032 
1033 //--------------------------------------------------------------------------------------------------
1034 /**
1035  * Accumulate boolean data
1036  *
1037  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
1038  *
1039  * @return:
1040  * - LE_OK on success
1041  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
1042  * - LE_FAULT on any other error
1043  */
1044 //--------------------------------------------------------------------------------------------------
1046 (
1047  le_avdata_RecordRef_t recordRef,
1048  ///< [IN]
1049  const char* LE_NONNULL path,
1050  ///< [IN]
1051  bool value,
1052  ///< [IN]
1053  uint64_t timestamp
1054  ///< [IN]
1055 );
1056 
1057 //--------------------------------------------------------------------------------------------------
1058 /**
1059  * Accumulate string data
1060  *
1061  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
1062  *
1063  * @return:
1064  * - LE_OK on success
1065  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
1066  * - LE_FAULT on any other error
1067  */
1068 //--------------------------------------------------------------------------------------------------
1070 (
1071  le_avdata_RecordRef_t recordRef,
1072  ///< [IN]
1073  const char* LE_NONNULL path,
1074  ///< [IN]
1075  const char* LE_NONNULL value,
1076  ///< [IN]
1077  uint64_t timestamp
1078  ///< [IN]
1079 );
1080 
1081 //--------------------------------------------------------------------------------------------------
1082 /**
1083  * Push record to the server
1084  *
1085  ** @return:
1086  * - LE_OK on success.
1087  * - LE_BUSY if push is queued and will pushed later automatically
1088  * - LE_NOT_POSSIBLE if push queue is full, try again later
1089  * - LE_FAULT on any other error
1090  *
1091  * * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1092  * function will not return.
1093  */
1094 //--------------------------------------------------------------------------------------------------
1096 (
1097  le_avdata_RecordRef_t recordRef,
1098  ///< [IN]
1099  le_avdata_CallbackResultFunc_t handlerPtr,
1100  ///< [IN]
1101  void* contextPtr
1102  ///< [IN]
1103 );
1104 
1105 //--------------------------------------------------------------------------------------------------
1106 /**
1107  * Add handler function for EVENT 'le_avdata_SessionState'
1108  *
1109  * This event provides information on AV session state changes
1110  */
1111 //--------------------------------------------------------------------------------------------------
1113 (
1115  ///< [IN]
1116  void* contextPtr
1117  ///< [IN]
1118 );
1119 
1120 //--------------------------------------------------------------------------------------------------
1121 /**
1122  * Remove handler function for EVENT 'le_avdata_SessionState'
1123  */
1124 //--------------------------------------------------------------------------------------------------
1126 (
1128  ///< [IN]
1129 );
1130 
1131 //--------------------------------------------------------------------------------------------------
1132 /**
1133  * Request the avcServer to open a session.
1134  *
1135  * @return
1136  * - SessionRef if session request succeeded
1137  * - NULL if session request failed
1138  */
1139 //--------------------------------------------------------------------------------------------------
1141 (
1142  void
1143 );
1144 
1145 //--------------------------------------------------------------------------------------------------
1146 /**
1147  * Request the avcServer to close a session.
1148  *
1149  */
1150 //--------------------------------------------------------------------------------------------------
1152 (
1154  ///< [IN] Reference to a previously opened AV session.
1155 );
1156 
1157 #endif // LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
le_result_t le_avdata_PushStream(const char *LE_NONNULL path, int fd, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
le_result_t le_avdata_GetInt(const char *LE_NONNULL path, int32_t *valuePtr)
Push was successful.
Definition: le_avdata_interface.h:458
le_avdata_AccessMode_t
Definition: le_avdata_interface.h:388
le_result_t le_avdata_GetFloat(const char *LE_NONNULL path, double *valuePtr)
le_result_t le_avdata_CreateResource(const char *LE_NONNULL path, le_avdata_AccessMode_t accessMode)
le_result_t
Definition: le_basics.h:35
le_result_t le_avdata_RecordFloat(le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, double value, uint64_t timestamp)
Push has failed.
Definition: le_avdata_interface.h:460
execute (server)
Definition: le_avdata_interface.h:394
le_result_t le_avdata_SetNull(const char *LE_NONNULL path)
le_avdata_SessionStateHandlerRef_t le_avdata_AddSessionStateHandler(le_avdata_SessionStateHandlerFunc_t handlerPtr, void *contextPtr)
read(server) or read/write(client)
Definition: le_avdata_interface.h:390
void le_avdata_ReleaseSession(le_avdata_RequestSessionObjRef_t requestRef)
struct le_avdata_RequestSessionObj * le_avdata_RequestSessionObjRef_t
Definition: le_avdata_interface.h:495
void le_avdata_RemoveResourceEventHandler(le_avdata_ResourceEventHandlerRef_t handlerRef)
le_result_t le_avdata_RecordString(le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, const char *LE_NONNULL value, uint64_t timestamp)
Null Data Type.
Definition: le_avdata_interface.h:436
Boolean Data Type.
Definition: le_avdata_interface.h:442
void le_avdata_DisconnectService(void)
le_result_t le_avdata_GetBool(const char *LE_NONNULL path, bool *valuePtr)
le_result_t le_avdata_PushRecord(le_avdata_RecordRef_t recordRef, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
void le_avdata_ReplyExecResult(le_avdata_ArgumentListRef_t argumentListRef, le_result_t result)
le_result_t le_avdata_Push(const char *LE_NONNULL path, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
String Data Type.
Definition: le_avdata_interface.h:444
le_result_t le_avdata_GetStringArgLength(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, int32_t *strArgLenPtr)
le_avdata_RequestSessionObjRef_t le_avdata_RequestSession(void)
void(* le_avdata_DisconnectHandler_t)(void *)
Definition: le_avdata_interface.h:277
le_result_t le_avdata_SetString(const char *LE_NONNULL path, const char *LE_NONNULL value)
le_result_t le_avdata_GetBoolArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, bool *boolArgPtr)
le_result_t le_avdata_RecordInt(le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, int32_t value, uint64_t timestamp)
le_result_t le_avdata_SetNamespace(le_avdata_Namespace_t namespace)
Float Data Type.
Definition: le_avdata_interface.h:440
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
Definition: le_avdata_interface.h:405
void le_avdata_ConnectService(void)
le_avdata_DataType_t
Definition: le_avdata_interface.h:434
le_avdata_SessionState_t
Definition: le_avdata_interface.h:503
le_result_t le_avdata_GetString(const char *LE_NONNULL path, char *value, size_t valueSize)
le_result_t le_avdata_GetStringArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, char *strArg, size_t strArgSize)
struct le_avdata_ResourceEventHandler * le_avdata_ResourceEventHandlerRef_t
Definition: le_avdata_interface.h:479
le_result_t le_avdata_TryConnectService(void)
void le_avdata_SetServerDisconnectHandler(le_avdata_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_avdata_SetFloat(const char *LE_NONNULL path, double value)
AVMS session started.
Definition: le_avdata_interface.h:505
write access type
Definition: le_avdata_interface.h:408
le_result_t le_avdata_GetFloatArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, double *floatArgPtr)
struct le_avdata_SessionStateHandler * le_avdata_SessionStateHandlerRef_t
Definition: le_avdata_interface.h:518
void(* le_avdata_SessionStateHandlerFunc_t)(le_avdata_SessionState_t sessionState, void *contextPtr)
Definition: le_avdata_interface.h:559
le_avdata_Namespace_t
Definition: le_avdata_interface.h:419
struct le_avdata_ArgumentList * le_avdata_ArgumentListRef_t
Definition: le_avdata_interface.h:471
struct le_avdata_Record * le_avdata_RecordRef_t
Definition: le_avdata_interface.h:487
le_avdata_ResourceEventHandlerRef_t le_avdata_AddResourceEventHandler(const char *LE_NONNULL path, le_avdata_ResourceHandlerFunc_t handlerPtr, void *contextPtr)
void(* le_avdata_CallbackResultFunc_t)(le_avdata_PushStatus_t status, void *contextPtr)
Definition: le_avdata_interface.h:546
AVMS session stopped.
Definition: le_avdata_interface.h:507
le_avdata_PushStatus_t
Definition: le_avdata_interface.h:456
execute access type
Definition: le_avdata_interface.h:409
le_result_t le_avdata_GetIntArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, int32_t *intArgPtr)
read access type
Definition: le_avdata_interface.h:407
le_result_t le_avdata_SetInt(const char *LE_NONNULL path, int32_t value)
le_avdata_RecordRef_t le_avdata_CreateRecord(void)
void le_avdata_DeleteRecord(le_avdata_RecordRef_t recordRef)
Integer Data Type.
Definition: le_avdata_interface.h:438
le_result_t le_avdata_SetBool(const char *LE_NONNULL path, bool value)
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:529
read/write (server) or read (client)
Definition: le_avdata_interface.h:392
void le_avdata_RemoveSessionStateHandler(le_avdata_SessionStateHandlerRef_t handlerRef)