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