le_avdata_interface.h

Go to the documentation of this file.
1 /*
2  * ====================== WARNING ======================
3  *
4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
5  * DO NOT MODIFY IN ANY WAY.
6  *
7  * ====================== WARNING ======================
8  */
9 
10 /**
11  * @page c_le_avdata AirVantage Data
12  *
13  * @ref le_avdata_interface.h "API Reference" <br>
14  * @ref howToAVData "How To Manage Data"
15  *
16  * <HR>
17  *
18  * This API provides a data service to allow apps to manage app-specific
19  * data on the AirVantage server.
20  *
21  * Data is setup as @b assets &mdash; a collection of fields that can be managed by the AirVantage
22  * server.
23  *
24  * An asset field is a single piece of information that can be managed by the Air Vantage server.
25  * There can be multiple fields in an asset.
26  *
27  * A field can be:
28  * - @c variable allows an app to set the value, and can be read from the AV server.
29  * - @c setting allows the AV server to set the value, and can be read by an app.
30  * - @c command allows the AV server to invoke a command or function in the app.
31  *
32  * All fields have names. Variable and setting fields also have a type. The possible field types,
33  * along with the default value are:
34  * - string (empty string)
35  * - integer (0)
36  * - float (0.0)
37  * - boolean (false)
38  * - binary (zero-length block).
39  *
40  * Default values can be overwritten in the asset definition. Currently, string, integer, float
41  * and boolean fields are supported; binary fields will be supported in the future.
42  *
43  *
44  * @section le_avdata_instance Asset Data Instances
45  *
46  * An app that needs to send data to the AirVantage server must first create an asset instance
47  * using le_avc_Create() with the name of the asset definition.
48  * Once an asset instance is created, the app can begin accessing the instance's fields.
49  *
50  * Multiple instances of the same asset can be created, as well as multiple instances of different
51  * assets.
52  *
53  * Asset definitions are specified in the @ref defFilesCdef_assets section of the app's @c cdef file.
54  *
55  * @section le_avdata_field Field Values and Activity
56  *
57  * Set functions are available to set variable field values. Get functions are
58  * available to get settings fields' values.
59  *
60  * An app can register a handler so that it can be called when activity occurs on a field.
61  * This is optional for variable and setting fields, but is required for command fields.
62  * - @c variable called when the field is read by the AV server. The
63  * app can then call the appropriate set function to provide a new value for the field.
64  * - @c setting called when the field has been updated by the AV server
65  * with a new value. The app can use the appropriate get function to retrieve the new value.
66  * - @c command called when the AV server wants to invoke a command. The
67  * app should perform an appropriate action or call a function to execute this command.
68  *
69  * Registered handlers are only called when the server performs the associated activity on
70  * a specific field of an asset instance. For example, a handler registered on a variable field will
71  * be called if the server reads only that field of an instance; it will not be called if the
72  * server reads the whole instance of an asset.
73  *
74  * Leaving it optional to register handlers for variable and setting fields allows an
75  * app to decide how it wants to access variable and setting fields. It can decide to
76  * only do something in response to the AV server, or it can work independently of the AV server
77  * updating variables when it has a new value, and reading settings only when it needs the value.
78  *
79  * @section le_avdata_observe Observe
80  *
81  * If the @ref howToAVData_enableObserve "Observe" is enabled, the AirVantage Server will send
82  * observe requests on all user-defined assets of an app.
83  *
84  * Whenever an app (asset) changes a field value by using le_avdata_Set*(), it'll trigger a
85  * notify if Observe is enabled on that asset. The notify contains only the value of the changed
86  * field.
87  *
88  * @section le_avdata_fatal Fatal Behavior
89  *
90  * An invalid asset name or field name is treated as a fatal error (i.e. non-recoverable)
91  * and will result in the client app being terminated.
92  *
93  * <HR>
94  *
95  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
96  */
97 /**
98  * @file le_avdata_interface.h
99  *
100  * Legato @ref c_le_avdata include file.
101  *
102  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
103  */
104 
105 #ifndef LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
106 #define LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
107 
108 
109 #include "legato.h"
110 
111 //--------------------------------------------------------------------------------------------------
112 /**
113  *
114  * Connect the current client thread to the service providing this API. Block until the service is
115  * available.
116  *
117  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
118  * called before any other functions in this API. Normally, ConnectService is automatically called
119  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
120  *
121  * This function is created automatically.
122  */
123 //--------------------------------------------------------------------------------------------------
125 (
126  void
127 );
128 
129 //--------------------------------------------------------------------------------------------------
130 /**
131  *
132  * Try to connect the current client thread to the service providing this API. Return with an error
133  * if the service is not available.
134  *
135  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
136  * called before any other functions in this API. Normally, ConnectService is automatically called
137  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
138  *
139  * This function is created automatically.
140  *
141  * @return
142  * - LE_OK if the client connected successfully to the service.
143  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
144  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
145  * - LE_COMM_ERROR if the Service Directory cannot be reached.
146  */
147 //--------------------------------------------------------------------------------------------------
149 (
150  void
151 );
152 
153 //--------------------------------------------------------------------------------------------------
154 /**
155  *
156  * Disconnect the current client thread from the service providing this API.
157  *
158  * Normally, this function doesn't need to be called. After this function is called, there's no
159  * longer a connection to the service, and the functions in this API can't be used. For details, see
160  * @ref apiFilesC_client.
161  *
162  * This function is created automatically.
163  */
164 //--------------------------------------------------------------------------------------------------
166 (
167  void
168 );
169 
170 
171 //--------------------------------------------------------------------------------------------------
172 /**
173  * An asset data instance reference
174  */
175 //--------------------------------------------------------------------------------------------------
176 typedef struct le_avdata_AssetInstance* le_avdata_AssetInstanceRef_t;
177 
178 
179 //--------------------------------------------------------------------------------------------------
180 /**
181  * Define the maximum length of an asset name (TODO: verify value)
182  */
183 //--------------------------------------------------------------------------------------------------
184 #define LE_AVDATA_ASSET_NAME_LEN 47
185 
186 
187 //--------------------------------------------------------------------------------------------------
188 /**
189  * Define the maximum length of a field name (TODO: verify value)
190  */
191 //--------------------------------------------------------------------------------------------------
192 #define LE_AVDATA_FIELD_NAME_LEN 47
193 
194 
195 //--------------------------------------------------------------------------------------------------
196 /**
197  * Define the maximum length of a string field (TODO: verify value)
198  */
199 //--------------------------------------------------------------------------------------------------
200 #define LE_AVDATA_STRING_VALUE_LEN 255
201 
202 
203 //--------------------------------------------------------------------------------------------------
204 /**
205  * Define the maximum length of a binary data field (TODO: verify value)
206  */
207 //--------------------------------------------------------------------------------------------------
208 #define LE_AVDATA_BINARY_VALUE_LEN 255
209 
210 
211 //--------------------------------------------------------------------------------------------------
212 /**
213  * Reference type used by Add/Remove functions for EVENT 'le_avdata_FieldEvent'
214  */
215 //--------------------------------------------------------------------------------------------------
216 typedef struct le_avdata_FieldEventHandler* le_avdata_FieldEventHandlerRef_t;
217 
218 
219 //--------------------------------------------------------------------------------------------------
220 /**
221  * Handler for field activity
222  *
223  * @param instRef
224  * @param fieldName
225  * @param contextPtr
226  */
227 //--------------------------------------------------------------------------------------------------
228 typedef void (*le_avdata_FieldHandlerFunc_t)
229 (
231  const char* fieldName,
232  void* contextPtr
233 );
234 
235 //--------------------------------------------------------------------------------------------------
236 /**
237  * Add handler function for EVENT 'le_avdata_FieldEvent'
238  *
239  * This event provides information on field activity
240  */
241 //--------------------------------------------------------------------------------------------------
243 (
245  ///< [IN]
246 
247  const char* fieldName,
248  ///< [IN]
249 
250  le_avdata_FieldHandlerFunc_t handlerPtr,
251  ///< [IN]
252 
253  void* contextPtr
254  ///< [IN]
255 );
256 
257 //--------------------------------------------------------------------------------------------------
258 /**
259  * Remove handler function for EVENT 'le_avdata_FieldEvent'
260  */
261 //--------------------------------------------------------------------------------------------------
263 (
265  ///< [IN]
266 );
267 
268 //--------------------------------------------------------------------------------------------------
269 /**
270  * Create an instance of AirVantage asset
271  *
272  * @return Reference to the asset instance
273  *
274  * @note It is a fatal error if the asset isn't defined.
275  */
276 //--------------------------------------------------------------------------------------------------
278 (
279  const char* assetName
280  ///< [IN]
281 );
282 
283 //--------------------------------------------------------------------------------------------------
284 /**
285  * Delete an instance of AirVantage asset
286  *
287  * @note It's a fatal error if the instRef isn't valid
288  */
289 //--------------------------------------------------------------------------------------------------
290 void le_avdata_Delete
291 (
293  ///< [IN]
294 );
295 
296 //--------------------------------------------------------------------------------------------------
297 /**
298  * Get the value of an integer setting field
299  *
300  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
301  */
302 //--------------------------------------------------------------------------------------------------
303 void le_avdata_GetInt
304 (
306  ///< [IN]
307 
308  const char* fieldName,
309  ///< [IN]
310 
311  int32_t* valuePtr
312  ///< [OUT]
313 );
314 
315 //--------------------------------------------------------------------------------------------------
316 /**
317  * Set the value of an integer variable field
318  *
319  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
320  */
321 //--------------------------------------------------------------------------------------------------
322 void le_avdata_SetInt
323 (
325  ///< [IN]
326 
327  const char* fieldName,
328  ///< [IN]
329 
330  int32_t value
331  ///< [IN]
332 );
333 
334 //--------------------------------------------------------------------------------------------------
335 /**
336  * Get the value of a float setting field
337  *
338  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
339  */
340 //--------------------------------------------------------------------------------------------------
342 (
344  ///< [IN]
345 
346  const char* fieldName,
347  ///< [IN]
348 
349  double* valuePtr
350  ///< [OUT]
351 );
352 
353 //--------------------------------------------------------------------------------------------------
354 /**
355  * Set the value of a float variable field
356  *
357  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
358  */
359 //--------------------------------------------------------------------------------------------------
361 (
363  ///< [IN]
364 
365  const char* fieldName,
366  ///< [IN]
367 
368  double value
369  ///< [IN]
370 );
371 
372 //--------------------------------------------------------------------------------------------------
373 /**
374  * Get the value of a boolean setting field
375  *
376  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
377  */
378 //--------------------------------------------------------------------------------------------------
380 (
382  ///< [IN]
383 
384  const char* fieldName,
385  ///< [IN]
386 
387  bool* valuePtr
388  ///< [OUT]
389 );
390 
391 //--------------------------------------------------------------------------------------------------
392 /**
393  * Set the value of a boolean variable field
394  *
395  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
396  */
397 //--------------------------------------------------------------------------------------------------
399 (
401  ///< [IN]
402 
403  const char* fieldName,
404  ///< [IN]
405 
406  bool value
407  ///< [IN]
408 );
409 
410 //--------------------------------------------------------------------------------------------------
411 /**
412  * Get the value of a string setting field
413  *
414  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
415  */
416 //--------------------------------------------------------------------------------------------------
418 (
420  ///< [IN]
421 
422  const char* fieldName,
423  ///< [IN]
424 
425  char* value,
426  ///< [OUT]
427 
428  size_t valueNumElements
429  ///< [IN]
430 );
431 
432 //--------------------------------------------------------------------------------------------------
433 /**
434  * Set the value of a string variable field
435  *
436  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
437  */
438 //--------------------------------------------------------------------------------------------------
440 (
442  ///< [IN]
443 
444  const char* fieldName,
445  ///< [IN]
446 
447  const char* value
448  ///< [IN]
449 );
450 
451 //--------------------------------------------------------------------------------------------------
452 /**
453  * Get the value of a binary data setting field
454  *
455  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
456  */
457 //--------------------------------------------------------------------------------------------------
459 (
461  ///< [IN]
462 
463  const char* fieldName,
464  ///< [IN]
465 
466  uint8_t* valuePtr,
467  ///< [OUT]
468 
469  size_t* valueNumElementsPtr
470  ///< [INOUT]
471 );
472 
473 //--------------------------------------------------------------------------------------------------
474 /**
475  * Set the value of a binary data variable field
476  *
477  * @note It's a fatal error if the instRef isn't valid, or the field doesn't exist
478  */
479 //--------------------------------------------------------------------------------------------------
481 (
483  ///< [IN]
484 
485  const char* fieldName,
486  ///< [IN]
487 
488  const uint8_t* valuePtr,
489  ///< [IN]
490 
491  size_t valueNumElements
492  ///< [IN]
493 );
494 
495 
496 #endif // LE_AVDATA_INTERFACE_H_INCLUDE_GUARD
497 
void le_avdata_Delete(le_avdata_AssetInstanceRef_t instRef)
void le_avdata_SetBool(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, bool value)
void le_avdata_RemoveFieldEventHandler(le_avdata_FieldEventHandlerRef_t addHandlerRef)
le_result_t
Definition: le_basics.h:35
void le_avdata_GetString(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, char *value, size_t valueNumElements)
void le_avdata_SetBinary(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, const uint8_t *valuePtr, size_t valueNumElements)
void(* le_avdata_FieldHandlerFunc_t)(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, void *contextPtr)
Definition: le_avdata_interface.h:229
void le_avdata_DisconnectService(void)
struct le_avdata_AssetInstance * le_avdata_AssetInstanceRef_t
Definition: le_avdata_interface.h:176
void le_avdata_ConnectService(void)
void le_avdata_GetFloat(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, double *valuePtr)
le_result_t le_avdata_TryConnectService(void)
void le_avdata_GetBinary(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, uint8_t *valuePtr, size_t *valueNumElementsPtr)
struct le_avdata_FieldEventHandler * le_avdata_FieldEventHandlerRef_t
Definition: le_avdata_interface.h:216
void le_avdata_GetInt(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, int32_t *valuePtr)
void le_avdata_SetFloat(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, double value)
le_avdata_AssetInstanceRef_t le_avdata_Create(const char *assetName)
le_avdata_FieldEventHandlerRef_t le_avdata_AddFieldEventHandler(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, le_avdata_FieldHandlerFunc_t handlerPtr, void *contextPtr)
void le_avdata_GetBool(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, bool *valuePtr)
void le_avdata_SetString(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, const char *value)
void le_avdata_SetInt(le_avdata_AssetInstanceRef_t instRef, const char *fieldName, int32_t value)