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_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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 {
348  ///< read(server) or read/write(client)
350  ///< read/write (server) or read (client)
352  ///< execute (server)
353 }
355 
356 
357 //--------------------------------------------------------------------------------------------------
358 /**
359  * Resource access types
360  */
361 //--------------------------------------------------------------------------------------------------
362 typedef enum
363 {
364  LE_AVDATA_ACCESS_READ = 0x1, ///< read access type
365  LE_AVDATA_ACCESS_WRITE = 0x2, ///< write access type
366  LE_AVDATA_ACCESS_EXEC = 0x4 ///< execute access type
367 }
369 
370 
371 //--------------------------------------------------------------------------------------------------
372 /**
373  * Data types
374  */
375 //--------------------------------------------------------------------------------------------------
376 typedef enum
377 {
379  ///< Null Data Type
381  ///< Integer Data Type
383  ///< Float Data Type
385  ///< Boolean Data Type
387  ///< String Data Type
388 }
390 
391 
392 //--------------------------------------------------------------------------------------------------
393 /**
394  * Status of the data push
395  * @todo Provide additional status to troubleshoot delivery problems
396  */
397 //--------------------------------------------------------------------------------------------------
398 typedef enum
399 {
401  ///< Push was successful
403  ///< Push has failed
404 }
406 
407 
408 //--------------------------------------------------------------------------------------------------
409 /**
410  * Argument list reference, for command only.
411  */
412 //--------------------------------------------------------------------------------------------------
413 typedef struct le_avdata_ArgumentList* le_avdata_ArgumentListRef_t;
414 
415 
416 //--------------------------------------------------------------------------------------------------
417 /**
418  * Reference type used by Add/Remove functions for EVENT 'le_avdata_ResourceEvent'
419  */
420 //--------------------------------------------------------------------------------------------------
421 typedef struct le_avdata_ResourceEventHandler* le_avdata_ResourceEventHandlerRef_t;
422 
423 
424 //--------------------------------------------------------------------------------------------------
425 /**
426  * A record reference
427  */
428 //--------------------------------------------------------------------------------------------------
429 typedef struct le_avdata_Record* le_avdata_RecordRef_t;
430 
431 
432 //--------------------------------------------------------------------------------------------------
433 /**
434  * Reference returned by RequestSession function and used by ReleaseSession function
435  */
436 //--------------------------------------------------------------------------------------------------
437 typedef struct le_avdata_RequestSessionObj* le_avdata_RequestSessionObjRef_t;
438 
439 
440 //--------------------------------------------------------------------------------------------------
441 /**
442  * AVMS session state
443  */
444 //--------------------------------------------------------------------------------------------------
445 typedef enum
446 {
448  ///< AVMS session started
450  ///< AVMS session stopped
451 }
453 
454 
455 //--------------------------------------------------------------------------------------------------
456 /**
457  * Reference type used by Add/Remove functions for EVENT 'le_avdata_SessionState'
458  */
459 //--------------------------------------------------------------------------------------------------
460 typedef struct le_avdata_SessionStateHandler* le_avdata_SessionStateHandlerRef_t;
461 
462 
463 //--------------------------------------------------------------------------------------------------
464 /**
465  * Handler for resource activity
466  */
467 //--------------------------------------------------------------------------------------------------
468 typedef void (*le_avdata_ResourceHandlerFunc_t)
469 (
470  const char* LE_NONNULL path,
471  ///<
472  le_avdata_AccessType_t accessType,
473  ///<
474  le_avdata_ArgumentListRef_t argumentListRef,
475  ///<
476  void* contextPtr
477  ///<
478 );
479 
480 //--------------------------------------------------------------------------------------------------
481 /**
482  * Handler for pushing data result.
483  */
484 //--------------------------------------------------------------------------------------------------
485 typedef void (*le_avdata_CallbackResultFunc_t)
486 (
487  le_avdata_PushStatus_t status,
488  ///<
489  void* contextPtr
490  ///<
491 );
492 
493 //--------------------------------------------------------------------------------------------------
494 /**
495  * Handler for AV session changes
496  */
497 //--------------------------------------------------------------------------------------------------
499 (
500  le_avdata_SessionState_t sessionState,
501  ///< Session started or stopped?
502  void* contextPtr
503  ///<
504 );
505 
506 //--------------------------------------------------------------------------------------------------
507 /**
508  * Add handler function for EVENT 'le_avdata_ResourceEvent'
509  *
510  * Upon resource access on the server side, the registered handler is called.
511  *
512  * For "settings" (read/write), the same handler is called for both read and write access.
513  *
514  * For "commands", the handler function must call the "ReplyExecResult" function to send the command
515  * execution result back to the AVC daemon (which then sends the proper response back to the AV
516  * server).
517  */
518 //--------------------------------------------------------------------------------------------------
520 (
521  const char* LE_NONNULL path,
522  ///< [IN]
524  ///< [IN]
525  void* contextPtr
526  ///< [IN]
527 );
528 
529 //--------------------------------------------------------------------------------------------------
530 /**
531  * Remove handler function for EVENT 'le_avdata_ResourceEvent'
532  */
533 //--------------------------------------------------------------------------------------------------
535 (
537  ///< [IN]
538 );
539 
540 //--------------------------------------------------------------------------------------------------
541 /**
542  * Create an asset data with the provided path. Note that asset data type and value are determined
543  * upon the first call to a Set function. When an asset data is created, it contains a null value,
544  * represented by the data type of none.
545  *
546  * @return:
547  * - LE_OK on success
548  * - LE_DUPLICATE if path has already been called by CreateResource before, or path is parent
549  * or child to an existing Asset Data path.
550  * - LE_FAULT on any other error.
551  */
552 //--------------------------------------------------------------------------------------------------
554 (
555  const char* LE_NONNULL path,
556  ///< [IN]
557  le_avdata_AccessMode_t accessMode
558  ///< [IN]
559 );
560 
561 //--------------------------------------------------------------------------------------------------
562 /**
563  * Sets an asset data to contain a null value, represented by the data type of none.
564  *
565  * @return:
566  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
567  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
568  * - LE_OK - access successful.
569  */
570 //--------------------------------------------------------------------------------------------------
572 (
573  const char* LE_NONNULL path
574  ///< [IN]
575 );
576 
577 //--------------------------------------------------------------------------------------------------
578 /**
579  * Gets the integer value of an asset data.
580  *
581  * @return:
582  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
583  * - LE_UNAVAILABLE - asset data contains null value
584  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
585  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
586  * - LE_OK - access successful.
587  */
588 //--------------------------------------------------------------------------------------------------
590 (
591  const char* LE_NONNULL path,
592  ///< [IN]
593  int32_t* valuePtr
594  ///< [OUT]
595 );
596 
597 //--------------------------------------------------------------------------------------------------
598 /**
599  * Sets an asset data to an integer value.
600  *
601  * @return:
602  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
603  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
604  * - LE_OK - access successful.
605  */
606 //--------------------------------------------------------------------------------------------------
608 (
609  const char* LE_NONNULL path,
610  ///< [IN]
611  int32_t value
612  ///< [IN]
613 );
614 
615 //--------------------------------------------------------------------------------------------------
616 /**
617  * Gets the float value of an asset data.
618  *
619  * @return:
620  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
621  * - LE_UNAVAILABLE - asset data contains null value
622  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
623  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
624  * - LE_OK - access successful.
625  */
626 //--------------------------------------------------------------------------------------------------
628 (
629  const char* LE_NONNULL path,
630  ///< [IN]
631  double* valuePtr
632  ///< [OUT]
633 );
634 
635 //--------------------------------------------------------------------------------------------------
636 /**
637  * Sets an asset data to a float 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 //--------------------------------------------------------------------------------------------------
646 (
647  const char* LE_NONNULL path,
648  ///< [IN]
649  double value
650  ///< [IN]
651 );
652 
653 //--------------------------------------------------------------------------------------------------
654 /**
655  * Gets the bool value of an asset data.
656  *
657  * @return:
658  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
659  * - LE_UNAVAILABLE - asset data contains null value
660  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
661  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
662  * - LE_OK - access successful.
663  */
664 //--------------------------------------------------------------------------------------------------
666 (
667  const char* LE_NONNULL path,
668  ///< [IN]
669  bool* valuePtr
670  ///< [OUT]
671 );
672 
673 //--------------------------------------------------------------------------------------------------
674 /**
675  * Sets an asset data to a bool value.
676  *
677  * @return:
678  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
679  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
680  * - LE_OK - access successful.
681  */
682 //--------------------------------------------------------------------------------------------------
684 (
685  const char* LE_NONNULL path,
686  ///< [IN]
687  bool value
688  ///< [IN]
689 );
690 
691 //--------------------------------------------------------------------------------------------------
692 /**
693  * Gets the string value of an asset data.
694  *
695  * @return:
696  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
697  * - LE_UNAVAILABLE - asset data contains null value
698  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
699  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
700  * - LE_OK - access successful.
701  */
702 //--------------------------------------------------------------------------------------------------
704 (
705  const char* LE_NONNULL path,
706  ///< [IN]
707  char* value,
708  ///< [OUT]
709  size_t valueSize
710  ///< [IN]
711 );
712 
713 //--------------------------------------------------------------------------------------------------
714 /**
715  * Sets an asset data to a string value.
716  *
717  * @return:
718  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
719  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
720  * - LE_OK - access successful.
721  */
722 //--------------------------------------------------------------------------------------------------
724 (
725  const char* LE_NONNULL path,
726  ///< [IN]
727  const char* LE_NONNULL value
728  ///< [IN]
729 );
730 
731 //--------------------------------------------------------------------------------------------------
732 /**
733  * Get the bool argument with the specified name.
734  *
735  * @return:
736  * - LE_OK on success
737  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
738  */
739 //--------------------------------------------------------------------------------------------------
741 (
742  le_avdata_ArgumentListRef_t argumentListRef,
743  ///< [IN]
744  const char* LE_NONNULL argName,
745  ///< [IN]
746  bool* boolArgPtr
747  ///< [OUT]
748 );
749 
750 //--------------------------------------------------------------------------------------------------
751 /**
752  * Get the float argument with the specified name.
753  *
754  * @return:
755  * - LE_OK on success
756  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
757  */
758 //--------------------------------------------------------------------------------------------------
760 (
761  le_avdata_ArgumentListRef_t argumentListRef,
762  ///< [IN]
763  const char* LE_NONNULL argName,
764  ///< [IN]
765  double* floatArgPtr
766  ///< [OUT]
767 );
768 
769 //--------------------------------------------------------------------------------------------------
770 /**
771  * Get the int argument with the specified name.
772  *
773  * @return:
774  * - LE_OK on success
775  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
776  */
777 //--------------------------------------------------------------------------------------------------
779 (
780  le_avdata_ArgumentListRef_t argumentListRef,
781  ///< [IN]
782  const char* LE_NONNULL argName,
783  ///< [IN]
784  int32_t* intArgPtr
785  ///< [OUT]
786 );
787 
788 //--------------------------------------------------------------------------------------------------
789 /**
790  * Get the string argument with the specified name.
791  *
792  * @return:
793  * - LE_OK on success
794  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
795  */
796 //--------------------------------------------------------------------------------------------------
798 (
799  le_avdata_ArgumentListRef_t argumentListRef,
800  ///< [IN]
801  const char* LE_NONNULL argName,
802  ///< [IN]
803  char* strArg,
804  ///< [OUT]
805  size_t strArgSize
806  ///< [IN]
807 );
808 
809 //--------------------------------------------------------------------------------------------------
810 /**
811  * Get the length (excluding terminating null byte) of the string argument of the specified name.
812  *
813  * @return:
814  * - LE_OK on success
815  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
816  */
817 //--------------------------------------------------------------------------------------------------
819 (
820  le_avdata_ArgumentListRef_t argumentListRef,
821  ///< [IN]
822  const char* LE_NONNULL argName,
823  ///< [IN]
824  int32_t* strArgLenPtr
825  ///< [OUT]
826 );
827 
828 //--------------------------------------------------------------------------------------------------
829 /**
830  * Reply command execution result to AVC Daemon, which can then respond to AV server. This function
831  * MUST be called at the end of a command execution, in order for AV server to be notified about the
832  * execution status.
833  */
834 //--------------------------------------------------------------------------------------------------
836 (
837  le_avdata_ArgumentListRef_t argumentListRef,
838  ///< [IN]
839  le_result_t result
840  ///< [IN]
841 );
842 
843 //--------------------------------------------------------------------------------------------------
844 /**
845  * Push asset data to the server.
846  *
847  * @return:
848  * - LE_OK on success.
849  * - LE_NOT_FOUND if path doesn't exist.
850  * - LE_BUSY if push is queued and will pushed later automatically
851  * - LE_NOT_POSSIBLE if push queue is full, try again later
852  * - LE_FAULT on any other error
853  */
854 //--------------------------------------------------------------------------------------------------
856 (
857  const char* LE_NONNULL path,
858  ///< [IN]
860  ///< [IN]
861  void* contextPtr
862  ///< [IN]
863 );
864 
865 //--------------------------------------------------------------------------------------------------
866 /**
867  * Push data dump to a specified path on the server.
868  *
869  * @return:
870  * - LE_OK on success.
871  * - LE_NOT_POSSIBLE if the service is busy pushing other data, try again later
872  * - LE_FAULT on any other error
873  */
874 //--------------------------------------------------------------------------------------------------
876 (
877  const char* LE_NONNULL path,
878  ///< [IN]
879  int fd,
880  ///< [IN]
882  ///< [IN]
883  void* contextPtr
884  ///< [IN]
885 );
886 
887 //--------------------------------------------------------------------------------------------------
888 /**
889  * Create a timeseries record
890  *
891  * @return Reference to the record
892  */
893 //--------------------------------------------------------------------------------------------------
895 (
896  void
897 );
898 
899 //--------------------------------------------------------------------------------------------------
900 /**
901  * Delete a timeseries record
902  */
903 //--------------------------------------------------------------------------------------------------
905 (
906  le_avdata_RecordRef_t recordRef
907  ///< [IN]
908 );
909 
910 //--------------------------------------------------------------------------------------------------
911 /**
912  * Accumulate int data
913  *
914  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
915  *
916  * @return:
917  * - LE_OK on success
918  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
919  * - LE_FAULT on any other error
920  */
921 //--------------------------------------------------------------------------------------------------
923 (
924  le_avdata_RecordRef_t recordRef,
925  ///< [IN]
926  const char* LE_NONNULL path,
927  ///< [IN]
928  int32_t value,
929  ///< [IN]
930  uint64_t timestamp
931  ///< [IN]
932 );
933 
934 //--------------------------------------------------------------------------------------------------
935 /**
936  * Accumulate float data
937  *
938  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
939  *
940  * @return:
941  * - LE_OK on success
942  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
943  * - LE_FAULT on any other error
944  */
945 //--------------------------------------------------------------------------------------------------
947 (
948  le_avdata_RecordRef_t recordRef,
949  ///< [IN]
950  const char* LE_NONNULL path,
951  ///< [IN]
952  double value,
953  ///< [IN]
954  uint64_t timestamp
955  ///< [IN]
956 );
957 
958 //--------------------------------------------------------------------------------------------------
959 /**
960  * Accumulate boolean data
961  *
962  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
963  *
964  * @return:
965  * - LE_OK on success
966  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
967  * - LE_FAULT on any other error
968  */
969 //--------------------------------------------------------------------------------------------------
971 (
972  le_avdata_RecordRef_t recordRef,
973  ///< [IN]
974  const char* LE_NONNULL path,
975  ///< [IN]
976  bool value,
977  ///< [IN]
978  uint64_t timestamp
979  ///< [IN]
980 );
981 
982 //--------------------------------------------------------------------------------------------------
983 /**
984  * Accumulate string data
985  *
986  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
987  *
988  * @return:
989  * - LE_OK on success
990  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
991  * - LE_FAULT on any other error
992  */
993 //--------------------------------------------------------------------------------------------------
995 (
996  le_avdata_RecordRef_t recordRef,
997  ///< [IN]
998  const char* LE_NONNULL path,
999  ///< [IN]
1000  const char* LE_NONNULL value,
1001  ///< [IN]
1002  uint64_t timestamp
1003  ///< [IN]
1004 );
1005 
1006 //--------------------------------------------------------------------------------------------------
1007 /**
1008  * Push record to the server
1009  *
1010  ** @return:
1011  * - LE_OK on success.
1012  * - LE_BUSY if push is queued and will pushed later automatically
1013  * - LE_NOT_POSSIBLE if push queue is full, try again later
1014  * - LE_FAULT on any other error
1015  *
1016  * * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1017  * function will not return.
1018  */
1019 //--------------------------------------------------------------------------------------------------
1021 (
1022  le_avdata_RecordRef_t recordRef,
1023  ///< [IN]
1024  le_avdata_CallbackResultFunc_t handlerPtr,
1025  ///< [IN]
1026  void* contextPtr
1027  ///< [IN]
1028 );
1029 
1030 //--------------------------------------------------------------------------------------------------
1031 /**
1032  * Add handler function for EVENT 'le_avdata_SessionState'
1033  *
1034  * This event provides information on AV session state changes
1035  */
1036 //--------------------------------------------------------------------------------------------------
1038 (
1040  ///< [IN]
1041  void* contextPtr
1042  ///< [IN]
1043 );
1044 
1045 //--------------------------------------------------------------------------------------------------
1046 /**
1047  * Remove handler function for EVENT 'le_avdata_SessionState'
1048  */
1049 //--------------------------------------------------------------------------------------------------
1051 (
1053  ///< [IN]
1054 );
1055 
1056 //--------------------------------------------------------------------------------------------------
1057 /**
1058  * Request the avcServer to open a session.
1059  *
1060  * @return
1061  * - SessionRef if session request succeeded
1062  * - NULL if session request failed
1063  */
1064 //--------------------------------------------------------------------------------------------------
1066 (
1067  void
1068 );
1069 
1070 //--------------------------------------------------------------------------------------------------
1071 /**
1072  * Request the avcServer to close a session.
1073  *
1074  */
1075 //--------------------------------------------------------------------------------------------------
1077 (
1079  ///< [IN] Reference to a previously opened AV session.
1080 );
1081 
1082 #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:400
le_avdata_AccessMode_t
Definition: le_avdata_interface.h:345
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:402
execute (server)
Definition: le_avdata_interface.h:351
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:347
void le_avdata_ReleaseSession(le_avdata_RequestSessionObjRef_t requestRef)
struct le_avdata_RequestSessionObj * le_avdata_RequestSessionObjRef_t
Definition: le_avdata_interface.h:437
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:378
Boolean Data Type.
Definition: le_avdata_interface.h:384
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:386
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:234
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)
Float Data Type.
Definition: le_avdata_interface.h:382
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:362
void le_avdata_ConnectService(void)
le_avdata_DataType_t
Definition: le_avdata_interface.h:376
le_avdata_SessionState_t
Definition: le_avdata_interface.h:445
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:421
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:447
write access type
Definition: le_avdata_interface.h:365
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:460
void(* le_avdata_SessionStateHandlerFunc_t)(le_avdata_SessionState_t sessionState, void *contextPtr)
Definition: le_avdata_interface.h:499
struct le_avdata_ArgumentList * le_avdata_ArgumentListRef_t
Definition: le_avdata_interface.h:413
struct le_avdata_Record * le_avdata_RecordRef_t
Definition: le_avdata_interface.h:429
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:486
AVMS session stopped.
Definition: le_avdata_interface.h:449
le_avdata_PushStatus_t
Definition: le_avdata_interface.h:398
execute access type
Definition: le_avdata_interface.h:366
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:364
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:380
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:469
read/write (server) or read (client)
Definition: le_avdata_interface.h:349
void le_avdata_RemoveSessionStateHandler(le_avdata_SessionStateHandlerRef_t handlerRef)