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 //--------------------------------------------------------------------------------------------------
301 /**
302  * Type for handler called when a server disconnects.
303  */
304 //--------------------------------------------------------------------------------------------------
305 typedef void (*le_avdata_DisconnectHandler_t)(void *);
306 
307 //--------------------------------------------------------------------------------------------------
308 /**
309  *
310  * Connect the current client thread to the service providing this API. Block until the service is
311  * available.
312  *
313  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
314  * called before any other functions in this API. Normally, ConnectService is automatically called
315  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
316  *
317  * This function is created automatically.
318  */
319 //--------------------------------------------------------------------------------------------------
321 (
322  void
323 );
324 
325 //--------------------------------------------------------------------------------------------------
326 /**
327  *
328  * Try to connect the current client thread to the service providing this API. Return with an error
329  * if the service is not available.
330  *
331  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
332  * called before any other functions in this API. Normally, ConnectService is automatically called
333  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
334  *
335  * This function is created automatically.
336  *
337  * @return
338  * - LE_OK if the client connected successfully to the service.
339  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
340  * bound.
341  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
342  * - LE_COMM_ERROR if the Service Directory cannot be reached.
343  */
344 //--------------------------------------------------------------------------------------------------
346 (
347  void
348 );
349 
350 //--------------------------------------------------------------------------------------------------
351 /**
352  * Set handler called when server disconnection is detected.
353  *
354  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
355  * to continue without exiting, it should call longjmp() from inside the handler.
356  */
357 //--------------------------------------------------------------------------------------------------
359 (
360  le_avdata_DisconnectHandler_t disconnectHandler,
361  void *contextPtr
362 );
363 
364 //--------------------------------------------------------------------------------------------------
365 /**
366  *
367  * Disconnect the current client thread from the service providing this API.
368  *
369  * Normally, this function doesn't need to be called. After this function is called, there's no
370  * longer a connection to the service, and the functions in this API can't be used. For details, see
371  * @ref apiFilesC_client.
372  *
373  * This function is created automatically.
374  */
375 //--------------------------------------------------------------------------------------------------
377 (
378  void
379 );
380 
381 
382 //--------------------------------------------------------------------------------------------------
383 /**
384  * Resource access modes:
385  * - Variable: read (server), read/write (client)
386  * - Setting: read/write (server), read/write (client)
387  * - Command: execute (server)
388  */
389 //--------------------------------------------------------------------------------------------------
390 
391 
392 //--------------------------------------------------------------------------------------------------
393 /**
394  * Resource access types
395  */
396 //--------------------------------------------------------------------------------------------------
397 
398 
399 //--------------------------------------------------------------------------------------------------
400 /**
401  * Resource namespace
402  */
403 //--------------------------------------------------------------------------------------------------
404 
405 
406 //--------------------------------------------------------------------------------------------------
407 /**
408  * Data types
409  */
410 //--------------------------------------------------------------------------------------------------
411 
412 
413 //--------------------------------------------------------------------------------------------------
414 /**
415  * Status of the data push
416  * @todo Provide additional status to troubleshoot delivery problems
417  */
418 //--------------------------------------------------------------------------------------------------
419 
420 
421 //--------------------------------------------------------------------------------------------------
422 /**
423  * Argument list reference, for command only.
424  */
425 //--------------------------------------------------------------------------------------------------
426 
427 
428 //--------------------------------------------------------------------------------------------------
429 /**
430  * Handler for resource activity. Note that the path returned by this event follows the unix format
431  * (e.g. "/a/b/c") even if the app uses the URL format (e.g "a.b.c") when registering
432  * the handler.
433  */
434 //--------------------------------------------------------------------------------------------------
435 
436 
437 //--------------------------------------------------------------------------------------------------
438 /**
439  * Handler for pushing data result.
440  */
441 //--------------------------------------------------------------------------------------------------
442 
443 
444 //--------------------------------------------------------------------------------------------------
445 /**
446  * Reference type used by Add/Remove functions for EVENT 'le_avdata_ResourceEvent'
447  */
448 //--------------------------------------------------------------------------------------------------
449 
450 
451 //--------------------------------------------------------------------------------------------------
452 /**
453  * A record reference
454  */
455 //--------------------------------------------------------------------------------------------------
456 
457 
458 //--------------------------------------------------------------------------------------------------
459 /**
460  * Reference returned by RequestSession function and used by ReleaseSession function
461  */
462 //--------------------------------------------------------------------------------------------------
463 
464 
465 //--------------------------------------------------------------------------------------------------
466 /**
467  * AVMS session state
468  */
469 //--------------------------------------------------------------------------------------------------
470 
471 
472 //--------------------------------------------------------------------------------------------------
473 /**
474  * Handler for AV session changes
475  */
476 //--------------------------------------------------------------------------------------------------
477 
478 
479 //--------------------------------------------------------------------------------------------------
480 /**
481  * Reference type used by Add/Remove functions for EVENT 'le_avdata_SessionState'
482  */
483 //--------------------------------------------------------------------------------------------------
484 
485 
486 //--------------------------------------------------------------------------------------------------
487 /**
488  * Add handler function for EVENT 'le_avdata_ResourceEvent'
489  *
490  * Upon resource access on the server side, the registered handler is called.
491  *
492  * For "settings" (read/write), the same handler is called for both read and write access.
493  *
494  * For "commands", the handler function must call the "ReplyExecResult" function to send the command
495  * execution result back to the AVC daemon (which then sends the proper response back to the AV
496  * server).
497  */
498 //--------------------------------------------------------------------------------------------------
499 le_avdata_ResourceEventHandlerRef_t le_avdata_AddResourceEventHandler
500 (
501  const char* LE_NONNULL path,
502  ///< [IN]
503  le_avdata_ResourceHandlerFunc_t handlerPtr,
504  ///< [IN]
505  void* contextPtr
506  ///< [IN]
507 );
508 
509 //--------------------------------------------------------------------------------------------------
510 /**
511  * Remove handler function for EVENT 'le_avdata_ResourceEvent'
512  */
513 //--------------------------------------------------------------------------------------------------
515 (
516  le_avdata_ResourceEventHandlerRef_t handlerRef
517  ///< [IN]
518 );
519 
520 //--------------------------------------------------------------------------------------------------
521 /**
522  * Create an asset data with the provided path. Note that asset data type and value are determined
523  * upon the first call to a Set function. When an asset data is created, it contains a null value,
524  * represented by the data type of none.
525  *
526  * @return:
527  * - LE_OK on success
528  * - LE_DUPLICATE if path has already been called by CreateResource before, or path is parent
529  * or child to an existing Asset Data path.
530  * - LE_FAULT on any other error.
531  */
532 //--------------------------------------------------------------------------------------------------
534 (
535  const char* LE_NONNULL path,
536  ///< [IN]
537  le_avdata_AccessMode_t accessMode
538  ///< [IN]
539 );
540 
541 //--------------------------------------------------------------------------------------------------
542 /**
543  * Sets the namespace for asset data.
544  *
545  * @return:
546  * - LE_OK on success
547  * - LE_BAD_PARAMETER if the namespace is unknown
548  */
549 //--------------------------------------------------------------------------------------------------
551 (
552  le_avdata_Namespace_t _namespace
553  ///< [IN]
554 );
555 
556 //--------------------------------------------------------------------------------------------------
557 /**
558  * Sets an asset data to contain a null value, represented by the data type of none.
559  *
560  * @return:
561  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
562  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
563  * - LE_OK - access successful.
564  */
565 //--------------------------------------------------------------------------------------------------
567 (
568  const char* LE_NONNULL path
569  ///< [IN]
570 );
571 
572 //--------------------------------------------------------------------------------------------------
573 /**
574  * Gets the integer value of an asset data.
575  *
576  * @return:
577  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
578  * - LE_UNAVAILABLE - asset data contains null value
579  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
580  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
581  * - LE_OK - access successful.
582  */
583 //--------------------------------------------------------------------------------------------------
585 (
586  const char* LE_NONNULL path,
587  ///< [IN]
588  int32_t* valuePtr
589  ///< [OUT]
590 );
591 
592 //--------------------------------------------------------------------------------------------------
593 /**
594  * Sets an asset data to an integer value.
595  *
596  * @return:
597  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
598  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
599  * - LE_OK - access successful.
600  */
601 //--------------------------------------------------------------------------------------------------
603 (
604  const char* LE_NONNULL path,
605  ///< [IN]
606  int32_t value
607  ///< [IN]
608 );
609 
610 //--------------------------------------------------------------------------------------------------
611 /**
612  * Gets the float value of an asset data.
613  *
614  * @return:
615  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
616  * - LE_UNAVAILABLE - asset data contains null value
617  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
618  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
619  * - LE_OK - access successful.
620  */
621 //--------------------------------------------------------------------------------------------------
623 (
624  const char* LE_NONNULL path,
625  ///< [IN]
626  double* valuePtr
627  ///< [OUT]
628 );
629 
630 //--------------------------------------------------------------------------------------------------
631 /**
632  * Sets an asset data to a float value.
633  *
634  * @return:
635  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
636  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
637  * - LE_OK - access successful.
638  */
639 //--------------------------------------------------------------------------------------------------
641 (
642  const char* LE_NONNULL path,
643  ///< [IN]
644  double value
645  ///< [IN]
646 );
647 
648 //--------------------------------------------------------------------------------------------------
649 /**
650  * Gets the bool value of an asset data.
651  *
652  * @return:
653  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
654  * - LE_UNAVAILABLE - asset data contains null value
655  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
656  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
657  * - LE_OK - access successful.
658  */
659 //--------------------------------------------------------------------------------------------------
661 (
662  const char* LE_NONNULL path,
663  ///< [IN]
664  bool* valuePtr
665  ///< [OUT]
666 );
667 
668 //--------------------------------------------------------------------------------------------------
669 /**
670  * Sets an asset data to a bool value.
671  *
672  * @return:
673  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
674  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
675  * - LE_OK - access successful.
676  */
677 //--------------------------------------------------------------------------------------------------
679 (
680  const char* LE_NONNULL path,
681  ///< [IN]
682  bool value
683  ///< [IN]
684 );
685 
686 //--------------------------------------------------------------------------------------------------
687 /**
688  * Gets the string value of an asset data.
689  *
690  * @return:
691  * - LE_BAD_PARAMETER - asset data being accessed is of the wrong data type
692  * - LE_UNAVAILABLE - asset data contains null value
693  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
694  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
695  * - LE_OVERFLOW - asset data length exceeds the maximum length
696  * - LE_OK - access successful
697  */
698 //--------------------------------------------------------------------------------------------------
700 (
701  const char* LE_NONNULL path,
702  ///< [IN]
703  char* value,
704  ///< [OUT]
705  size_t valueSize
706  ///< [IN]
707 );
708 
709 //--------------------------------------------------------------------------------------------------
710 /**
711  * Sets an asset data to a string value.
712  *
713  * @return:
714  * - LE_NOT_FOUND - if the path is invalid and does not point to an asset data
715  * - LE_NOT_PERMITTED - asset data being accessed does not have the right permission
716  * - LE_OK - access successful.
717  */
718 //--------------------------------------------------------------------------------------------------
720 (
721  const char* LE_NONNULL path,
722  ///< [IN]
723  const char* LE_NONNULL value
724  ///< [IN]
725 );
726 
727 //--------------------------------------------------------------------------------------------------
728 /**
729  * Get the bool argument with the specified name.
730  *
731  * @return:
732  * - LE_OK on success
733  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
734  */
735 //--------------------------------------------------------------------------------------------------
737 (
738  le_avdata_ArgumentListRef_t argumentListRef,
739  ///< [IN]
740  const char* LE_NONNULL argName,
741  ///< [IN]
742  bool* boolArgPtr
743  ///< [OUT]
744 );
745 
746 //--------------------------------------------------------------------------------------------------
747 /**
748  * Get the float argument with the specified name.
749  *
750  * @return:
751  * - LE_OK on success
752  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
753  */
754 //--------------------------------------------------------------------------------------------------
756 (
757  le_avdata_ArgumentListRef_t argumentListRef,
758  ///< [IN]
759  const char* LE_NONNULL argName,
760  ///< [IN]
761  double* floatArgPtr
762  ///< [OUT]
763 );
764 
765 //--------------------------------------------------------------------------------------------------
766 /**
767  * Get the int argument with the specified name.
768  *
769  * @return:
770  * - LE_OK on success
771  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
772  */
773 //--------------------------------------------------------------------------------------------------
775 (
776  le_avdata_ArgumentListRef_t argumentListRef,
777  ///< [IN]
778  const char* LE_NONNULL argName,
779  ///< [IN]
780  int32_t* intArgPtr
781  ///< [OUT]
782 );
783 
784 //--------------------------------------------------------------------------------------------------
785 /**
786  * Get the string argument with the specified name.
787  *
788  * @return:
789  * - LE_OK on success
790  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API
791  * - LE_OVERFLOW - argument length exceeds the maximum length
792  */
793 //--------------------------------------------------------------------------------------------------
795 (
796  le_avdata_ArgumentListRef_t argumentListRef,
797  ///< [IN]
798  const char* LE_NONNULL argName,
799  ///< [IN]
800  char* strArg,
801  ///< [OUT]
802  size_t strArgSize
803  ///< [IN]
804 );
805 
806 //--------------------------------------------------------------------------------------------------
807 /**
808  * Get the length (excluding terminating null byte) of the string argument of the specified name.
809  *
810  * @return:
811  * - LE_OK on success
812  * - LE_NOT_FOUND if argument doesn't exist, or its data type doesn't match the API.
813  */
814 //--------------------------------------------------------------------------------------------------
816 (
817  le_avdata_ArgumentListRef_t argumentListRef,
818  ///< [IN]
819  const char* LE_NONNULL argName,
820  ///< [IN]
821  int32_t* strArgLenPtr
822  ///< [OUT]
823 );
824 
825 //--------------------------------------------------------------------------------------------------
826 /**
827  * Reply command execution result to AVC Daemon, which can then respond to AV server. This function
828  * MUST be called at the end of a command execution, in order for AV server to be notified about the
829  * execution status.
830  */
831 //--------------------------------------------------------------------------------------------------
833 (
834  le_avdata_ArgumentListRef_t argumentListRef,
835  ///< [IN]
836  le_result_t result
837  ///< [IN]
838 );
839 
840 //--------------------------------------------------------------------------------------------------
841 /**
842  * Push asset data to the server.
843  *
844  * @return:
845  * - LE_OK on success
846  * - LE_NOT_FOUND if the provided path doesn't exist
847  * - LE_BUSY if push service is busy. Data added to queue list for later push
848  * - LE_OVERFLOW if data size exceeds the maximum allowed size
849  * - LE_NO_MEMORY if push queue is full, try again later
850  * - LE_FAULT on any other error
851  */
852 //--------------------------------------------------------------------------------------------------
854 (
855  const char* LE_NONNULL path,
856  ///< [IN]
857  le_avdata_CallbackResultFunc_t handlerPtr,
858  ///< [IN]
859  void* contextPtr
860  ///< [IN]
861 );
862 
863 //--------------------------------------------------------------------------------------------------
864 /**
865  * Push data dump to a specified path on the server.
866  *
867  * @return:
868  * - LE_OK on success
869  * - LE_BUSY if push service is busy. Data added to queue list for later push
870  * - LE_OVERFLOW if data size exceeds the maximum allowed size
871  * - LE_NO_MEMORY if push queue is full, try again later
872  * - LE_FAULT on any other error
873  */
874 //--------------------------------------------------------------------------------------------------
876 (
877  const char* LE_NONNULL path,
878  ///< [IN]
879  int fd,
880  ///< [IN]
881  le_avdata_CallbackResultFunc_t handlerPtr,
882  ///< [IN]
883  void* contextPtr
884  ///< [IN]
885 );
886 
887 //--------------------------------------------------------------------------------------------------
888 /**
889  * Create a timeseries record
890  *
891  * @return Reference to the record
892  */
893 //--------------------------------------------------------------------------------------------------
894 le_avdata_RecordRef_t le_avdata_CreateRecord
895 (
896  void
897 );
898 
899 //--------------------------------------------------------------------------------------------------
900 /**
901  * Delete a timeseries record
902  */
903 //--------------------------------------------------------------------------------------------------
905 (
906  le_avdata_RecordRef_t recordRef
907  ///< [IN]
908 );
909 
910 //--------------------------------------------------------------------------------------------------
911 /**
912  * Accumulate int data
913  *
914  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
915  *
916  * @return:
917  * - LE_OK on success
918  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
919  * - LE_FAULT on any other error
920  */
921 //--------------------------------------------------------------------------------------------------
923 (
924  le_avdata_RecordRef_t recordRef,
925  ///< [IN]
926  const char* LE_NONNULL path,
927  ///< [IN]
928  int32_t value,
929  ///< [IN]
930  uint64_t timestamp
931  ///< [IN]
932 );
933 
934 //--------------------------------------------------------------------------------------------------
935 /**
936  * Accumulate float data
937  *
938  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
939  *
940  * @return:
941  * - LE_OK on success
942  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
943  * - LE_FAULT on any other error
944  */
945 //--------------------------------------------------------------------------------------------------
947 (
948  le_avdata_RecordRef_t recordRef,
949  ///< [IN]
950  const char* LE_NONNULL path,
951  ///< [IN]
952  double value,
953  ///< [IN]
954  uint64_t timestamp
955  ///< [IN]
956 );
957 
958 //--------------------------------------------------------------------------------------------------
959 /**
960  * Accumulate boolean data
961  *
962  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
963  *
964  * @return:
965  * - LE_OK on success
966  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
967  * - LE_FAULT on any other error
968  */
969 //--------------------------------------------------------------------------------------------------
971 (
972  le_avdata_RecordRef_t recordRef,
973  ///< [IN]
974  const char* LE_NONNULL path,
975  ///< [IN]
976  bool value,
977  ///< [IN]
978  uint64_t timestamp
979  ///< [IN]
980 );
981 
982 //--------------------------------------------------------------------------------------------------
983 /**
984  * Accumulate string data
985  *
986  * @note The client will be terminated if the recordRef is not valid, or the resource doesn't exist
987  *
988  * @return:
989  * - LE_OK on success
990  * - LE_NO_MEMORY if the current entry was NOT added because the time series buffer is full.
991  * - LE_FAULT on any other error
992  */
993 //--------------------------------------------------------------------------------------------------
995 (
996  le_avdata_RecordRef_t recordRef,
997  ///< [IN]
998  const char* LE_NONNULL path,
999  ///< [IN]
1000  const char* LE_NONNULL value,
1001  ///< [IN]
1002  uint64_t timestamp
1003  ///< [IN]
1004 );
1005 
1006 //--------------------------------------------------------------------------------------------------
1007 /**
1008  * Push record to the server
1009  *
1010  ** @return:
1011  * - LE_OK on success
1012  * - LE_BUSY if push service is busy. Data added to queue list for later push
1013  * - LE_OVERFLOW if data size exceeds the maximum allowed size
1014  * - LE_NO_MEMORY if push queue is full, try again later
1015  * - LE_FAULT on any other error
1016  *
1017  * * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1018  * function will not return.
1019  */
1020 //--------------------------------------------------------------------------------------------------
1022 (
1023  le_avdata_RecordRef_t recordRef,
1024  ///< [IN]
1025  le_avdata_CallbackResultFunc_t handlerPtr,
1026  ///< [IN]
1027  void* contextPtr
1028  ///< [IN]
1029 );
1030 
1031 //--------------------------------------------------------------------------------------------------
1032 /**
1033  * Add handler function for EVENT 'le_avdata_SessionState'
1034  *
1035  * This event provides information on AV session state changes
1036  */
1037 //--------------------------------------------------------------------------------------------------
1038 le_avdata_SessionStateHandlerRef_t le_avdata_AddSessionStateHandler
1039 (
1040  le_avdata_SessionStateHandlerFunc_t handlerPtr,
1041  ///< [IN]
1042  void* contextPtr
1043  ///< [IN]
1044 );
1045 
1046 //--------------------------------------------------------------------------------------------------
1047 /**
1048  * Remove handler function for EVENT 'le_avdata_SessionState'
1049  */
1050 //--------------------------------------------------------------------------------------------------
1052 (
1053  le_avdata_SessionStateHandlerRef_t handlerRef
1054  ///< [IN]
1055 );
1056 
1057 //--------------------------------------------------------------------------------------------------
1058 /**
1059  * Request the avcServer to open a session.
1060  *
1061  * @return
1062  * - SessionRef if session request succeeded
1063  * - NULL if session request failed
1064  */
1065 //--------------------------------------------------------------------------------------------------
1066 le_avdata_RequestSessionObjRef_t le_avdata_RequestSession
1067 (
1068  void
1069 );
1070 
1071 //--------------------------------------------------------------------------------------------------
1072 /**
1073  * Request the avcServer to close a session.
1074  *
1075  */
1076 //--------------------------------------------------------------------------------------------------
1078 (
1079  le_avdata_RequestSessionObjRef_t requestRef
1080  ///< [IN] Reference to a previously opened AV session.
1081 );
1082 
1083 #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)
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:45
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_SetNull(const char *LE_NONNULL path)
le_avdata_SessionStateHandlerRef_t le_avdata_AddSessionStateHandler(le_avdata_SessionStateHandlerFunc_t handlerPtr, void *contextPtr)
void le_avdata_ReleaseSession(le_avdata_RequestSessionObjRef_t requestRef)
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)
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)
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:305
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_RecordBool(le_avdata_RecordRef_t recordRef, const char *LE_NONNULL path, bool value, uint64_t timestamp)
LE_FULL_API void le_avdata_SetServerDisconnectHandler(le_avdata_DisconnectHandler_t disconnectHandler, void *contextPtr)
void le_avdata_ConnectService(void)
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)
le_result_t le_avdata_TryConnectService(void)
le_result_t le_avdata_SetFloat(const char *LE_NONNULL path, double value)
le_result_t le_avdata_GetFloatArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, double *floatArgPtr)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_avdata_SetNamespace(le_avdata_Namespace_t _namespace)
le_avdata_ResourceEventHandlerRef_t le_avdata_AddResourceEventHandler(const char *LE_NONNULL path, le_avdata_ResourceHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_avdata_GetIntArg(le_avdata_ArgumentListRef_t argumentListRef, const char *LE_NONNULL argName, int32_t *intArgPtr)
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)
le_result_t le_avdata_SetBool(const char *LE_NONNULL path, bool value)
void le_avdata_RemoveSessionStateHandler(le_avdata_SessionStateHandlerRef_t handlerRef)