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 Asset data settings are persistent after an application restart or device reboot,
162  * regardless of the namespace used to create it. The asset data settings are restored lazily when
163  * the app or server reads the setting.
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. A read request from the
192  * server on a parent node will result in reading multiple resources together. For example, a read
193  * request on "<appName>/test" will result in a response containing relative paths and values of
194  * resourceA and resourceB.
195  *
196  * @section le_avdata_timeseries Time Series
197  *
198  * This feature enables user Apps to collect and keep in memory data when the device is off-line and
199  * send the data to the AirVantage Server when the device is on-line.
200  *
201  * Time series records can be initialized using le_avdata_CreateRecord().
202  * Data can be accumulated using the following data types along with a specified time stamp
203  * (milliseconds elapsed since epoch).
204  * - le_avdata_RecordInt()
205  * - le_avdata_RecordFloat()
206  * - le_avdata_RecordBool()
207  * - le_avdata_RecordString()
208  *
209  * User apps can then open an @c avms session, and push the collected history data using
210  * le_avdata_PushRecord(). The callback used when calling le_avdata_PushRecord() will indicate
211  * whether the push has been successful or not.
212  *
213  * This code sample shows how to collect data and send to the server (assuming session is opened)
214  *
215  * @code
216  *
217  * static void PushCallbackHandler
218  * (
219  * le_avdata_PushStatus_t status,
220  * void* contextPtr
221  * )
222  * {
223  * if (status == LE_AVDATA_PUSH_SUCCESS)
224  * {
225  * // data pushed successfully
226  * }
227  * }
228  *
229  * static void SendData()
230  * {
231  * struct timeval tv;
232  * uint64_t utcMilliSec;
233  * le_result_t result;
234  *
235  * le_avdata_RecordRef_t recRef = le_avdata_CreateRecord();
236  *
237  * gettimeofday(&tv, NULL);
238  * utcMilliSec = (uint64_t)(tv.tv_sec) * 1000 + (uint64_t)(tv.tv_usec) / 1000; // get current time
239  * result = le_avdata_RecordFloat(recRef, "speed", 0.08, utcMilliSec);
240  *
241  * if (result == LE_OK)
242  * {
243  * le_avdata_PushRecord(recRef, PushCallbackHandler, NULL);
244  * }
245  *
246  * le_avdata_DeleteRecord(recRef);
247  * }
248  * @endcode
249  *
250  * @section le_avdata_session User App Session Management
251  *
252  * An App can request to open a session and register a handler to get notified of a session
253  * events. le_avdata_RequestSession() and le_avdata_ReleaseSession() can be used to
254  * open a session and close a session respectively. If the session was initiated by an
255  * user app, the session will be closed when all apps release their session reference.
256  * le_avdata_AddSessionStateHandler() and le_avdata_RemoveSessionStateHandler() can be used to add
257  * and remove notification handlers.
258  *
259  * @section le_avdata_fatal Fatal Behavior
260  *
261  * An invalid asset name or field name is treated as a fatal error (i.e. non-recoverable)
262  * and will result in the client App being terminated.
263  *
264  * @section le_avdata_buffer AV Data Buffer Limitation
265  *
266  * The number of resources that can be read/written together is limited by the buffer size
267  * defined by avc client. There are three buffers that determines how many resources can be
268  * read/written/pushed together.
269  *
270  * - COAP_BLOCK1_SIZE - Determines the number of resource that can be written together
271  * - AVDATA_READ_BUFFER_BYTES - Determines the number of resource that can be read together
272  * - AVDATA_PUSH_BUFFER_BYTES - Determines the number of resource that can be pushed together
273  *
274  * All the buffers are set to 4096 bytes by default. Users can increase the buffer size if an
275  * application needs to operate on a parent path with a large number of resources under it.
276  *
277  * @note Having more than 5000 resources under a parent path is not advisable for
278  * several reasons: If the network is lost or device resets while the payload is being
279  * transferred, the read/write operation will fail and has to be re-triggered. Large number
280  * of settings will also slow down avc startup.
281  *
282  * Copyright (C) Sierra Wireless Inc.
283  */
284 /**
285  * @file le_avdata_interface.h
286  *
287  * Legato @ref c_le_avdata include file.
288  *
289  * Copyright (C) Sierra Wireless Inc.
290  */
291 
292 #ifndef LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
293 #define LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
294 
295 
296 #include "legato.h"
297 
298 // Internal includes for this interface
299 #include "le_avdata_common.h"
300 /** @addtogroup le_avdata le_avdata API Reference
301  * @{
302  * @file le_avdata_common.h
303  * @file le_avdata_interface.h **/
304 //--------------------------------------------------------------------------------------------------
305 /**
306  * Type for handler called when a server disconnects.
307  */
308 //--------------------------------------------------------------------------------------------------
309 typedef void (*le_avdata_DisconnectHandler_t)(void *);
310 
311 //--------------------------------------------------------------------------------------------------
312 /**
313  *
314  * Connect the current client thread to the service providing this API. Block until the service is
315  * available.
316  *
317  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
318  * called before any other functions in this API. Normally, ConnectService is automatically called
319  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
320  *
321  * This function is created automatically.
322  */
323 //--------------------------------------------------------------------------------------------------
325 (
326  void
327 );
328 
329 //--------------------------------------------------------------------------------------------------
330 /**
331  *
332  * Try to connect the current client thread to the service providing this API. Return with an error
333  * if the service is not available.
334  *
335  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
336  * called before any other functions in this API. Normally, ConnectService is automatically called
337  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
338  *
339  * This function is created automatically.
340  *
341  * @return
342  * - LE_OK if the client connected successfully to the service.
343  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
344  * bound.
345  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
346  * - LE_COMM_ERROR if the Service Directory cannot be reached.
347  */
348 //--------------------------------------------------------------------------------------------------
350 (
351  void
352 );
353 
354 //--------------------------------------------------------------------------------------------------
355 /**
356  * Set handler called when server disconnection is detected.
357  *
358  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
359  * to continue without exiting, it should call longjmp() from inside the handler.
360  */
361 //--------------------------------------------------------------------------------------------------
363 (
364  le_avdata_DisconnectHandler_t disconnectHandler,
365  void *contextPtr
366 );
367 
368 //--------------------------------------------------------------------------------------------------
369 /**
370  *
371  * Disconnect the current client thread from the service providing this API.
372  *
373  * Normally, this function doesn't need to be called. After this function is called, there's no
374  * longer a connection to the service, and the functions in this API can't be used. For details, see
375  * @ref apiFilesC_client.
376  *
377  * This function is created automatically.
378  */
379 //--------------------------------------------------------------------------------------------------
381 (
382  void
383 );
384 
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 
395 
396 //--------------------------------------------------------------------------------------------------
397 /**
398  * Resource access types
399  */
400 //--------------------------------------------------------------------------------------------------
401 
402 
403 //--------------------------------------------------------------------------------------------------
404 /**
405  * Resource namespace
406  */
407 //--------------------------------------------------------------------------------------------------
408 
409 
410 //--------------------------------------------------------------------------------------------------
411 /**
412  * Data types
413  */
414 //--------------------------------------------------------------------------------------------------
415 
416 
417 //--------------------------------------------------------------------------------------------------
418 /**
419  * Status of the data push
420  * @todo Provide additional status to troubleshoot delivery problems
421  */
422 //--------------------------------------------------------------------------------------------------
423 
424 
425 //--------------------------------------------------------------------------------------------------
426 /**
427  * Argument list reference, for command only.
428  */
429 //--------------------------------------------------------------------------------------------------
430 
431 
432 //--------------------------------------------------------------------------------------------------
433 /**
434  * Handler for resource activity. Note that the path returned by this event follows the unix format
435  * (e.g. "/a/b/c") even if the app uses the URL format (e.g "a.b.c") when registering
436  * the handler.
437  */
438 //--------------------------------------------------------------------------------------------------
439 
440 
441 //--------------------------------------------------------------------------------------------------
442 /**
443  * Handler for pushing data result.
444  */
445 //--------------------------------------------------------------------------------------------------
446 
447 
448 //--------------------------------------------------------------------------------------------------
449 /**
450  * Reference type used by Add/Remove functions for EVENT 'le_avdata_ResourceEvent'
451  */
452 //--------------------------------------------------------------------------------------------------
453 
454 
455 //--------------------------------------------------------------------------------------------------
456 /**
457  * A record reference
458  */
459 //--------------------------------------------------------------------------------------------------
460 
461 
462 //--------------------------------------------------------------------------------------------------
463 /**
464  * Reference returned by RequestSession function and used by ReleaseSession function
465  */
466 //--------------------------------------------------------------------------------------------------
467 
468 
469 //--------------------------------------------------------------------------------------------------
470 /**
471  * AVMS session state
472  */
473 //--------------------------------------------------------------------------------------------------
474 
475 
476 //--------------------------------------------------------------------------------------------------
477 /**
478  * Handler for AV session changes
479  */
480 //--------------------------------------------------------------------------------------------------
481 
482 
483 //--------------------------------------------------------------------------------------------------
484 /**
485  * Reference type used by Add/Remove functions for EVENT 'le_avdata_SessionState'
486  */
487 //--------------------------------------------------------------------------------------------------
488 
489 
490 //--------------------------------------------------------------------------------------------------
491 /**
492  * Add handler function for EVENT 'le_avdata_ResourceEvent'
493  *
494  * Upon resource access on the server side, the registered handler is called.
495  *
496  * For "settings" (read/write), the same handler is called for both read and write access.
497  *
498  * For "commands", the handler function must call the "ReplyExecResult" function to send the command
499  * execution result back to the AVC daemon (which then sends the proper response back to the AV
500  * server).
501  */
502 //--------------------------------------------------------------------------------------------------
504 (
505  const char* LE_NONNULL path,
506  ///< [IN]
508  ///< [IN]
509  void* contextPtr
510  ///< [IN]
511 );
512 
513 //--------------------------------------------------------------------------------------------------
514 /**
515  * Remove handler function for EVENT 'le_avdata_ResourceEvent'
516  */
517 //--------------------------------------------------------------------------------------------------
519 (
521  ///< [IN]
522 );
523 
524 //--------------------------------------------------------------------------------------------------
525 /**
526  * Create an asset data with the provided path. Note that asset data type and value are determined
527  * upon the first call to a Set function. When an asset data is created, it contains a null value,
528  * represented by the data type of none.
529  *
530  * @return:
531  * - LE_OK on success
532  * - LE_DUPLICATE if path has already been called by CreateResource before, or path is parent
533  * or child to an existing Asset Data path.
534  * - LE_FAULT on any other error.
535  */
536 //--------------------------------------------------------------------------------------------------
538 (
539  const char* LE_NONNULL path,
540  ///< [IN]
541  le_avdata_AccessMode_t accessMode
542  ///< [IN]
543 );
544 
545 //--------------------------------------------------------------------------------------------------
546 /**
547  * Sets the namespace for asset data.
548  *
549  * @return:
550  * - LE_OK on success
551  * - LE_BAD_PARAMETER if the namespace is unknown
552  */
553 //--------------------------------------------------------------------------------------------------
555 (
556  le_avdata_Namespace_t _namespace
557  ///< [IN]
558 );
559 
560 //--------------------------------------------------------------------------------------------------
561 /**
562  * Sets an asset data to contain a null value, represented by the data type of none.
563  *
564  * @return:
565  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
566  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
567  * - LE_OK - access successful.
568  */
569 //--------------------------------------------------------------------------------------------------
571 (
572  const char* LE_NONNULL path
573  ///< [IN]
574 );
575 
576 //--------------------------------------------------------------------------------------------------
577 /**
578  * Gets the integer value of an asset data.
579  *
580  * @return:
581  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
582  * - LE_UNAVAILABLE - asset data contains null value
583  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
584  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
585  * - LE_OK - access successful.
586  */
587 //--------------------------------------------------------------------------------------------------
589 (
590  const char* LE_NONNULL path,
591  ///< [IN]
592  int32_t* valuePtr
593  ///< [OUT]
594 );
595 
596 //--------------------------------------------------------------------------------------------------
597 /**
598  * Sets an asset data to an integer value.
599  *
600  * @return:
601  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
602  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
603  * - LE_OK - access successful.
604  */
605 //--------------------------------------------------------------------------------------------------
607 (
608  const char* LE_NONNULL path,
609  ///< [IN]
610  int32_t value
611  ///< [IN]
612 );
613 
614 //--------------------------------------------------------------------------------------------------
615 /**
616  * Gets the float value of an asset data.
617  *
618  * @return:
619  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
620  * - LE_UNAVAILABLE - asset data contains null value
621  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
622  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
623  * - LE_OK - access successful.
624  */
625 //--------------------------------------------------------------------------------------------------
627 (
628  const char* LE_NONNULL path,
629  ///< [IN]
630  double* valuePtr
631  ///< [OUT]
632 );
633 
634 //--------------------------------------------------------------------------------------------------
635 /**
636  * Sets an asset data to a float value.
637  *
638  * @return:
639  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
640  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
641  * - LE_OK - access successful.
642  */
643 //--------------------------------------------------------------------------------------------------
645 (
646  const char* LE_NONNULL path,
647  ///< [IN]
648  double value
649  ///< [IN]
650 );
651 
652 //--------------------------------------------------------------------------------------------------
653 /**
654  * Gets the bool value of an asset data.
655  *
656  * @return:
657  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
658  * - LE_UNAVAILABLE - asset data contains null value
659  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
660  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
661  * - LE_OK - access successful.
662  */
663 //--------------------------------------------------------------------------------------------------
665 (
666  const char* LE_NONNULL path,
667  ///< [IN]
668  bool* valuePtr
669  ///< [OUT]
670 );
671 
672 //--------------------------------------------------------------------------------------------------
673 /**
674  * Sets an asset data to a bool value.
675  *
676  * @return:
677  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
678  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
679  * - LE_OK - access successful.
680  */
681 //--------------------------------------------------------------------------------------------------
683 (
684  const char* LE_NONNULL path,
685  ///< [IN]
686  bool value
687  ///< [IN]
688 );
689 
690 //--------------------------------------------------------------------------------------------------
691 /**
692  * Gets the string value of an asset data.
693  *
694  * @return:
695  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
696  * - LE_UNAVAILABLE - asset data contains null value
697  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
698  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
699  * - LE_OVERFLOW - asset data length exceeds the maximum length
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  * - LE_OVERFLOW - argument length exceeds the maximum length
796  */
797 //--------------------------------------------------------------------------------------------------
799 (
800  le_avdata_ArgumentListRef_t argumentListRef,
801  ///< [IN]
802  const char* LE_NONNULL argName,
803  ///< [IN]
804  char* strArg,
805  ///< [OUT]
806  size_t strArgSize
807  ///< [IN]
808 );
809 
810 //--------------------------------------------------------------------------------------------------
811 /**
812  * Get the length (excluding terminating null byte) of the string argument of the specified name.
813  *
814  * @return:
815  * - LE_OK on success
816  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
817  */
818 //--------------------------------------------------------------------------------------------------
820 (
821  le_avdata_ArgumentListRef_t argumentListRef,
822  ///< [IN]
823  const char* LE_NONNULL argName,
824  ///< [IN]
825  int32_t* strArgLenPtr
826  ///< [OUT]
827 );
828 
829 //--------------------------------------------------------------------------------------------------
830 /**
831  * Reply command execution result to AVC Daemon, which can then respond to AV server. This function
832  * MUST be called at the end of a command execution, in order for AV server to be notified about the
833  * execution status.
834  */
835 //--------------------------------------------------------------------------------------------------
837 (
838  le_avdata_ArgumentListRef_t argumentListRef,
839  ///< [IN]
840  le_result_t result
841  ///< [IN]
842 );
843 
844 //--------------------------------------------------------------------------------------------------
845 /**
846  * Push asset data to the server.
847  *
848  * @return:
849  * - LE_OK on success
850  * - LE_NOT_FOUND if the provided path doesn't exist
851  * - LE_BUSY if push service is busy. Data added to queue list for later push
852  * - LE_OVERFLOW if data size exceeds the maximum allowed size
853  * - LE_NO_MEMORY if push queue is full, try again later
854  * - LE_FAULT on any other error
855  */
856 //--------------------------------------------------------------------------------------------------
858 (
859  const char* LE_NONNULL path,
860  ///< [IN]
862  ///< [IN]
863  void* contextPtr
864  ///< [IN]
865 );
866 
867 //--------------------------------------------------------------------------------------------------
868 /**
869  * Push data dump to a specified path on the server.
870  *
871  * @return:
872  * - LE_OK on success
873  * - LE_BUSY if push service is busy. Data added to queue list for later push
874  * - LE_OVERFLOW if data size exceeds the maximum allowed size
875  * - LE_NO_MEMORY if push queue is full, try again later
876  * - LE_FAULT on any other error
877  */
878 //--------------------------------------------------------------------------------------------------
880 (
881  const char* LE_NONNULL path,
882  ///< [IN]
883  int fd,
884  ///< [IN]
886  ///< [IN]
887  void* contextPtr
888  ///< [IN]
889 );
890 
891 //--------------------------------------------------------------------------------------------------
892 /**
893  * Create a timeseries record
894  *
895  * @return Reference to the record
896  */
897 //--------------------------------------------------------------------------------------------------
899 (
900  void
901 );
902 
903 //--------------------------------------------------------------------------------------------------
904 /**
905  * Delete a timeseries record
906  */
907 //--------------------------------------------------------------------------------------------------
909 (
910  le_avdata_RecordRef_t recordRef
911  ///< [IN]
912 );
913 
914 //--------------------------------------------------------------------------------------------------
915 /**
916  * Accumulate int data
917  *
918  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
919  *
920  * @return:
921  * - LE_OK on success
922  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
923  * - LE_FAULT on any other error
924  */
925 //--------------------------------------------------------------------------------------------------
927 (
928  le_avdata_RecordRef_t recordRef,
929  ///< [IN]
930  const char* LE_NONNULL path,
931  ///< [IN]
932  int32_t value,
933  ///< [IN]
934  uint64_t timestamp
935  ///< [IN]
936 );
937 
938 //--------------------------------------------------------------------------------------------------
939 /**
940  * Accumulate float data
941  *
942  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
943  *
944  * @return:
945  * - LE_OK on success
946  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
947  * - LE_FAULT on any other error
948  */
949 //--------------------------------------------------------------------------------------------------
951 (
952  le_avdata_RecordRef_t recordRef,
953  ///< [IN]
954  const char* LE_NONNULL path,
955  ///< [IN]
956  double value,
957  ///< [IN]
958  uint64_t timestamp
959  ///< [IN]
960 );
961 
962 //--------------------------------------------------------------------------------------------------
963 /**
964  * Accumulate boolean data
965  *
966  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
967  *
968  * @return:
969  * - LE_OK on success
970  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
971  * - LE_FAULT on any other error
972  */
973 //--------------------------------------------------------------------------------------------------
975 (
976  le_avdata_RecordRef_t recordRef,
977  ///< [IN]
978  const char* LE_NONNULL path,
979  ///< [IN]
980  bool value,
981  ///< [IN]
982  uint64_t timestamp
983  ///< [IN]
984 );
985 
986 //--------------------------------------------------------------------------------------------------
987 /**
988  * Accumulate string data
989  *
990  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
991  *
992  * @return:
993  * - LE_OK on success
994  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
995  * - LE_FAULT on any other error
996  */
997 //--------------------------------------------------------------------------------------------------
999 (
1000  le_avdata_RecordRef_t recordRef,
1001  ///< [IN]
1002  const char* LE_NONNULL path,
1003  ///< [IN]
1004  const char* LE_NONNULL value,
1005  ///< [IN]
1006  uint64_t timestamp
1007  ///< [IN]
1008 );
1009 
1010 //--------------------------------------------------------------------------------------------------
1011 /**
1012  * Push record to the server
1013  *
1014  ** @return:
1015  * - LE_OK on success
1016  * - LE_BUSY if push service is busy. Data added to queue list for later push
1017  * - LE_OVERFLOW if data size exceeds the maximum allowed size
1018  * - LE_NO_MEMORY if push queue is full, try again later
1019  * - LE_FAULT on any other error
1020  *
1021  * * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1022  * function will not return.
1023  */
1024 //--------------------------------------------------------------------------------------------------
1026 (
1027  le_avdata_RecordRef_t recordRef,
1028  ///< [IN]
1029  le_avdata_CallbackResultFunc_t handlerPtr,
1030  ///< [IN]
1031  void* contextPtr
1032  ///< [IN]
1033 );
1034 
1035 //--------------------------------------------------------------------------------------------------
1036 /**
1037  * Add handler function for EVENT 'le_avdata_SessionState'
1038  *
1039  * This event provides information on AV session state changes
1040  */
1041 //--------------------------------------------------------------------------------------------------
1043 (
1045  ///< [IN]
1046  void* contextPtr
1047  ///< [IN]
1048 );
1049 
1050 //--------------------------------------------------------------------------------------------------
1051 /**
1052  * Remove handler function for EVENT 'le_avdata_SessionState'
1053  */
1054 //--------------------------------------------------------------------------------------------------
1056 (
1058  ///< [IN]
1059 );
1060 
1061 //--------------------------------------------------------------------------------------------------
1062 /**
1063  * Request the avcServer to open a session.
1064  *
1065  * @return
1066  * - SessionRef if session request succeeded
1067  * - NULL if session request failed
1068  */
1069 //--------------------------------------------------------------------------------------------------
1071 (
1072  void
1073 );
1074 
1075 //--------------------------------------------------------------------------------------------------
1076 /**
1077  * Request the avcServer to close a session.
1078  *
1079  */
1080 //--------------------------------------------------------------------------------------------------
1082 (
1084  ///< [IN] Reference to a previously opened AV session.
1085 );
1086 
1087 /** @} **/
1088 
1089 #endif // LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
void le_avdata_DeleteRecord(le_avdata_RecordRef_t recordRef)
struct le_avdata_Record * le_avdata_RecordRef_t
Definition: le_avdata_common.h:158
le_result_t le_avdata_RecordInt(le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, int32_t value, uint64_t timestamp)
void le_avdata_RemoveSessionStateHandler(le_avdata_SessionStateHandlerRef_t handlerRef)
void le_avdata_DisconnectService(void)
le_result_t
Definition: le_basics.h:46
le_result_t le_avdata_SetNull(const char *LE_NONNULL path)
void(* le_avdata_DisconnectHandler_t)(void *)
Definition: le_avdata_interface.h:309
le_result_t le_avdata_GetStringArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, char *strArg, size_t strArgSize)
le_result_t le_avdata_SetString(const char *LE_NONNULL path, const char *LE_NONNULL value)
le_result_t le_avdata_RecordFloat(le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, double value, uint64_t timestamp)
le_result_t le_avdata_RecordString(le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, const char *LE_NONNULL value, uint64_t timestamp)
le_result_t le_avdata_GetInt(const char *LE_NONNULL path, int32_t *valuePtr)
le_result_t le_avdata_SetInt(const char *LE_NONNULL path, int32_t value)
void le_avdata_RemoveResourceEventHandler(le_avdata_ResourceEventHandlerRef_t handlerRef)
LE_FULL_API void le_avdata_SetServerDisconnectHandler(le_avdata_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_avdata_AccessMode_t
Definition: le_avdata_common.h:62
le_result_t le_avdata_GetIntArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, int32_t *intArgPtr)
le_result_t le_avdata_SetNamespace(le_avdata_Namespace_t _namespace)
le_result_t le_avdata_CreateResource(const char *LE_NONNULL path, le_avdata_AccessMode_t accessMode)
void le_avdata_ConnectService(void)
void le_avdata_ReplyExecResult(le_avdata_ArgumentListRef_t argumentListRef, le_result_t result)
le_result_t le_avdata_SetFloat(const char *LE_NONNULL path, double value)
le_result_t le_avdata_RecordBool(le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, bool value, uint64_t timestamp)
struct le_avdata_ResourceEventHandler * le_avdata_ResourceEventHandlerRef_t
Definition: le_avdata_common.h:150
le_avdata_SessionStateHandlerRef_t le_avdata_AddSessionStateHandler(le_avdata_SessionStateHandlerFunc_t handlerPtr, void *contextPtr)
le_avdata_RequestSessionObjRef_t le_avdata_RequestSession(void)
le_result_t le_avdata_GetBool(const char *LE_NONNULL path, bool *valuePtr)
struct le_avdata_SessionStateHandler * le_avdata_SessionStateHandlerRef_t
Definition: le_avdata_common.h:189
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_GetFloatArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, double *floatArgPtr)
le_result_t le_avdata_TryConnectService(void)
void le_avdata_ReleaseSession(le_avdata_RequestSessionObjRef_t requestRef)
void(* le_avdata_CallbackResultFunc_t)(le_avdata_PushStatus_t status, void *contextPtr)
Definition: le_avdata_common.h:217
le_result_t le_avdata_PushRecord(le_avdata_RecordRef_t recordRef, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
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_common.h:200
le_result_t le_avdata_Push(const char *LE_NONNULL path, le_avdata_CallbackResultFunc_t handlerPtr, void *contextPtr)
le_avdata_ResourceEventHandlerRef_t le_avdata_AddResourceEventHandler(const char *LE_NONNULL path, le_avdata_ResourceHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_avdata_GetBoolArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, bool *boolArgPtr)
le_avdata_RecordRef_t le_avdata_CreateRecord(void)
struct le_avdata_RequestSessionObj * le_avdata_RequestSessionObjRef_t
Definition: le_avdata_common.h:166
le_result_t le_avdata_SetBool(const char *LE_NONNULL path, bool value)
le_result_t le_avdata_GetFloat(const char *LE_NONNULL path, double *valuePtr)
void(* le_avdata_SessionStateHandlerFunc_t)(le_avdata_SessionState_t sessionState, void *contextPtr)
Definition: le_avdata_common.h:230
struct le_avdata_ArgumentList * le_avdata_ArgumentListRef_t
Definition: le_avdata_common.h:142
le_result_t le_avdata_GetStringArgLength(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, int32_t *strArgLenPtr)
le_result_t le_avdata_GetString(const char *LE_NONNULL path, char *value, size_t valueSize)
le_avdata_Namespace_t
Definition: le_avdata_common.h:90