le_dcs_interface.h

    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  * Example of le_dcs_GetChannels():
  127  * @code
  128  *    // This is the callback function for handling the results of a channel list query
  129  *    static void ClientChannelQueryHandler
  130  *    (
  131  *        le_result_t result,                       ///< [IN] Result of the query
  132  *        const le_dcs_ChannelInfo_t *channelList,  ///< [IN] Channel list returned
  133  *        size_t channelListSize,                   ///< [IN] Channel list's size
  134  *        void *contextPtr                          ///< [IN] Associated user context pointer
  135  *    )
  136  *    {
  137  *        uint16_t i;
  138  *
  139  *        LE_INFO("Received channel query result %d, channel list size %d", result, channelListSize);
  140  *
  141  *        if (channelListSize == 0)
  142  *        {
  143  *            return;
  144  *        }
  145  *
  146  *        for (i = 0; i < channelListSize; i++)
  147  *        {
  148  *            LE_INFO("Available channel #%d: name %s from technology %d, state %d, reference %p",
  149  *                    i + 1, channelList[i].name, channelList[i].technology, channelList[i].state,
  150  *                    channelList[i].ref);
  151  *        }
  152  *    }
  153  *
  154  *    // This is the function initiating a channel list query
  155  *    void ClientGetChannels
  156  *    (
  157  *        void
  158  *    )
  159  *    {
  160  *        le_dcs_GetChannels(ClientChannelQueryHandler, NULL);
  161  *    }
  162  *   @endcode
  163  *
  164  * @subsection le_dcs_APIDetails_GetReference Get Channel Reference
  165  *
  166  * If an application wants to user @c le_dcs over a channel that is already known and won't come
  167  * and go frequently, i.e., a cellular channel, then the app can learn
  168  * about its channel reference via either le_dcs_GetChannels() or le_dcs_GetReference().
  169  * le_dcs_GetChannels() provides better reliability, le_dcs_GetReference() is a synchronous
  170  * transaction that provides the technology and channel type faster but without the reliability of
  171  * le_dcs_GetChannels().
  172  *
  173  * Example of le_dcs_GetChannels() used to retrieve a specific channel's channel reference:
  174  * @code
  175  *    void ClientGetReference
  176  *    (
  177  *        char channelName[LE_DCS_CHANNEL_NAME_MAX_LEN],
  178  *        le_dcs_Technology_t channelTech
  179  *    )
  180  *    {
  181  *        le_dcs_ChannelRef_t ref = le_dcs_GetReference(channelName, channelTech);
  182  *        if (ref == 0)
  183  *        {
  184  *            LE_ERROR("Failed to retrieve channel reference for channel %s of tech %d",
  185  *                     channelName, channelTech);
  186  *            return;
  187  *        }
  188  *        LE_INFO("Retrieved channel reference %p for channel %s of tech %d", channelName,
  189  *                channelTech, ref);
  190  *    }
  191  *   @endcode
  192  *
  193  * @subsection le_dcs_APIDetails_GetTechnology Channel Technology
  194  *
  195  * DCS provides le_dcs_GetTechnology() to applications for querying for the technology type of
  196  * a known channel reference. This should be used when those applications are seeking to
  197  * remember all channel references returned via le_dcs_GetChannels() but not all the details about
  198  * each channel.
  199  *
  200  * Example over how to use le_dcs_GetTechnology():
  201  * @code
  202  *    void ClientGetTechnology
  203  *    (
  204  *        le_dcs_ChannelRef_t channelRef
  205  *    )
  206  *    {
  207  *        le_dcs_Technology_t channelTech = le_dcs_GetTechnology(channelRef);
  208  *        LE_INFO("Retrieved tech type %d for channel reference %p ", channelTech, channelRef);
  209  *    }
  210  *   @endcode
  211  *
  212  * @subsection le_dcs_APIDetails_GetState Channel State
  213  *
  214  * As a channel's administrative state might change over time, le_dcs_GetState() queries for
  215  * a given channel's up-to-date state.
  216  *
  217  * Example of checking for State:
  218  * @code
  219  *    void ClientGetAdminState
  220  *    (
  221  *        le_dcs_ChannelRef_t channelRef
  222  *    )
  223  *    {
  224  *        le_dcs_State_t state;
  225  *        char interfaceName[LE_DCS_INTERFACE_NAME_MAX_LEN+1];
  226  *        le_result_t ret;
  227  *
  228  *        ret = le_dcs_GetState(channelRef, &state, interfaceName, LE_DCS_INTERFACE_NAME_MAX_LEN);
  229  *        if (LE_OK != ret)
  230  *        {
  231  *            LE_ERROR("Failed to get admin state of channel reference %p; return code %d",
  232  *                     channelRef, ret);
  233  *            return;
  234  *        }
  235  *        LE_INFO("Retrieved for channel reference %s network interface %s, admin state %s",
  236  *                channelRef, interfaceName, (state==LE_DCS_STATE_UP) ? "up" : "down");
  237  *    }
  238  *   @endcode
  239  *
  240  * @subsection le_dcsAPIDetails_EventHandler Channel Event Handler
  241  *
  242  * Applications that want to be kept posted about any state changes of the channel can fulfill this
  243  * need by providing DCS a channel event handler via le_dcs_AddEventHandler() per channel.
  244  * For each channel managed by le_dcs, there could be a chain of event handlers provided by multiple
  245  * applications interested in it. After an application is disassociated from a channel or
  246  * uninterested in it, it can call le_dcs_RemoveEventHandler() to remove its event handler.
  247  *
  248  * Example of checking for state within an event handler:
  249  * @code
  250  *    static void clientEventHandler
  251  *    (
  252  *        le_dcs_ChannelRef_t channelRef, ///< [IN] The channel for which the event is
  253  *        le_dcs_Event_t event,           ///< [IN] Event up or down
  254  *        int32_t code,                   ///< [IN] Additional event code, like error code
  255  *        void *contextPtr                ///< [IN] Associated user context pointer
  256  *    )
  257  *    {
  258  *        LE_INFO("Received for channel reference %p event %s", channelRef,
  259  *                (event == LE_DCS_EVENT_UP) ? "Up" : "Down");
  260  *    }
  261  *
  262  *    void ClientAddEventHandler
  263  *    (
  264  *        le_dcs_ChannelRef_t channelRef,
  265  *        le_dcs_EventHandlerRef_t *eventHandlerRef
  266  *    )
  267  *    {
  268  *        if ((channelRef == 0) || !eventHandlerRef)
  269  *        {
  270  *            LE_ERROR("Invalid inputs for adding event handler for channel reference %p",
  271  *                     channelRef);
  272  *            return;
  273  *        }
  274  *        *eventHandlerRef = le_dcs_AddEventHandler(channelRef, clientEventHandler, NULL);
  275  *        LE_INFO("Added event handler for channel reference %p; event handler reference %p",
  276  *                channelRef, *eventHandlerRef);
  277  *    }
  278  *
  279  *    void ClientRemoveEventHandler
  280  *    (
  281  *        le_dcs_EventHandlerRef_t eventHandlerRef
  282  *    )
  283  *    {
  284  *        if (!eventHandlerRef)
  285  *        {
  286  *            LE_ERROR("Got null channel event handler to remove");
  287  *            return;
  288  *        }
  289  *        le_dcs_RemoveEventHandler(eventHandlerRef);
  290  *    }
  291  *   @endcode
  292  *
  293  * @subsubsection le_dcsAPIDetails_StartStop Starting and Stopping Channel
  294  *
  295  * The function for an application to start a selected data channel and associate itself with it is
  296  * le_dcs_Start(), while the opposite to stop and disassociate with it is le_dcs_Stop().
  297  *
  298  * Example of starting and stoping a channel:
  299  * @code
  300  *    void ClientStartChannel
  301  *    (
  302  *        le_dcs_ChannelRef_t channelRef,
  303  *        le_dcs_ReqObjRef_t *reqObj
  304  *    )
  305  *    {
  306  *  if ((channelRef == 0) || !reqObj)
  307  *        {
  308  *            LE_ERROR("Invalid inputs for starting channel with reference %p", channelRef);
  309  *            return;
  310  *        }
  311  *        *reqObj = le_dcs_Start(channelRef);
  312  *        LE_INFO("Started channel with reference %p and request reference %p", channelRef, *reqObj);
  313  *    }
  314  *
  315  *    void ClientStopChannel
  316  *    (
  317  *        le_dcs_ReqObjRef_t reqObj
  318  *    )
  319  *    {
  320  *        le_result_t ret;
  321  *        if (!reqObj)
  322  *        {
  323  *            LE_ERROR("Invalid input for stopping channel with request reference %p", reqObj);
  324  *            return;
  325  *        }
  326  *
  327  *        ret = le_dcs_Stop(reqObj);
  328  *        LE_INFO("Stopped channel with request reference %p, release status %d", reqObj, ret);
  329  *    }
  330  *   @endcode
  331  *
  332  * @section le_dcs_ConnectionFailure Handling of Connection Failures
  333  *
  334  * With the @c le_dcs interface, connection failures over a channel are handled within the channel
  335  * itself. Connection retries over another channel of the same or different technology will not be
  336  * internally attempted like with the @c le_data interface.
  337  *
  338  * If the channel fails the default behavior is for DCS to try to reconnect over the same
  339  * channel. If a different channel is wanted to be tried as a backup that logic and direction needs
  340  * to be added to the application logic. If there is an issue with a channel, the application
  341  * associated with the channel needs to disassociate from it and re-associate with another channel.
  342  *
  343  * Technology-specific conditions and custom-made handlings in @c le_dcs are now implemented and
  344  * attempted within the technology itself, i.e. the default behavior for cellular channels will
  345  * have a different behavior than WiFi's.
  346  *
  347  * Best practices are to retry a reconnect over a certain limited duration with a back-off duration.
  348  * After all allowed attempts have exhausted with no success, then DCS will send a channel down
  349  * event notification to the interested applications and stop the retries. In situations
  350  * involving a system-wide blackout, one example is in the cellular packet switched state's becoming
  351  * false, a retry won't be attempted until its recovery, i.e. in the example the cellular packet
  352  * switched state's going back to true, where DCS will resume retrying to reconnect back all the
  353  * channels of the corresponding technology that are administratively up.
  354  *
  355  * It is very necessary to note that for some technologies after a channel has failed and then
  356  * reconnected back, the network interface and IP address assigned to its use might have changed
  357  * (depending on settings like DHCP). The default gateway and DNS addresses for this channel might
  358  * have changed as well and applications must take this into account and might need to re-adjust
  359  * the routes and/or gateway address settings after a channel state flapped.
  360  *
  361  * Copyright (C) Sierra Wireless Inc.
  362  */
  363 /**
  364  * @file le_dcs_interface.h
  365  *
  366  * Legato @ref c_le_dcs include file.
  367  *
  368  * Copyright (C) Sierra Wireless Inc.
  369  */
  370 
  371 #ifndef LE_DCS_INTERFACE_H_INCLUDE_GUARD
  372 #define LE_DCS_INTERFACE_H_INCLUDE_GUARD
  373 
  374 
  375 #include "legato.h"
  376 
  377 // Internal includes for this interface
  378 #include "le_dcs_common.h"
  379 //--------------------------------------------------------------------------------------------------
  380 /**
  381  * Type for handler called when a server disconnects.
  382  */
  383 //--------------------------------------------------------------------------------------------------
  384 typedef void (*le_dcs_DisconnectHandler_t)(void *);
  385 
  386 //--------------------------------------------------------------------------------------------------
  387 /**
  388  *
  389  * Connect the current client thread to the service providing this API. Block until the service is
  390  * available.
  391  *
  392  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  393  * called before any other functions in this API.  Normally, ConnectService is automatically called
  394  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  395  *
  396  * This function is created automatically.
  397  */
  398 //--------------------------------------------------------------------------------------------------
  399 void le_dcs_ConnectService
  400 (
  401     void
  402 );
  403 
  404 //--------------------------------------------------------------------------------------------------
  405 /**
  406  *
  407  * Try to connect the current client thread to the service providing this API. Return with an error
  408  * if the service is not available.
  409  *
  410  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  411  * called before any other functions in this API.  Normally, ConnectService is automatically called
  412  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  413  *
  414  * This function is created automatically.
  415  *
  416  * @return
  417  *  - LE_OK if the client connected successfully to the service.
  418  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  419  *    bound.
  420  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  421  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  422  */
  423 //--------------------------------------------------------------------------------------------------
  424 le_result_t le_dcs_TryConnectService
  425 (
  426     void
  427 );
  428 
  429 //--------------------------------------------------------------------------------------------------
  430 /**
  431  * Set handler called when server disconnection is detected.
  432  *
  433  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  434  * to continue without exiting, it should call longjmp() from inside the handler.
  435  */
  436 //--------------------------------------------------------------------------------------------------
  437 LE_FULL_API void le_dcs_SetServerDisconnectHandler
  438 (
  439     le_dcs_DisconnectHandler_t disconnectHandler,
  440     void *contextPtr
  441 );
  442 
  443 //--------------------------------------------------------------------------------------------------
  444 /**
  445  *
  446  * Disconnect the current client thread from the service providing this API.
  447  *
  448  * Normally, this function doesn't need to be called. After this function is called, there's no
  449  * longer a connection to the service, and the functions in this API can't be used. For details, see
  450  * @ref apiFilesC_client.
  451  *
  452  * This function is created automatically.
  453  */
  454 //--------------------------------------------------------------------------------------------------
  455 void le_dcs_DisconnectService
  456 (
  457     void
  458 );
  459 
  460 
  461 //--------------------------------------------------------------------------------------------------
  462 /**
  463  * Reference returned by Request function and used by Release function
  464  */
  465 //--------------------------------------------------------------------------------------------------
  466 
  467 
  468 //--------------------------------------------------------------------------------------------------
  469 /**
  470  * Reference to a data channel
  471  */
  472 //--------------------------------------------------------------------------------------------------
  473 
  474 
  475 //--------------------------------------------------------------------------------------------------
  476 /**
  477  * Technologies.
  478  */
  479 //--------------------------------------------------------------------------------------------------
  480 
  481 
  482 //--------------------------------------------------------------------------------------------------
  483 /**
  484  * Channel states.
  485  */
  486 //--------------------------------------------------------------------------------------------------
  487 
  488 
  489 //--------------------------------------------------------------------------------------------------
  490 /**
  491  * Channel events.
  492  */
  493 //--------------------------------------------------------------------------------------------------
  494 
  495 
  496 //--------------------------------------------------------------------------------------------------
  497 /**
  498  * Handler for channel state changes
  499  */
  500 //--------------------------------------------------------------------------------------------------
  501 
  502 
  503 //--------------------------------------------------------------------------------------------------
  504 /**
  505  * Reference type used by Add/Remove functions for EVENT 'le_dcs_Event'
  506  */
  507 //--------------------------------------------------------------------------------------------------
  508 
  509 
  510 //--------------------------------------------------------------------------------------------------
  511 /**
  512  * This is the structure with info about each available channel
  513  */
  514 //--------------------------------------------------------------------------------------------------
  515 
  516 
  517 //--------------------------------------------------------------------------------------------------
  518 /**
  519  * Handler for the receiving the results of a channel list query
  520  */
  521 //--------------------------------------------------------------------------------------------------
  522 
  523 
  524 //--------------------------------------------------------------------------------------------------
  525 /**
  526  * Add handler function for EVENT 'le_dcs_Event'
  527  *
  528  * This event provides information on channel events
  529  */
  530 //--------------------------------------------------------------------------------------------------
  531 le_dcs_EventHandlerRef_t le_dcs_AddEventHandler
  532 (
  533     le_dcs_ChannelRef_t channelRef,
  534         ///< [IN] The channel for which the event is
  535     le_dcs_EventHandlerFunc_t handlerPtr,
  536         ///< [IN]
  537     void* contextPtr
  538         ///< [IN]
  539 );
  540 
  541 //--------------------------------------------------------------------------------------------------
  542 /**
  543  * Remove handler function for EVENT 'le_dcs_Event'
  544  */
  545 //--------------------------------------------------------------------------------------------------
  546 void le_dcs_RemoveEventHandler
  547 (
  548     le_dcs_EventHandlerRef_t handlerRef
  549         ///< [IN]
  550 );
  551 
  552 //--------------------------------------------------------------------------------------------------
  553 /**
  554  * Query for a channel's technology type
  555  *
  556  * @return
  557  *      - The given channel's technology type as an enumberator from @ref le_dcs_Technology_t
  558  */
  559 //--------------------------------------------------------------------------------------------------
  560 le_dcs_Technology_t le_dcs_GetTechnology
  561 (
  562     le_dcs_ChannelRef_t channelRef
  563         ///< [IN] channel which technology type is to be queried
  564 );
  565 
  566 //--------------------------------------------------------------------------------------------------
  567 /**
  568  * Query for a channel's state
  569  *
  570  * @return
  571  *      - The given channel's state in the 2nd argument and associated network interface
  572  *        in 'name'
  573  */
  574 //--------------------------------------------------------------------------------------------------
  575 le_result_t le_dcs_GetState
  576 (
  577     le_dcs_ChannelRef_t channelRef,
  578         ///< [IN] channel which status is to be queried
  579     le_dcs_State_t* statePtr,
  580         ///< [OUT] channel state returned as output
  581     char* interfaceName,
  582         ///< [OUT] channel's network interface name
  583     size_t interfaceNameSize
  584         ///< [IN]
  585 );
  586 
  587 //--------------------------------------------------------------------------------------------------
  588 /**
  589  * Request by an app to start a data channel
  590  *
  591  * @return
  592  *      - Object reference to the request (to be used later for releasing the channel)
  593  *      - NULL if it has failed to process the request
  594  */
  595 //--------------------------------------------------------------------------------------------------
  596 le_dcs_ReqObjRef_t le_dcs_Start
  597 (
  598     le_dcs_ChannelRef_t channelRef
  599         ///< [IN] channel requested to be started
  600 );
  601 
  602 //--------------------------------------------------------------------------------------------------
  603 /**
  604  * Stop for an app its previously started data channel
  605  */
  606 //--------------------------------------------------------------------------------------------------
  607 le_result_t le_dcs_Stop
  608 (
  609     le_dcs_ReqObjRef_t reqRef
  610         ///< [IN] the start request's reference earlier returned
  611 );
  612 
  613 //--------------------------------------------------------------------------------------------------
  614 /**
  615  * Get the object reference of the channel given by the name and its technology type in the first
  616  * and second arguments as input
  617  *
  618  * @return
  619  *     - The retrieved channel reference is returned in the function's return value upon success.
  620  *     - Upon failure, 0 is returned back
  621  */
  622 //--------------------------------------------------------------------------------------------------
  623 le_dcs_ChannelRef_t le_dcs_GetReference
  624 (
  625     const char* LE_NONNULL name,
  626         ///< [IN] name of channel which reference is to be retrieved
  627     le_dcs_Technology_t technology
  628         ///< [IN] technology of the channel given by its name above
  629 );
  630 
  631 //--------------------------------------------------------------------------------------------------
  632 /**
  633  * Trigger a query for the list of all available data channels that will be returned asynchronously
  634  * via the ChannelQueryHandler callback notification
  635  */
  636 //--------------------------------------------------------------------------------------------------
  637 void le_dcs_GetChannels
  638 (
  639     le_dcs_GetChannelsHandlerFunc_t handlerPtr,
  640         ///< [IN] requester's handler for receiving results
  641     void* contextPtr
  642         ///< [IN]
  643 );
  644 
  645 #endif // LE_DCS_INTERFACE_H_INCLUDE_GUARD
