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