le_dcs_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_dcs le_dcs Interface
14  *
15  * @ref le_dcs_interface.h "API Reference" <br>
16  * @ref sampleApps_gpsApp "Sample code" <br>
17  *
18  * When applications need to exchange data with other devices on the packet switched data network,
19  * a data channel needs to be first established. After such channel is successfully established,
20  * then applications can open up IP sockets on this data channel as necessary as a data pipe for
21  * sending and receiving data.
22  *
23  * @section le_dcs_ChannelOps Channel Operations
24  *
25  * The Data Channel Service (DCS) provides an API interface for a client application to learn
26  * about all the data channels available on a device, and administratively start or stop a selected
27  * channel. Data channels that are managed by DCS can be shared by multiple applications.
28  *
29  * @note In the context of this documentation the acronym DCS refers to the @c le_dcs
30  * interface, unless specified otherwise.
31  *
32  * When one application asks DCS to start a specified channel, DCS associates it with this channel;
33  * similarly when it asks DCS to stop this channel, DCS disassociates it from its use. Therefore,
34  * in this way what a client application sees and gets as a channel's state is its administrative
35  * state, not its operational state. A channel is operationally brought up when its
36  * administratively state goes up to indicate that it is needed by at least one application.
37  * Similarly, it is operationally brought down when its administrative state goes down to indicate
38  * that it is needed by no application anymore. Thus, it is possible for a chanel to be
39  * administratively up, meaning that it is associated with some applications, but operationally
40  * down due to certain reasons, including network errors, weak signal, temporary downtime, etc.
41  *
42  * @section le_dcs_ChannelReferenceUniqueID Channel Reference
43  *
44  * Since DCS provides channel choices, a channel's object reference is used in most of its APIs
45  * as the input identifier to uniquely identify the channel of choice. This channel reference is
46  * unique across the device over all supported technologies, and is managed and provided by DCS.
47  *
48  * Before a channel can be specified as an input argument of choice, an application needs to
49  * call le_dcs_GetChannels() to get the list of all channels and from those results learn about
50  * each one's channel reference for use in any other @c le_dcs and le_net API calls.
51  *
52  * @section le_dcs_RelateToLeNet le_net Interface
53  *
54  * Associated with the @c le_dcs interface, the @c le_net interface provides network services to
55  * DCS-managed channels. @c le_net provides APIs for setting the device's default gateway
56  * addresses, DNS server addresses, adding routes, etc.
57  *
58  * @section le_dcs_TechConfigs Technical Configurations
59  *
60  * With the use of le_data, there used to be technology-specific configurations saved in Legato's
61  * configuration tree under DCS's paths. @c le_dcs expanded DCS's capabilities to
62  * modularize technology-specific implementations and support multiple active channels over
63  * different technologies simultaneously, @c le_dcs no longer keeps technology-specific
64  * configurations under its tree paths.
65  *
66  * For WiFi-specific configurations, the @c le_dcs interface no longer saves them on its common
67  * path dataConnectionService:/wifi/SSID. Per-SSID configurations are saved now on the wifiService
68  * path under the SSID name itself, e.g. wifiService:/wifi/channel/MY-MOBILE/setProtocol
69  * and wifiService:/wifi/channel/MY-WLAN/hidden where MY-MOBILE and MY-WLAN are both SSIDs.
70  * Moreover, confidential user credentials, like passphrase, PSK, user name with password, are now
71  * kept in secure storage. In the case of WiFi, these are kept and managed there by the
72  * wifiClient, only through which reading and writing of such info can be done. Note that the WiFi
73  * security protocol used for each SSID remains on the config tree mentioned above for easy
74  * reference and debugging. In this way, @c le_dcs keeps technology-specific configurations on the
75  * path of the technology itself.
76  *
77  * Example of WiFi Config:
78  * @verbatim
79  wifiService:/
80  wifi/
81  channel/
82  MY-MOBILE/
83  secProtocol<string> == 3
84  MY-WLAN/
85  secProtocol<string> == 3
86  hidden<bool> == true
87  @endverbatim
88  *
89  * The above illustration shows that under this new path structure multiple configurations for
90  * multiple channels can be stored and easily expanded for future needs.
91  * For more details about WiFi configurations, please refer to @ref le_wifiClient_interface.h.
92  *
93  * For cellular-specific configurations, each time a cellular channel needs to be
94  * specified as an input argument in calling a @c le_dcs API.@c le_dcs does
95  * not use nor refer to the default cellular profile index saved under the path
96  * dataConnectionService:/cellular/profileIndex.
97  *
98  * @section le_dcs_APIOverview API Overview
99  *
100  * The @c le_dcs APIs provide applications the interfaces to:
101  *
102  *
103  * | Function | Description |
104  * | -------------------------------| -----------------------------------------------------------------------------------------|
105  * | le_dcs_GetChannels() | Retrieves the list of all available channels across all supported technologies |
106  * | le_dcs_GetTechnology() | Queries for a channel reference's technology type |
107  * | le_dcs_GetReference() | Queries for a channel's reference by its name and technology |
108  * | le_dcs_GetState() | Queries for a channel's administrative state and network interface name by its reference |
109  * | le_dcs_AddEventHandler() | Adds a channel event notification handler for a specific channel |
110  * | le_dcs_RemoveEventHandler() | Removes a channel event notification handler for a specific channel |
111  * | le_dcs_Start() | Starts a channel |
112  * | le_dcs_Stop() | Stops a channel |
113  *
114  *
115  * @subsection le_dcs_APIDetails_GetChannels Get Channel
116  *
117  * For an application that seeks to use the @c le_dcs APIs, the first step is to call
118  * le_dcs_GetChannels() to obtain an up-to-date list of all channels available over all supported
119  * technologies on which are the channel reference and technology type of each available channel.
120  * The channel that the app wishes to communicate with can then be chosen from this list.
121  *
122  * @note To call le_dcs_GetChannels() the application needs to provide a handler function
123  * to handle the results to be returned, and wait until such results come back before calling
124  * subsequent @c le_dcs APIs. le_dcs_GetChannels() is asynchronous, due to need of some technologies
125  * to actively re-scan for their latest lists of available channels, i.e., WiFi.
126  *
127  * @note Moreover, on the returned channel list the channel state of each channel is provided.
128  * However, it is a dynamic parameter which value might keep changing and is, thus, included as
129  * a result only for reference. Client apps need to know that it was a value retrieved at the
130  * moment when DCS performed the channel query, but may not necessarily stay the same when they
131  * get it as part of the channel list results.
132  *
133  * Example of le_dcs_GetChannels():
134  * @code
135  * // This is the callback function for handling the results of a channel list query
136  * static void ClientChannelQueryHandler
137  * (
138  * le_result_t result, ///< [IN] Result of the query
139  * const le_dcs_ChannelInfo_t *channelList, ///< [IN] Channel list returned
140  * size_t channelListSize, ///< [IN] Channel list's size
141  * void *contextPtr ///< [IN] Associated user context pointer
142  * )
143  * {
144  * uint16_t i;
145  *
146  * LE_INFO("Received channel query result %d, channel list size %d", result, channelListSize);
147  *
148  * if (channelListSize == 0)
149  * {
150  * return;
151  * }
152  *
153  * for (i = 0; i < channelListSize; i++)
154  * {
155  * LE_INFO("Available channel #%d: name %s from technology %d, state %d, reference %p",
156  * i + 1, channelList[i].name, channelList[i].technology, channelList[i].state,
157  * channelList[i].ref);
158  * }
159  * }
160  *
161  * // This is the function initiating a channel list query
162  * void ClientGetChannels
163  * (
164  * void
165  * )
166  * {
167  * le_dcs_GetChannels(ClientChannelQueryHandler, NULL);
168  * }
169  * @endcode
170  *
171  * @subsection le_dcs_APIDetails_GetReference Get Channel Reference
172  *
173  * If an application wants to user @c le_dcs over a channel that is already known and won't come
174  * and go frequently, i.e., a cellular channel, then the app can learn
175  * about its channel reference via either le_dcs_GetChannels() or le_dcs_GetReference().
176  * le_dcs_GetChannels() provides better reliability, le_dcs_GetReference() is a synchronous
177  * transaction that provides the technology and channel type faster but without the reliability of
178  * le_dcs_GetChannels().
179  *
180  * Example of le_dcs_GetChannels() used to retrieve a specific channel's channel reference:
181  * @code
182  * void ClientGetReference
183  * (
184  * char channelName[LE_DCS_CHANNEL_NAME_MAX_LEN],
185  * le_dcs_Technology_t channelTech
186  * )
187  * {
188  * le_dcs_ChannelRef_t ref = le_dcs_GetReference(channelName, channelTech);
189  * if (ref == 0)
190  * {
191  * LE_ERROR("Failed to retrieve channel reference for channel %s of tech %d",
192  * channelName, channelTech);
193  * return;
194  * }
195  * LE_INFO("Retrieved channel reference %p for channel %s of tech %d", channelName,
196  * channelTech, ref);
197  * }
198  * @endcode
199  *
200  * @subsection le_dcs_APIDetails_GetTechnology Channel Technology
201  *
202  * DCS provides le_dcs_GetTechnology() to applications for querying for the technology type of
203  * a known channel reference. This should be used when those applications are seeking to
204  * remember all channel references returned via le_dcs_GetChannels() but not all the details about
205  * each channel.
206  *
207  * Example over how to use le_dcs_GetTechnology():
208  * @code
209  * void ClientGetTechnology
210  * (
211  * le_dcs_ChannelRef_t channelRef
212  * )
213  * {
214  * le_dcs_Technology_t channelTech = le_dcs_GetTechnology(channelRef);
215  * LE_INFO("Retrieved tech type %d for channel reference %p ", channelTech, channelRef);
216  * }
217  * @endcode
218  *
219  * @subsection le_dcs_APIDetails_GetState Channel State
220  *
221  * As a channel's administrative state might change over time, le_dcs_GetState() queries for
222  * a given channel's up-to-date state.
223  *
224  * Example of checking for State:
225  * @code
226  * void ClientGetAdminState
227  * (
228  * le_dcs_ChannelRef_t channelRef
229  * )
230  * {
231  * le_dcs_State_t state;
232  * char interfaceName[LE_DCS_INTERFACE_NAME_MAX_LEN+1];
233  * le_result_t ret;
234  *
235  * ret = le_dcs_GetState(channelRef, &state, interfaceName, LE_DCS_INTERFACE_NAME_MAX_LEN);
236  * if (LE_OK != ret)
237  * {
238  * LE_ERROR("Failed to get admin state of channel reference %p; return code %d",
239  * channelRef, ret);
240  * return;
241  * }
242  * LE_INFO("Retrieved for channel reference %s network interface %s, admin state %s",
243  * channelRef, interfaceName, (state==LE_DCS_STATE_UP) ? "up" : "down");
244  * }
245  * @endcode
246  *
247  * @subsection le_dcsAPIDetails_EventHandler Channel Event Handler
248  *
249  * Applications that want to be kept posted about any state changes of the channel can fulfill this
250  * need by providing DCS a channel event handler via le_dcs_AddEventHandler() per channel.
251  * For each channel managed by le_dcs, there could be a chain of event handlers provided by multiple
252  * applications interested in it. After an application is disassociated from a channel or
253  * uninterested in it, it can call le_dcs_RemoveEventHandler() to remove its event handler.
254  *
255  * Example of checking for state within an event handler:
256  * @code
257  * static void clientEventHandler
258  * (
259  * le_dcs_ChannelRef_t channelRef, ///< [IN] The channel for which the event is
260  * le_dcs_Event_t event, ///< [IN] Event up, down or temp-down
261  * int32_t code, ///< [IN] Additional event code, like error code
262  * void *contextPtr ///< [IN] Associated user context pointer
263  * )
264  * {
265  * char *eventString;
266  * switch (event)
267  * {
268  * case LE_DCS_EVENT_UP:
269  * eventString = "Up";
270  * break;
271  * case LE_DCS_EVENT_DOWN:
272  * eventString = "Down";
273  * break;
274  * case LE_DCS_EVENT_TEMP_DOWN:
275  * eventString = "Temporary Down";
276  * break;
277  * default:
278  * eventString = "Unknown";
279  * break;
280  * }
281  * LE_INFO("Received for channel reference %p event %s", channelRef,
282  * eventString, channelDb->channelName, appSessionRef);
283  * }
284  *
285  * void ClientAddEventHandler
286  * (
287  * le_dcs_ChannelRef_t channelRef,
288  * le_dcs_EventHandlerRef_t *eventHandlerRef
289  * )
290  * {
291  * if ((channelRef == 0) || !eventHandlerRef)
292  * {
293  * LE_ERROR("Invalid inputs for adding event handler for channel reference %p",
294  * channelRef);
295  * return;
296  * }
297  * *eventHandlerRef = le_dcs_AddEventHandler(channelRef, clientEventHandler, NULL);
298  * LE_INFO("Added event handler for channel reference %p; event handler reference %p",
299  * channelRef, *eventHandlerRef);
300  * }
301  *
302  * void ClientRemoveEventHandler
303  * (
304  * le_dcs_EventHandlerRef_t eventHandlerRef
305  * )
306  * {
307  * if (!eventHandlerRef)
308  * {
309  * LE_ERROR("Got null channel event handler to remove");
310  * return;
311  * }
312  * le_dcs_RemoveEventHandler(eventHandlerRef);
313  * }
314  * @endcode
315  *
316  * @subsubsection le_dcsAPIDetails_StartStop Starting and Stopping Channel
317  *
318  * The function for an application to start a selected data channel and associate itself with it is
319  * le_dcs_Start(), while the opposite to stop and disassociate with it is le_dcs_Stop().
320  *
321  * Example of starting and stoping a channel:
322  * @code
323  * void ClientStartChannel
324  * (
325  * le_dcs_ChannelRef_t channelRef,
326  * le_dcs_ReqObjRef_t *reqObj
327  * )
328  * {
329  * if ((channelRef == 0) || !reqObj)
330  * {
331  * LE_ERROR("Invalid inputs for starting channel with reference %p", channelRef);
332  * return;
333  * }
334  * *reqObj = le_dcs_Start(channelRef);
335  * LE_INFO("Started channel with reference %p and request reference %p", channelRef, *reqObj);
336  * }
337  *
338  * void ClientStopChannel
339  * (
340  * le_dcs_ReqObjRef_t reqObj
341  * )
342  * {
343  * le_result_t ret;
344  * if (!reqObj)
345  * {
346  * LE_ERROR("Invalid input for stopping channel with request reference %p", reqObj);
347  * return;
348  * }
349  *
350  * ret = le_dcs_Stop(reqObj);
351  * LE_INFO("Stopped channel with request reference %p, release status %d", reqObj, ret);
352  * }
353  * @endcode
354  *
355  * @section le_dcs_ConnectionFailure Handling of Connection Failures
356  *
357  * With the @c le_dcs interface, connection failures over a channel are handled within the channel
358  * itself. Connection retries over another channel of the same or different technology will not be
359  * internally attempted like with the @c le_data interface.
360  *
361  * If the channel fails the default behavior is for DCS to try to reconnect over the same
362  * channel. If a different channel is wanted to be tried as a backup that logic and direction needs
363  * to be added to the application logic. If there is an issue with a channel, the application
364  * associated with the channel needs to disassociate from it and re-associate with another channel.
365  *
366  * Technology-specific conditions and custom-made handlings in @c le_dcs are now implemented and
367  * attempted within the technology itself, i.e. the default behavior for cellular channels will
368  * have a different behavior than WiFi's.
369  *
370  * Best practices are to retry a reconnect over a certain limited duration with a back-off duration.
371  * After all allowed attempts have exhausted with no success, then DCS will send a channel down
372  * event notification to the interested applications and stop the retries. In situations
373  * involving a system-wide blackout, one example is in the cellular packet switched state's becoming
374  * false, a retry won't be attempted until its recovery, i.e. in the example the cellular packet
375  * switched state's going back to true, where DCS will resume retrying to reconnect back all the
376  * channels of the corresponding technology that are administratively up.
377  *
378  * It is very necessary to note that for some technologies after a channel has failed and then
379  * reconnected back, the network interface and IP address assigned to its use might have changed
380  * (depending on settings like DHCP). The default gateway and DNS addresses for this channel might
381  * have changed as well and applications must take this into account and might need to re-adjust
382  * the routes and/or gateway address settings after a channel state flapped.
383  *
384  * Copyright (C) Sierra Wireless Inc.
385  */
386 /**
387  * @file le_dcs_interface.h
388  *
389  * Legato @ref c_le_dcs include file.
390  *
391  * Copyright (C) Sierra Wireless Inc.
392  */
393 
394 #ifndef LE_DCS_INTERFACE_H_INCLUDE_GUARD
395 #define LE_DCS_INTERFACE_H_INCLUDE_GUARD
396 
397 
398 #include "legato.h"
399 
400 // Internal includes for this interface
401 #include "le_dcs_common.h"
402 //--------------------------------------------------------------------------------------------------
403 /**
404  * Type for handler called when a server disconnects.
405  */
406 //--------------------------------------------------------------------------------------------------
407 typedef void (*le_dcs_DisconnectHandler_t)(void *);
408 
409 //--------------------------------------------------------------------------------------------------
410 /**
411  *
412  * Connect the current client thread to the service providing this API. Block until the service is
413  * available.
414  *
415  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
416  * called before any other functions in this API. Normally, ConnectService is automatically called
417  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
418  *
419  * This function is created automatically.
420  */
421 //--------------------------------------------------------------------------------------------------
423 (
424  void
425 );
426 
427 //--------------------------------------------------------------------------------------------------
428 /**
429  *
430  * Try to connect the current client thread to the service providing this API. Return with an error
431  * if the service is not available.
432  *
433  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
434  * called before any other functions in this API. Normally, ConnectService is automatically called
435  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
436  *
437  * This function is created automatically.
438  *
439  * @return
440  * - LE_OK if the client connected successfully to the service.
441  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
442  * bound.
443  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
444  * - LE_COMM_ERROR if the Service Directory cannot be reached.
445  */
446 //--------------------------------------------------------------------------------------------------
448 (
449  void
450 );
451 
452 //--------------------------------------------------------------------------------------------------
453 /**
454  * Set handler called when server disconnection is detected.
455  *
456  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
457  * to continue without exiting, it should call longjmp() from inside the handler.
458  */
459 //--------------------------------------------------------------------------------------------------
461 (
462  le_dcs_DisconnectHandler_t disconnectHandler,
463  void *contextPtr
464 );
465 
466 //--------------------------------------------------------------------------------------------------
467 /**
468  *
469  * Disconnect the current client thread from the service providing this API.
470  *
471  * Normally, this function doesn't need to be called. After this function is called, there's no
472  * longer a connection to the service, and the functions in this API can't be used. For details, see
473  * @ref apiFilesC_client.
474  *
475  * This function is created automatically.
476  */
477 //--------------------------------------------------------------------------------------------------
479 (
480  void
481 );
482 
483 
484 //--------------------------------------------------------------------------------------------------
485 /**
486  * Reference returned by Request function and used by Release function
487  */
488 //--------------------------------------------------------------------------------------------------
489 
490 
491 //--------------------------------------------------------------------------------------------------
492 /**
493  * Reference to a data channel
494  */
495 //--------------------------------------------------------------------------------------------------
496 
497 
498 //--------------------------------------------------------------------------------------------------
499 /**
500  * Technologies.
501  */
502 //--------------------------------------------------------------------------------------------------
503 
504 
505 //--------------------------------------------------------------------------------------------------
506 /**
507  * Channel states.
508  */
509 //--------------------------------------------------------------------------------------------------
510 
511 
512 //--------------------------------------------------------------------------------------------------
513 /**
514  * Channel events: These are the data channel events in DCS' northbound towards client apps.
515  *
516  * The LE_DCS_EVENT_UP event for a given data channel means that it has been brought up and become
517  * usable.
518  *
519  * The LE_DCS_EVENT_DOWN event means that the given data channel has gone down, been disassociated
520  * from all the client apps which have called le_dcs_Start() to start it, and its technology has
521  * stopped to retry reconnecting it back further.
522  *
523  * The LE_DCS_EVEN_TEMP_DOWN event means, on the other hand, that the given data channel has
524  * temporarily gone down, but remains associated with those client apps which have called
525  * le_dcs_Start() to start but not yet le_dcs_Stop() to stop it, and its technology will
526  * continue to retry reconnecting it back after some backoff.
527  *
528  */
529 //--------------------------------------------------------------------------------------------------
530 
531 
532 //--------------------------------------------------------------------------------------------------
533 /**
534  * Handler for channel state changes
535  */
536 //--------------------------------------------------------------------------------------------------
537 
538 
539 //--------------------------------------------------------------------------------------------------
540 /**
541  * Reference type used by Add/Remove functions for EVENT 'le_dcs_Event'
542  */
543 //--------------------------------------------------------------------------------------------------
544 
545 
546 //--------------------------------------------------------------------------------------------------
547 /**
548  * This is the structure with info about each available channel
549  */
550 //--------------------------------------------------------------------------------------------------
551 
552 
553 //--------------------------------------------------------------------------------------------------
554 /**
555  * Handler for the receiving the results of a channel list query
556  */
557 //--------------------------------------------------------------------------------------------------
558 
559 
560 //--------------------------------------------------------------------------------------------------
561 /**
562  * Add handler function for EVENT 'le_dcs_Event'
563  *
564  * This event provides information on channel events
565  */
566 //--------------------------------------------------------------------------------------------------
567 le_dcs_EventHandlerRef_t le_dcs_AddEventHandler
568 (
569  le_dcs_ChannelRef_t channelRef,
570  ///< [IN] The channel for which the event is
571  le_dcs_EventHandlerFunc_t handlerPtr,
572  ///< [IN]
573  void* contextPtr
574  ///< [IN]
575 );
576 
577 //--------------------------------------------------------------------------------------------------
578 /**
579  * Remove handler function for EVENT 'le_dcs_Event'
580  */
581 //--------------------------------------------------------------------------------------------------
583 (
584  le_dcs_EventHandlerRef_t handlerRef
585  ///< [IN]
586 );
587 
588 //--------------------------------------------------------------------------------------------------
589 /**
590  * Query for a channel's technology type
591  *
592  * @return
593  * - The given channel's technology type as an enumberator from @ref le_dcs_Technology_t
594  */
595 //--------------------------------------------------------------------------------------------------
596 le_dcs_Technology_t le_dcs_GetTechnology
597 (
598  le_dcs_ChannelRef_t channelRef
599  ///< [IN] channel which technology type is to be queried
600 );
601 
602 //--------------------------------------------------------------------------------------------------
603 /**
604  * Query for a channel's administrative state
605  *
606  * @return
607  * - The given channel's state in the 2nd argument and associated network interface
608  * in 'name'
609  */
610 //--------------------------------------------------------------------------------------------------
612 (
613  le_dcs_ChannelRef_t channelRef,
614  ///< [IN] channel which status is to be queried
615  le_dcs_State_t* statePtr,
616  ///< [OUT] channel state returned as output
617  char* interfaceName,
618  ///< [OUT] channel's network interface name
619  size_t interfaceNameSize
620  ///< [IN]
621 );
622 
623 //--------------------------------------------------------------------------------------------------
624 /**
625  * Request by an app to start a data channel
626  *
627  * @return
628  * - Object reference to the request (to be used later for releasing the channel)
629  * - NULL if it has failed to process the request
630  */
631 //--------------------------------------------------------------------------------------------------
632 le_dcs_ReqObjRef_t le_dcs_Start
633 (
634  le_dcs_ChannelRef_t channelRef
635  ///< [IN] channel requested to be started
636 );
637 
638 //--------------------------------------------------------------------------------------------------
639 /**
640  * Stop for an app its previously started data channel
641  */
642 //--------------------------------------------------------------------------------------------------
644 (
645  le_dcs_ReqObjRef_t reqRef
646  ///< [IN] the start request's reference earlier returned
647 );
648 
649 //--------------------------------------------------------------------------------------------------
650 /**
651  * Get the object reference of the channel given by the name and its technology type in the first
652  * and second arguments as input
653  *
654  * @return
655  * - The retrieved channel reference is returned in the function's return value upon success.
656  * - Upon failure, 0 is returned back
657  */
658 //--------------------------------------------------------------------------------------------------
659 le_dcs_ChannelRef_t le_dcs_GetReference
660 (
661  const char* LE_NONNULL name,
662  ///< [IN] name of channel which reference is to be retrieved
663  le_dcs_Technology_t technology
664  ///< [IN] technology of the channel given by its name above
665 );
666 
667 //--------------------------------------------------------------------------------------------------
668 /**
669  * Trigger a query for the list of all available data channels that will be returned asynchronously
670  * via the ChannelQueryHandler callback notification
671  */
672 //--------------------------------------------------------------------------------------------------
674 (
675  le_dcs_GetChannelsHandlerFunc_t handlerPtr,
676  ///< [IN] requester's handler for receiving results
677  void* contextPtr
678  ///< [IN]
679 );
680 
681 #endif // LE_DCS_INTERFACE_H_INCLUDE_GUARD
le_dcs_EventHandlerRef_t le_dcs_AddEventHandler(le_dcs_ChannelRef_t channelRef, le_dcs_EventHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t
Definition: le_basics.h:45
le_result_t le_dcs_TryConnectService(void)
le_dcs_Technology_t le_dcs_GetTechnology(le_dcs_ChannelRef_t channelRef)
le_dcs_ReqObjRef_t le_dcs_Start(le_dcs_ChannelRef_t channelRef)
void le_dcs_ConnectService(void)
LE_FULL_API void le_dcs_SetServerDisconnectHandler(le_dcs_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_dcs_ChannelRef_t le_dcs_GetReference(const char *LE_NONNULL name, le_dcs_Technology_t technology)
void le_dcs_DisconnectService(void)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_dcs_Stop(le_dcs_ReqObjRef_t reqRef)
void le_dcs_RemoveEventHandler(le_dcs_EventHandlerRef_t handlerRef)
void(* le_dcs_DisconnectHandler_t)(void *)
Definition: le_dcs_interface.h:407
void le_dcs_GetChannels(le_dcs_GetChannelsHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_dcs_GetState(le_dcs_ChannelRef_t channelRef, le_dcs_State_t *statePtr, char *interfaceName, size_t interfaceNameSize)