le_dcs_AddEventHandler
le_dcs_EventHandlerRef_t le_dcs_AddEventHandler(le_dcs_ChannelRef_t channelRef, le_dcs_EventHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t
le_result_t
Definition: le_basics.h:35
le_dcs_TryConnectService
le_result_t le_dcs_TryConnectService(void)
le_dcs_GetTechnology
le_dcs_Technology_t le_dcs_GetTechnology(le_dcs_ChannelRef_t channelRef)
le_dcs_Start
le_dcs_ReqObjRef_t le_dcs_Start(le_dcs_ChannelRef_t channelRef)
le_dcs_ConnectService
void le_dcs_ConnectService(void)
le_dcs_SetServerDisconnectHandler
LE_FULL_API void le_dcs_SetServerDisconnectHandler(le_dcs_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_dcs_GetReference
le_dcs_ChannelRef_t le_dcs_GetReference(const char *LE_NONNULL name, le_dcs_Technology_t technology)
le_dcs_DisconnectService
void le_dcs_DisconnectService(void)
le_dcs_Stop
le_result_t le_dcs_Stop(le_dcs_ReqObjRef_t reqRef)
LE_FULL_API
#define LE_FULL_API
Definition: le_basics.h:288
le_dcs_RemoveEventHandler
void le_dcs_RemoveEventHandler(le_dcs_EventHandlerRef_t handlerRef)
le_dcs_DisconnectHandler_t
void(* le_dcs_DisconnectHandler_t)(void *)
Definition: le_dcs_interface.h:384
le_dcs_GetChannels
void le_dcs_GetChannels(le_dcs_GetChannelsHandlerFunc_t handlerPtr, void *contextPtr)
le_dcs_GetState
le_result_t le_dcs_GetState(le_dcs_ChannelRef_t channelRef, le_dcs_State_t *statePtr, char *interfaceName, size_t interfaceNameSize)