le_wifiAp_interface.h

    1 /*
    2  * ====================== WARNING ======================
    3  *
    4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    5  * DO NOT MODIFY IN ANY WAY.
    6  *
    7  * ====================== WARNING ======================
    8  */
    9 
   10 /**
   11  * @page c_le_wifi_ap WiFi Access Point Service
   12  *
   13  * @ref le_wifiAp_interface.h "API Reference"
   14  *
   15  * <HR>
   16  *
   17  * This WiFi Service API provides Wifi Access Point setup.
   18  * Please note that if there is only one wifi hardware the WiFi Access Point
   19  * cannot be used at the same time as the WiFi Client service.
   20  *
   21  * @section le_wifi_binding IPC interfaces binding
   22  *
   23  *
   24  * Here's a code sample binding to WiFi service:
   25  * @verbatim
   26    bindings:
   27    {
   28       clientExe.clientComponent.le_wifiAp -> wifiService.le_wifiAp
   29    }
   30    @endverbatim
   31  *
   32  *
   33  *
   34  * @section le_wifiAp_connect_to_ap Setting parameters for the Access Point
   35  *
   36  * Note that these parameters must be set before the access point is started.
   37  * See each function for its default value.
   38  *
   39  * To set the SSID for the Access Point use the following function:
   40  * - le_wifiAp_SetSsid()
   41  *
   42  * To set the pass phrase prior for the Access Point use the function:
   43  * Also see le_wifiAp_SetPreSharedKey().
   44  * - le_wifiAp_SetPassPhrase()
   45  *
   46  * Instead of setting the pass phrase, the Pre Shared Key (PSK), can be set explicitly.
   47  * To set the Pre Shared Key prior for the Access Point start use the function:
   48  * - le_wifiAp_SetPreSharedKey()
   49  *
   50  * Sets the security protocol to use.
   51  * - le_wifiAp_SetSecurityProtocol()
   52  *
   53  * Sets is the Access Point should show up in network scans or not.
   54  * - le_wifiAp_SetDiscoverable()
   55  *
   56  * Sets which channel to use.
   57  * - le_wifiAp_SetChannel()
   58  *
   59  *
   60  * @snippet "apps/sample/wifiApTest/wifiApTestComponent/wifiApTest.c" SetCred
   61  *
   62  * @section le_wifiAp_Start Starting the WiFi Access Point
   63  *
   64  * The WiFi Access Point is started with the function le_wifiAp_Start(). Unless values have been changed, default values will be used:
   65  * - le_wifiAp_Start():
   66  *
   67  * To subscribe to wifi events le_wifiAp_AddEventHandler() is to be called.
   68  * - le_wifiAp_AddEventHandler()
   69  *
   70  *
   71  * @snippet "apps/sample/wifiApTest/wifiApTestComponent/wifiApTest.c"  Subscribe
   72  *
   73  * <HR>
   74  *
   75  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   76  */
   77 /**
   78  * @file le_wifiAp_interface.h
   79  *
   80  * Legato @ref c_le_wifiAp include file.
   81  *
   82  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   83  */
   84 
   85 #ifndef LE_WIFIAP_INTERFACE_H_INCLUDE_GUARD
   86 #define LE_WIFIAP_INTERFACE_H_INCLUDE_GUARD
   87 
   88 
   89 #include "legato.h"
   90 
   91 // Interface specific includes
   92 #include "le_wifiDefs_interface.h"
   93 
   94 
   95 //--------------------------------------------------------------------------------------------------
   96 /**
   97  *
   98  * Connect the current client thread to the service providing this API. Block until the service is
   99  * available.
  100  *
  101  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  102  * called before any other functions in this API.  Normally, ConnectService is automatically called
  103  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  104  *
  105  * This function is created automatically.
  106  */
  107 //--------------------------------------------------------------------------------------------------
  108 void le_wifiAp_ConnectService
  109 (
  110     void
  111 );
  112 
  113 //--------------------------------------------------------------------------------------------------
  114 /**
  115  *
  116  * Try to connect the current client thread to the service providing this API. Return with an error
  117  * if the service is not available.
  118  *
  119  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  120  * called before any other functions in this API.  Normally, ConnectService is automatically called
  121  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  122  *
  123  * This function is created automatically.
  124  *
  125  * @return
  126  *  - LE_OK if the client connected successfully to the service.
  127  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  128  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  129  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  130  */
  131 //--------------------------------------------------------------------------------------------------
  132 le_result_t le_wifiAp_TryConnectService
  133 (
  134     void
  135 );
  136 
  137 //--------------------------------------------------------------------------------------------------
  138 /**
  139  *
  140  * Disconnect the current client thread from the service providing this API.
  141  *
  142  * Normally, this function doesn't need to be called. After this function is called, there's no
  143  * longer a connection to the service, and the functions in this API can't be used. For details, see
  144  * @ref apiFilesC_client.
  145  *
  146  * This function is created automatically.
  147  */
  148 //--------------------------------------------------------------------------------------------------
  149 void le_wifiAp_DisconnectService
  150 (
  151     void
  152 );
  153 
  154 
  155 //--------------------------------------------------------------------------------------------------
  156 /**
  157  * WiFi Access Point Events.
  158  */
  159 //--------------------------------------------------------------------------------------------------
  160 typedef enum
  161 {
  162     LE_WIFIAP_EVENT_CLIENT_CONNECTED = 0,
  163         ///< Client connected to WiFi Access Point.
  164 
  165     LE_WIFIAP_EVENT_CLIENT_DISCONNECTED = 1
  166         ///< Client disconnected from WiFi Access Point.
  167 }
  168 le_wifiAp_Event_t;
  169 
  170 
  171 //--------------------------------------------------------------------------------------------------
  172 /**
  173  * WiFi Access Point Security levels.
  174  */
  175 //--------------------------------------------------------------------------------------------------
  176 typedef enum
  177 {
  178     LE_WIFIAP_SECURITY_NONE = 0,
  179         ///< WiFi Access Point is open and has no password.
  180 
  181     LE_WIFIAP_SECURITY_WPA2 = 1
  182         ///< WiFi Access Point has WPA2 activated.
  183 }
  184 le_wifiAp_SecurityProtocol_t;
  185 
  186 
  187 //--------------------------------------------------------------------------------------------------
  188 /**
  189  * Reference type used by Add/Remove functions for EVENT 'le_wifiAp_NewEvent'
  190  */
  191 //--------------------------------------------------------------------------------------------------
  192 typedef struct le_wifiAp_NewEventHandler* le_wifiAp_NewEventHandlerRef_t;
  193 
  194 
  195 //--------------------------------------------------------------------------------------------------
  196 /**
  197  * Handler for WiFi Access Point changes
  198  *
  199  * @param event
  200  *        Handles the wifi events
  201  * @param contextPtr
  202  */
  203 //--------------------------------------------------------------------------------------------------
  204 typedef void (*le_wifiAp_EventHandlerFunc_t)
  205 (
  206     le_wifiAp_Event_t event,
  207     void* contextPtr
  208 );
  209 
  210 //--------------------------------------------------------------------------------------------------
  211 /**
  212  * Add handler function for EVENT 'le_wifiAp_NewEvent'
  213  *
  214  * These events provide information on WiFi Access Point
  215  */
  216 //--------------------------------------------------------------------------------------------------
  217 le_wifiAp_NewEventHandlerRef_t le_wifiAp_AddNewEventHandler
  218 (
  219     le_wifiAp_EventHandlerFunc_t handlerPtr,
  220         ///< [IN]
  221 
  222     void* contextPtr
  223         ///< [IN]
  224 );
  225 
  226 //--------------------------------------------------------------------------------------------------
  227 /**
  228  * Remove handler function for EVENT 'le_wifiAp_NewEvent'
  229  */
  230 //--------------------------------------------------------------------------------------------------
  231 void le_wifiAp_RemoveNewEventHandler
  232 (
  233     le_wifiAp_NewEventHandlerRef_t addHandlerRef
  234         ///< [IN]
  235 );
  236 
  237 //--------------------------------------------------------------------------------------------------
  238 /**
  239  * This function starts the WIFI Access Point.
  240  * @note that all settings, if to be used, such as security, username, password must set prior to
  241  * starting the Access Point.
  242  *
  243  * @return
  244  *      - LE_FAULT if the function failed.
  245  *      - LE_OK if the function succeeded.
  246  *
  247  */
  248 //--------------------------------------------------------------------------------------------------
  249 le_result_t le_wifiAp_Start
  250 (
  251     void
  252 );
  253 
  254 //--------------------------------------------------------------------------------------------------
  255 /**
  256  * This function stops the WIFI Access Point.
  257  *
  258  * @return
  259  *      - LE_FAULT if the function failed.
  260  *      - LE_OK if the function succeeded.
  261  *
  262  */
  263 //--------------------------------------------------------------------------------------------------
  264 le_result_t le_wifiAp_Stop
  265 (
  266     void
  267 );
  268 
  269 //--------------------------------------------------------------------------------------------------
  270 /**
  271  * Set the Service set identification (SSID) of the AccessPoint
  272  * Default value is "LEGATO Access Point"
  273  * @note that the SSID does not have to be human readable ASCII values, but often has.
  274  *
  275  * @return
  276  *      - LE_BAD_PARAMETER if some parameter is invalid.
  277  *      - LE_OK if the function succeeded.
  278  */
  279 //--------------------------------------------------------------------------------------------------
  280 le_result_t le_wifiAp_SetSsid
  281 (
  282     const uint8_t* ssidPtr,
  283         ///< [IN] The SSID to set as a octet array.
  284 
  285     size_t ssidNumElements
  286         ///< [IN]
  287 );
  288 
  289 //--------------------------------------------------------------------------------------------------
  290 /**
  291  * Set the Security protocol to use.
  292  * Default value is SECURITY_WPA2.
  293  * @note that the SSID does not have to be human readable ASCII values, but often has.
  294  *
  295  * @return
  296  *      - LE_BAD_PARAMETER if some parameter is invalid.
  297  *      - LE_OK if the function succeeded.
  298  */
  299 //--------------------------------------------------------------------------------------------------
  300 le_result_t le_wifiAp_SetSecurityProtocol
  301 (
  302     le_wifiAp_SecurityProtocol_t securityProtocol
  303         ///< [IN] The security protocol to use.
  304 );
  305 
  306 //--------------------------------------------------------------------------------------------------
  307 /**
  308  * Set the passphrase used to generate the PSK.
  309  * Default value is "ChangeThisPassword".
  310  *
  311  * @note If the PSK is to be set directly, please use le_wifiAp_SetPreSharedKey()
  312  *
  313  * @return
  314  *      - LE_BAD_PARAMETER if parameter is invalid.
  315  *      - LE_OK if the function succeeded.
  316  *
  317  */
  318 //--------------------------------------------------------------------------------------------------
  319 le_result_t le_wifiAp_SetPassPhrase
  320 (
  321     const char* passPhrase
  322         ///< [IN] pass-phrase for PSK
  323 );
  324 
  325 //--------------------------------------------------------------------------------------------------
  326 /**
  327  * Set the Pre Shared Key, PSK.
  328  * There is no default value, since le_wifiAp_SetPassPhrase is used as default.
  329  * @note the difference between le_wifiAp_SetPassPhrase() and this function
  330  *
  331  * @return
  332  *      - LE_BAD_PARAMETER if parameter is invalid.
  333  *      - LE_OK if the function succeeded.
  334  *
  335  */
  336 //--------------------------------------------------------------------------------------------------
  337 le_result_t le_wifiAp_SetPreSharedKey
  338 (
  339     const char* preSharedKey
  340         ///< [IN] PSK. Note the difference between PSK and Pass Phrase.
  341 );
  342 
  343 //--------------------------------------------------------------------------------------------------
  344 /**
  345  * Set if the Access Point should announce its presence.
  346  * Default value is TRUE.
  347  * If the value is set to FALSE, the Access Point will be hidden.
  348  *
  349  * @return LE_OK if the function succeeded.
  350  *
  351  */
  352 //--------------------------------------------------------------------------------------------------
  353 le_result_t le_wifiAp_SetDiscoverable
  354 (
  355     bool discoverable
  356         ///< [IN] If TRUE the Access Point shows up on scans, else it is hidden.
  357 );
  358 
  359 //--------------------------------------------------------------------------------------------------
  360 /**
  361  * Set which WiFi Channel to use.
  362  * Default value is 1.
  363  * Some legal restrictions for values 12 - 14 might apply for your region.
  364  *
  365  * @return
  366  *      - LE_OUT_OF_RANGE if requested channel number is out of range.
  367  *      - LE_OK if the function succeeded.
  368  *
  369  */
  370 //--------------------------------------------------------------------------------------------------
  371 le_result_t le_wifiAp_SetChannel
  372 (
  373     int8_t channelNumber
  374         ///< [IN] the channel number must be between 1 and 14.
  375 );
  376 
  377 //--------------------------------------------------------------------------------------------------
  378 /**
  379  * Set number of maximally allowed clients to connect to the Access Point at the same time.
  380  *
  381  * @return
  382  *      - LE_OUT_OF_RANGE if requested number of users exceeds the capabilities of the Access Point.
  383  *      - LE_OK if the function succeeded.
  384  *
  385  */
  386 //--------------------------------------------------------------------------------------------------
  387 le_result_t le_wifiAp_SetMaxNumberOfClients
  388 (
  389     int8_t maxNumberOfClient
  390         ///< [IN] the maximum number of clients
  391 );
  392 
  393 //--------------------------------------------------------------------------------------------------
  394 /**
  395  * Defines the IP adresses range for the host AP.
  396  *
  397  * @return
  398  *      - LE_BAD_PARAMETER if at least one of the given IP addresses is invalid.
  399  *      - LE_FAULT if a system call failed.
  400  *      - LE_OK if the function succeeded.
  401  *
  402  */
  403 //--------------------------------------------------------------------------------------------------
  404 le_result_t le_wifiAp_SetIpRange
  405 (
  406     const char* ipAp,
  407         ///< [IN] the IP address of the Access Point.
  408 
  409     const char* ipStart,
  410         ///< [IN] the start IP address of the Access Point.
  411 
  412     const char* ipStop
  413         ///< [IN] the stop IP address of the Access Point.
  414 );
  415 
  416 
  417 #endif // LE_WIFIAP_INTERFACE_H_INCLUDE_GUARD
  418 
