le_dcs_common.h

Go to the documentation of this file.
1 
2 /*
3  * ====================== WARNING ======================
4  *
5  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
6  * DO NOT MODIFY IN ANY WAY.
7  *
8  * ====================== WARNING ======================
9  */
10 /**
11  * @file le_dcs_common.h
12  *
13  * Type definitions for le_dcs.
14  *
15  */
16 #ifndef LE_DCS_COMMON_H_INCLUDE_GUARD
17 #define LE_DCS_COMMON_H_INCLUDE_GUARD
18 
19 
20 #include "legato.h"
21 
22 #define IFGEN_LE_DCS_PROTOCOL_ID "bc64c0ae1d3e02a79c05b7e92b1cd802"
23 #define IFGEN_LE_DCS_MSG_SIZE 3856
24 /** @addtogroup le_dcs
25  * @{ **/
26 
27 
28 //--------------------------------------------------------------------------------------------------
29 /**
30  * Interface name string length.
31  */
32 //--------------------------------------------------------------------------------------------------
33 #define LE_DCS_INTERFACE_NAME_MAX_LEN 100
34 
35 //--------------------------------------------------------------------------------------------------
36 /**
37  * Channel name string length.
38  */
39 //--------------------------------------------------------------------------------------------------
40 #define LE_DCS_CHANNEL_NAME_MAX_LEN 32
41 
42 //--------------------------------------------------------------------------------------------------
43 /**
44  * IP addr string's max length
45  */
46 //--------------------------------------------------------------------------------------------------
47 #define LE_DCS_IPADDR_MAX_LEN 46
48 
49 //--------------------------------------------------------------------------------------------------
50 /**
51  * Max # of channel list entries for a query: CHANNEL_LIST_QUERY_MAX is for per-technology, while
52  * CHANNEL_LIST_ENTRY_MAX is for all channels of all supported technologies. Currently, the former
53  * one's value is set to the max value supported by cellular. The latter is set to 2 times of that
54  * to support wifi. The extra 8 is for ethernet. When more technologies are supported, this value
55  * needs to be raised accordingly.
56  */
57 //--------------------------------------------------------------------------------------------------
58 #define LE_DCS_CHANNEL_LIST_QUERY_MAX 36
59 
60 //--------------------------------------------------------------------------------------------------
61 /**
62  */
63 //--------------------------------------------------------------------------------------------------
64 #define LE_DCS_CHANNEL_LIST_ENTRY_MAX 80
65 
66 //--------------------------------------------------------------------------------------------------
67 /**
68  * Reference returned by Request function and used by Release function
69  */
70 //--------------------------------------------------------------------------------------------------
71 typedef struct le_dcs_ReqObj* le_dcs_ReqObjRef_t;
72 
73 
74 //--------------------------------------------------------------------------------------------------
75 /**
76  * Reference to a data channel
77  */
78 //--------------------------------------------------------------------------------------------------
79 typedef struct le_dcs_Channel* le_dcs_ChannelRef_t;
80 
81 
82 //--------------------------------------------------------------------------------------------------
83 /**
84  * Technologies.
85  */
86 //--------------------------------------------------------------------------------------------------
87 typedef enum
88 {
89  LE_DCS_TECH_UNKNOWN = 0,
90  ///<
92  ///< Wi-Fi
94  ///< Cellular
96  ///< Ethernet
98  ///< Unknown state.
99 }
101 
102 
103 //--------------------------------------------------------------------------------------------------
104 /**
105  * Channel states.
106  */
107 //--------------------------------------------------------------------------------------------------
108 typedef enum
109 {
110  LE_DCS_STATE_DOWN = 0,
111  ///<
112  LE_DCS_STATE_UP = 1
113  ///<
114 }
116 
117 
118 //--------------------------------------------------------------------------------------------------
119 /**
120  * Channel events: These are the data channel events in DCS' northbound towards client apps.
121  *
122  * The LE_DCS_EVENT_UP event for a given data channel means that it has been brought up and become
123  * usable.
124  *
125  * The LE_DCS_EVENT_DOWN event means that the given data channel has gone down, been disassociated
126  * from all the client apps which have called le_dcs_Start() to start it, and its technology has
127  * stopped to retry reconnecting it back further.
128  *
129  * The LE_DCS_EVEN_TEMP_DOWN event means, on the other hand, that the given data channel has
130  * temporarily gone down, but remains associated with those client apps which have called
131  * le_dcs_Start() to start but not yet le_dcs_Stop() to stop it, and its technology will
132  * continue to retry reconnecting it back after some backoff.
133  *
134  */
135 //--------------------------------------------------------------------------------------------------
136 typedef enum
137 {
138  LE_DCS_EVENT_DOWN = 0,
139  ///<
140  LE_DCS_EVENT_UP = 1,
141  ///<
142  LE_DCS_EVENT_TEMP_DOWN = 2
143  ///<
144 }
146 
147 
148 //--------------------------------------------------------------------------------------------------
149 /**
150  * Reference type used by Add/Remove functions for EVENT 'le_dcs_Event'
151  */
152 //--------------------------------------------------------------------------------------------------
153 typedef struct le_dcs_EventHandler* le_dcs_EventHandlerRef_t;
154 
155 
156 //--------------------------------------------------------------------------------------------------
157 /**
158  * This is the structure with info about each available channel
159  */
160 //--------------------------------------------------------------------------------------------------
161 typedef struct
162 {
164  char name[32 + 1];
165  le_dcs_Technology_t technology;
166  le_dcs_State_t state;
167 }
169 
170 
171 //--------------------------------------------------------------------------------------------------
172 /**
173  * Handler for channel state changes
174  */
175 //--------------------------------------------------------------------------------------------------
176 typedef void (*le_dcs_EventHandlerFunc_t)
177 (
178  le_dcs_ChannelRef_t channelRef,
179  ///< The channel for which the event is
180  le_dcs_Event_t event,
181  ///< Event up or down
182  int32_t code,
183  ///< Additional event code, like error code
184  void* contextPtr
185  ///<
186 );
187 
188 //--------------------------------------------------------------------------------------------------
189 /**
190  * Handler for the receiving the results of a channel list query
191  */
192 //--------------------------------------------------------------------------------------------------
193 typedef void (*le_dcs_GetChannelsHandlerFunc_t)
194 (
195  le_result_t result,
196  ///< Result of the channel list query
197  const le_dcs_ChannelInfo_t* channelListPtr,
198  ///< List of channels returned
199  size_t channelListSize,
200  ///<
201  void* contextPtr
202  ///<
203 );
204 
205 
206 //--------------------------------------------------------------------------------------------------
207 /**
208  * Get if this client bound locally.
209  */
210 //--------------------------------------------------------------------------------------------------
211 LE_SHARED bool ifgen_le_dcs_HasLocalBinding
212 (
213  void
214 );
215 
216 
217 //--------------------------------------------------------------------------------------------------
218 /**
219  * Init data that is common across all threads
220  */
221 //--------------------------------------------------------------------------------------------------
222 LE_SHARED void ifgen_le_dcs_InitCommonData
223 (
224  void
225 );
226 
227 
228 //--------------------------------------------------------------------------------------------------
229 /**
230  * Perform common initialization and open a session
231  */
232 //--------------------------------------------------------------------------------------------------
233 LE_SHARED le_result_t ifgen_le_dcs_OpenSession
234 (
235  le_msg_SessionRef_t _ifgen_sessionRef,
236  bool isBlocking
237 );
238 
239 //--------------------------------------------------------------------------------------------------
240 /**
241  * Add handler function for EVENT 'le_dcs_Event'
242  *
243  * This event provides information on channel events
244  */
245 //--------------------------------------------------------------------------------------------------
246 LE_SHARED le_dcs_EventHandlerRef_t ifgen_le_dcs_AddEventHandler
247 (
248  le_msg_SessionRef_t _ifgen_sessionRef,
249  le_dcs_ChannelRef_t channelRef,
250  ///< [IN] The channel for which the event is
251  le_dcs_EventHandlerFunc_t handlerPtr,
252  ///< [IN]
253  void* contextPtr
254  ///< [IN]
255 );
256 
257 //--------------------------------------------------------------------------------------------------
258 /**
259  * Remove handler function for EVENT 'le_dcs_Event'
260  */
261 //--------------------------------------------------------------------------------------------------
262 LE_SHARED void ifgen_le_dcs_RemoveEventHandler
263 (
264  le_msg_SessionRef_t _ifgen_sessionRef,
265  le_dcs_EventHandlerRef_t handlerRef
266  ///< [IN]
267 );
268 
269 //--------------------------------------------------------------------------------------------------
270 /**
271  * Query for a channel's technology type
272  *
273  * @return
274  * - The given channel's technology type as an enumberator from @ref le_dcs_Technology_t
275  */
276 //--------------------------------------------------------------------------------------------------
277 LE_SHARED le_dcs_Technology_t ifgen_le_dcs_GetTechnology
278 (
279  le_msg_SessionRef_t _ifgen_sessionRef,
280  le_dcs_ChannelRef_t channelRef
281  ///< [IN] channel which technology type is to be queried
282 );
283 
284 //--------------------------------------------------------------------------------------------------
285 /**
286  * Query for a channel's administrative state
287  *
288  * @return
289  * - The given channel's state in the 2nd argument and associated network interface
290  * in 'name'
291  */
292 //--------------------------------------------------------------------------------------------------
293 LE_SHARED le_result_t ifgen_le_dcs_GetState
294 (
295  le_msg_SessionRef_t _ifgen_sessionRef,
296  le_dcs_ChannelRef_t channelRef,
297  ///< [IN] channel which status is to be queried
298  le_dcs_State_t* statePtr,
299  ///< [OUT] channel state returned as output
300  char* interfaceName,
301  ///< [OUT] channel's network interface name
302  size_t interfaceNameSize
303  ///< [IN]
304 );
305 
306 //--------------------------------------------------------------------------------------------------
307 /**
308  * Request by an app to start a data channel
309  *
310  * @return
311  * - Object reference to the request (to be used later for releasing the channel)
312  * - NULL if it has failed to process the request
313  */
314 //--------------------------------------------------------------------------------------------------
315 LE_SHARED le_dcs_ReqObjRef_t ifgen_le_dcs_Start
316 (
317  le_msg_SessionRef_t _ifgen_sessionRef,
318  le_dcs_ChannelRef_t channelRef
319  ///< [IN] channel requested to be started
320 );
321 
322 //--------------------------------------------------------------------------------------------------
323 /**
324  * Stop for an app its previously started data channel
325  */
326 //--------------------------------------------------------------------------------------------------
327 LE_SHARED le_result_t ifgen_le_dcs_Stop
328 (
329  le_msg_SessionRef_t _ifgen_sessionRef,
330  le_dcs_ReqObjRef_t reqRef
331  ///< [IN] the start request's reference earlier returned
332 );
333 
334 //--------------------------------------------------------------------------------------------------
335 /**
336  * Get the object reference of the channel given by the name and its technology type in the first
337  * and second arguments as input
338  *
339  * @return
340  * - The retrieved channel reference is returned in the function's return value upon success.
341  * - Upon failure, 0 is returned back
342  */
343 //--------------------------------------------------------------------------------------------------
344 LE_SHARED le_dcs_ChannelRef_t ifgen_le_dcs_GetReference
345 (
346  le_msg_SessionRef_t _ifgen_sessionRef,
347  const char* LE_NONNULL name,
348  ///< [IN] name of channel which reference is to be retrieved
349  le_dcs_Technology_t technology
350  ///< [IN] technology of the channel given by its name above
351 );
352 
353 //--------------------------------------------------------------------------------------------------
354 /**
355  * Trigger a query for the list of all available data channels that will be returned asynchronously
356  * via the ChannelQueryHandler callback notification
357  */
358 //--------------------------------------------------------------------------------------------------
359 LE_SHARED void ifgen_le_dcs_GetChannels
360 (
361  le_msg_SessionRef_t _ifgen_sessionRef,
363  ///< [IN] requester's handler for receiving results
364  void* contextPtr
365  ///< [IN]
366 );
367 /** @} **/
368 #endif // LE_DCS_COMMON_H_INCLUDE_GUARD
Unknown state.
Definition: le_dcs_common.h:97
void(* le_dcs_EventHandlerFunc_t)(le_dcs_ChannelRef_t channelRef, le_dcs_Event_t event, int32_t code, void *contextPtr)
Definition: le_dcs_common.h:177
le_dcs_Event_t
Definition: le_dcs_common.h:136
#define LE_SHARED
Definition: le_basics.h:300
le_result_t
Definition: le_basics.h:46
struct le_dcs_ReqObj * le_dcs_ReqObjRef_t
Definition: le_dcs_common.h:71
struct le_dcs_EventHandler * le_dcs_EventHandlerRef_t
Definition: le_dcs_common.h:153
void(* le_dcs_GetChannelsHandlerFunc_t)(le_result_t result, const le_dcs_ChannelInfo_t *channelListPtr, size_t channelListSize, void *contextPtr)
Definition: le_dcs_common.h:194
Ethernet.
Definition: le_dcs_common.h:95
le_dcs_Technology_t
Definition: le_dcs_common.h:87
Definition: le_dcs_common.h:161
Cellular.
Definition: le_dcs_common.h:93
struct le_dcs_Channel * le_dcs_ChannelRef_t
Definition: le_dcs_common.h:79
struct le_msg_Session * le_msg_SessionRef_t
Definition: le_messaging.h:860
Wi-Fi.
Definition: le_dcs_common.h:91
le_dcs_State_t
Definition: le_dcs_common.h:108