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  * @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 /** @addtogroup le_dcs le_dcs API Reference
  403  * @{
  404  * @file le_dcs_common.h
  405  * @file le_dcs_interface.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 //--------------------------------------------------------------------------------------------------
  426 void le_dcs_ConnectService
  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 //--------------------------------------------------------------------------------------------------
  451 le_result_t le_dcs_TryConnectService
  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 //--------------------------------------------------------------------------------------------------
  464 LE_FULL_API void le_dcs_SetServerDisconnectHandler
  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 //--------------------------------------------------------------------------------------------------
  482 void le_dcs_DisconnectService
  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 //--------------------------------------------------------------------------------------------------
  586 void le_dcs_RemoveEventHandler
  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 administrative state
  609  *
  610  * @return
  611  *      - The given channel's state in the 2nd argument and associated network interface
  612  *        in 'name'
  613  */
  614 //--------------------------------------------------------------------------------------------------
  615 le_result_t le_dcs_GetState
  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  * @return
  632  *      - Object reference to the request (to be used later for releasing the channel)
  633  *      - NULL if it has failed to process the request
  634  */
  635 //--------------------------------------------------------------------------------------------------
  636 le_dcs_ReqObjRef_t le_dcs_Start
  637 (
  638     le_dcs_ChannelRef_t channelRef
  639         ///< [IN] channel requested to be started
  640 );
  641 
  642 //--------------------------------------------------------------------------------------------------
  643 /**
  644  * Stop for an app its previously started data channel
  645  */
  646 //--------------------------------------------------------------------------------------------------
  647 le_result_t le_dcs_Stop
  648 (
  649     le_dcs_ReqObjRef_t reqRef
  650         ///< [IN] the start request's reference earlier returned
  651 );
  652 
  653 //--------------------------------------------------------------------------------------------------
  654 /**
  655  * Get the object reference of the channel given by the name and its technology type in the first
  656  * and second arguments as input
  657  *
  658  * @return
  659  *     - The retrieved channel reference is returned in the function's return value upon success.
  660  *     - Upon failure, 0 is returned back
  661  */
  662 //--------------------------------------------------------------------------------------------------
  663 le_dcs_ChannelRef_t le_dcs_GetReference
  664 (
  665     const char* LE_NONNULL name,
  666         ///< [IN] name of channel which reference is to be retrieved
  667     le_dcs_Technology_t technology
  668         ///< [IN] technology of the channel given by its name above
  669 );
  670 
  671 //--------------------------------------------------------------------------------------------------
  672 /**
  673  * Trigger a query for the list of all available data channels that will be returned asynchronously
  674  * via the ChannelQueryHandler callback notification
  675  */
  676 //--------------------------------------------------------------------------------------------------
  677 void le_dcs_GetChannels
  678 (
  679     le_dcs_GetChannelsHandlerFunc_t handlerPtr,
  680         ///< [IN] requester's handler for receiving results
  681     void* contextPtr
  682         ///< [IN]
  683 );
  684 
  685 /** @} **/
  686 
  687 #endif // LE_DCS_INTERFACE_H_INCLUDE_GUARD
le_dcs_RemoveEventHandler
void le_dcs_RemoveEventHandler(le_dcs_EventHandlerRef_t handlerRef)
le_dcs_GetChannels
void le_dcs_GetChannels(le_dcs_GetChannelsHandlerFunc_t handlerPtr, void *contextPtr)
le_dcs_common.h
le_dcs_EventHandlerFunc_t
void(* le_dcs_EventHandlerFunc_t)(le_dcs_ChannelRef_t channelRef, le_dcs_Event_t event, int32_t code, void *contextPtr)
Definition: le_dcs_common.h:177
le_dcs_TryConnectService
le_result_t le_dcs_TryConnectService(void)
le_result_t
le_result_t
Definition: le_basics.h:46
le_dcs_Stop
le_result_t le_dcs_Stop(le_dcs_ReqObjRef_t reqRef)
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_ReqObjRef_t
struct le_dcs_ReqObj * le_dcs_ReqObjRef_t
Definition: le_dcs_common.h:71
le_dcs_EventHandlerRef_t
struct le_dcs_EventHandler * le_dcs_EventHandlerRef_t
Definition: le_dcs_common.h:153
le_dcs_GetChannelsHandlerFunc_t
void(* le_dcs_GetChannelsHandlerFunc_t)(le_result_t result, const le_dcs_ChannelInfo_t *channelListPtr, size_t channelListSize, void *contextPtr)
Definition: le_dcs_common.h:194
le_dcs_DisconnectService
void le_dcs_DisconnectService(void)
le_dcs_Technology_t
le_dcs_Technology_t
Definition: le_dcs_common.h:87
le_dcs_GetState
le_result_t le_dcs_GetState(le_dcs_ChannelRef_t channelRef, le_dcs_State_t *statePtr, char *interfaceName, size_t interfaceNameSize)
le_dcs_DisconnectHandler_t
void(* le_dcs_DisconnectHandler_t)(void *)
Definition: le_dcs_interface.h:411
le_dcs_ChannelRef_t
struct le_dcs_Channel * le_dcs_ChannelRef_t
Definition: le_dcs_common.h:79
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_dcs_State_t
le_dcs_State_t
Definition: le_dcs_common.h:108
legato.h
le_dcs_GetReference
le_dcs_ChannelRef_t le_dcs_GetReference(const char *LE_NONNULL name, le_dcs_Technology_t technology)
le_dcs_GetTechnology
le_dcs_Technology_t le_dcs_GetTechnology(le_dcs_ChannelRef_t channelRef)
le_dcs_SetServerDisconnectHandler
LE_FULL_API void le_dcs_SetServerDisconnectHandler(le_dcs_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_dcs_AddEventHandler
le_dcs_EventHandlerRef_t le_dcs_AddEventHandler(le_dcs_ChannelRef_t channelRef, le_dcs_EventHandlerFunc_t handlerPtr, void *contextPtr)