le_wifiAp_DisconnectService
void le_wifiAp_DisconnectService(void)
le_result_t
le_result_t
Definition: le_basics.h:35
le_wifiAp_Stop
le_result_t le_wifiAp_Stop(void)
le_wifiAp_NewEventHandlerRef_t
struct le_wifiAp_NewEventHandler * le_wifiAp_NewEventHandlerRef_t
Definition: le_wifiAp_interface.h:192
le_wifiAp_Event_t
le_wifiAp_Event_t
Definition: le_wifiAp_interface.h:160
le_wifiAp_AddNewEventHandler
le_wifiAp_NewEventHandlerRef_t le_wifiAp_AddNewEventHandler(le_wifiAp_EventHandlerFunc_t handlerPtr, void *contextPtr)
le_wifiAp_SetSecurityProtocol
le_result_t le_wifiAp_SetSecurityProtocol(le_wifiAp_SecurityProtocol_t securityProtocol)
le_wifiDefs_interface.h
LE_WIFIAP_EVENT_CLIENT_DISCONNECTED
Client disconnected from WiFi Access Point. 
Definition: le_wifiAp_interface.h:165
le_wifiAp_SetMaxNumberOfClients
le_result_t le_wifiAp_SetMaxNumberOfClients(int8_t maxNumberOfClient)
le_wifiAp_SetIpRange
le_result_t le_wifiAp_SetIpRange(const char *ipAp, const char *ipStart, const char *ipStop)
le_wifiAp_SetDiscoverable
le_result_t le_wifiAp_SetDiscoverable(bool discoverable)
le_wifiAp_SetChannel
le_result_t le_wifiAp_SetChannel(int8_t channelNumber)
le_wifiAp_ConnectService
void le_wifiAp_ConnectService(void)
LE_WIFIAP_EVENT_CLIENT_CONNECTED
Client connected to WiFi Access Point. 
Definition: le_wifiAp_interface.h:162
le_wifiAp_SetSsid
le_result_t le_wifiAp_SetSsid(const uint8_t *ssidPtr, size_t ssidNumElements)
legato.h
le_wifiAp_SetPassPhrase
le_result_t le_wifiAp_SetPassPhrase(const char *passPhrase)
LE_WIFIAP_SECURITY_WPA2
WiFi Access Point has WPA2 activated. 
Definition: le_wifiAp_interface.h:181
le_wifiAp_RemoveNewEventHandler
void le_wifiAp_RemoveNewEventHandler(le_wifiAp_NewEventHandlerRef_t addHandlerRef)
le_wifiAp_EventHandlerFunc_t
void(* le_wifiAp_EventHandlerFunc_t)(le_wifiAp_Event_t event, void *contextPtr)
Definition: le_wifiAp_interface.h:205
le_wifiAp_SecurityProtocol_t
le_wifiAp_SecurityProtocol_t
Definition: le_wifiAp_interface.h:176
LE_WIFIAP_SECURITY_NONE
WiFi Access Point is open and has no password. 
Definition: le_wifiAp_interface.h:178
le_wifiAp_SetPreSharedKey
le_result_t le_wifiAp_SetPreSharedKey(const char *preSharedKey)
le_wifiAp_Start
le_result_t le_wifiAp_Start(void)
le_wifiAp_TryConnectService
le_result_t le_wifiAp_TryConnectService(void)