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