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  * Sets what country code to use.
   62  * - le_wifiAp_SetCountryCode()
   63  *
   64  * Sets which IEEE standard to use.
   65  * - le_wifiAp_SetIeeeStandard()
   66  *
   67  * Gets which IEEE standard was set.
   68  * - le_wifiAp_GetIeeeStandard()
   69  *
   70  * @snippet "apps/sample/wifiApTest/wifiApTestComponent/wifiApTest.c" SetCred
   71  *
   72  * @section le_wifiAp_Start Starting the WiFi Access Point
   73  *
   74  * The WiFi Access Point is started with the function le_wifiAp_Start(). Unless values have been changed, default values will be used:
   75  * - le_wifiAp_Start():
   76  *
   77  * To subscribe to wifi events le_wifiAp_AddNewEventHandler() is to be called.
   78  * - le_wifiAp_AddNewEventHandler()
   79  *
   80  *
   81  * @snippet "apps/sample/wifiApTest/wifiApTestComponent/wifiApTest.c"  Subscribe
   82  *
   83  * <HR>
   84  *
   85  * Copyright (C) Sierra Wireless Inc.
   86  */
   87 /**
   88  * @file le_wifiAp_interface.h
   89  *
   90  * Legato @ref c_le_wifiAp include file.
   91  *
   92  * Copyright (C) Sierra Wireless Inc.
   93  */
   94 
   95 #ifndef LE_WIFIAP_INTERFACE_H_INCLUDE_GUARD
   96 #define LE_WIFIAP_INTERFACE_H_INCLUDE_GUARD
   97 
   98 
   99 #include "legato.h"
  100 
  101 // Interface specific includes
  102 #include "le_wifiDefs_interface.h"
  103 
  104 // Internal includes for this interface
  105 #include "le_wifiAp_common.h"
  106 //--------------------------------------------------------------------------------------------------
  107 /**
  108  * Type for handler called when a server disconnects.
  109  */
  110 //--------------------------------------------------------------------------------------------------
  111 typedef void (*le_wifiAp_DisconnectHandler_t)(void *);
  112 
  113 //--------------------------------------------------------------------------------------------------
  114 /**
  115  *
  116  * Connect the current client thread to the service providing this API. Block until the service is
  117  * 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 //--------------------------------------------------------------------------------------------------
  126 void le_wifiAp_ConnectService
  127 (
  128     void
  129 );
  130 
  131 //--------------------------------------------------------------------------------------------------
  132 /**
  133  *
  134  * Try to connect the current client thread to the service providing this API. Return with an error
  135  * if the service is not available.
  136  *
  137  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  138  * called before any other functions in this API.  Normally, ConnectService is automatically called
  139  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  140  *
  141  * This function is created automatically.
  142  *
  143  * @return
  144  *  - LE_OK if the client connected successfully to the service.
  145  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  146  *    bound.
  147  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  148  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  149  */
  150 //--------------------------------------------------------------------------------------------------
  151 le_result_t le_wifiAp_TryConnectService
  152 (
  153     void
  154 );
  155 
  156 //--------------------------------------------------------------------------------------------------
  157 /**
  158  * Set handler called when server disconnection is detected.
  159  *
  160  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  161  * to continue without exiting, it should call longjmp() from inside the handler.
  162  */
  163 //--------------------------------------------------------------------------------------------------
  164 LE_FULL_API void le_wifiAp_SetServerDisconnectHandler
  165 (
  166     le_wifiAp_DisconnectHandler_t disconnectHandler,
  167     void *contextPtr
  168 );
  169 
  170 //--------------------------------------------------------------------------------------------------
  171 /**
  172  *
  173  * Disconnect the current client thread from the service providing this API.
  174  *
  175  * Normally, this function doesn't need to be called. After this function is called, there's no
  176  * longer a connection to the service, and the functions in this API can't be used. For details, see
  177  * @ref apiFilesC_client.
  178  *
  179  * This function is created automatically.
  180  */
  181 //--------------------------------------------------------------------------------------------------
  182 void le_wifiAp_DisconnectService
  183 (
  184     void
  185 );
  186 
  187 
  188 //--------------------------------------------------------------------------------------------------
  189 /**
  190  * WiFi Access Point Events.
  191  */
  192 //--------------------------------------------------------------------------------------------------
  193 
  194 
  195 //--------------------------------------------------------------------------------------------------
  196 /**
  197  * WiFi Access Point Security levels.
  198  */
  199 //--------------------------------------------------------------------------------------------------
  200 
  201 
  202 //--------------------------------------------------------------------------------------------------
  203 /**
  204  * IEEE 802.11 standards Bit Mask
  205  */
  206 //--------------------------------------------------------------------------------------------------
  207 
  208 
  209 //--------------------------------------------------------------------------------------------------
  210 /**
  211  * Handler for WiFi Access Point changes
  212  */
  213 //--------------------------------------------------------------------------------------------------
  214 
  215 
  216 //--------------------------------------------------------------------------------------------------
  217 /**
  218  * Reference type used by Add/Remove functions for EVENT 'le_wifiAp_NewEvent'
  219  */
  220 //--------------------------------------------------------------------------------------------------
  221 
  222 
  223 //--------------------------------------------------------------------------------------------------
  224 /**
  225  * Add handler function for EVENT 'le_wifiAp_NewEvent'
  226  *
  227  * These events provide information on WiFi Access Point
  228  *
  229  */
  230 //--------------------------------------------------------------------------------------------------
  231 le_wifiAp_NewEventHandlerRef_t le_wifiAp_AddNewEventHandler
  232 (
  233     le_wifiAp_EventHandlerFunc_t handlerPtr,
  234         ///< [IN]
  235     void* contextPtr
  236         ///< [IN]
  237 );
  238 
  239 //--------------------------------------------------------------------------------------------------
  240 /**
  241  * Remove handler function for EVENT 'le_wifiAp_NewEvent'
  242  */
  243 //--------------------------------------------------------------------------------------------------
  244 void le_wifiAp_RemoveNewEventHandler
  245 (
  246     le_wifiAp_NewEventHandlerRef_t handlerRef
  247         ///< [IN]
  248 );
  249 
  250 //--------------------------------------------------------------------------------------------------
  251 /**
  252  * This function starts the WIFI Access Point.
  253  * @note that all settings, if to be used, such as security, username, password must set prior to
  254  * starting the Access Point.
  255  *
  256  * @return
  257  *      - LE_FAULT if the function failed.
  258  *      - LE_OK if the function succeeded.
  259  *
  260  */
  261 //--------------------------------------------------------------------------------------------------
  262 le_result_t le_wifiAp_Start
  263 (
  264     void
  265 );
  266 
  267 //--------------------------------------------------------------------------------------------------
  268 /**
  269  * This function stops the WIFI Access Point.
  270  *
  271  * @return
  272  *      - LE_FAULT if the function failed.
  273  *      - LE_OK if the function succeeded.
  274  *
  275  */
  276 //--------------------------------------------------------------------------------------------------
  277 le_result_t le_wifiAp_Stop
  278 (
  279     void
  280 );
  281 
  282 //--------------------------------------------------------------------------------------------------
  283 /**
  284  * Set the Service set identification (SSID) of the AccessPoint
  285  * Default value is "LEGATO Access Point"
  286  * @note that the SSID does not have to be human readable ASCII values, but often has.
  287  *
  288  * @return
  289  *      - LE_BAD_PARAMETER if some parameter is invalid.
  290  *      - LE_OK if the function succeeded.
  291  */
  292 //--------------------------------------------------------------------------------------------------
  293 le_result_t le_wifiAp_SetSsid
  294 (
  295     const uint8_t* ssidPtr,
  296         ///< [IN] The SSID to set as a octet array.
  297     size_t ssidSize
  298         ///< [IN]
  299 );
  300 
  301 //--------------------------------------------------------------------------------------------------
  302 /**
  303  * Set the Security protocol to use.
  304  * Default value is SECURITY_WPA2.
  305  * @note that the SSID does not have to be human readable ASCII values, but often has.
  306  *
  307  * @return
  308  *      - LE_BAD_PARAMETER if some parameter is invalid.
  309  *      - LE_OK if the function succeeded.
  310  */
  311 //--------------------------------------------------------------------------------------------------
  312 le_result_t le_wifiAp_SetSecurityProtocol
  313 (
  314     le_wifiAp_SecurityProtocol_t securityProtocol
  315         ///< [IN] The security protocol to use.
  316 );
  317 
  318 //--------------------------------------------------------------------------------------------------
  319 /**
  320  * Set the passphrase used to generate the PSK.
  321  *
  322  * @note If the PSK is to be set directly, please use le_wifiAp_SetPreSharedKey()
  323  *
  324  * @return
  325  *      - LE_BAD_PARAMETER if parameter is invalid.
  326  *      - LE_OK if the function succeeded.
  327  *
  328  */
  329 //--------------------------------------------------------------------------------------------------
  330 le_result_t le_wifiAp_SetPassPhrase
  331 (
  332     const char* LE_NONNULL passPhrase
  333         ///< [IN] pass-phrase for PSK
  334 );
  335 
  336 //--------------------------------------------------------------------------------------------------
  337 /**
  338  * Set the Pre Shared Key, PSK.
  339  * There is no default value, since le_wifiAp_SetPassPhrase is used as default.
  340  * @note the difference between le_wifiAp_SetPassPhrase() and this function
  341  *
  342  * @return
  343  *      - LE_BAD_PARAMETER if parameter is invalid.
  344  *      - LE_OK if the function succeeded.
  345  *
  346  */
  347 //--------------------------------------------------------------------------------------------------
  348 le_result_t le_wifiAp_SetPreSharedKey
  349 (
  350     const char* LE_NONNULL preSharedKey
  351         ///< [IN] PSK. Note the difference between PSK and Pass Phrase.
  352 );
  353 
  354 //--------------------------------------------------------------------------------------------------
  355 /**
  356  * Set if the Access Point should announce its presence.
  357  * Default value is TRUE.
  358  * If the value is set to FALSE, the Access Point will be hidden.
  359  *
  360  * @return LE_OK if the function succeeded.
  361  *
  362  */
  363 //--------------------------------------------------------------------------------------------------
  364 le_result_t le_wifiAp_SetDiscoverable
  365 (
  366     bool discoverable
  367         ///< [IN] If TRUE the Access Point shows up on scans, else it is hidden.
  368 );
  369 
  370 //--------------------------------------------------------------------------------------------------
  371 /**
  372  * Set which IEEE standard to use.
  373  * Default hardware mode is IEEE 802.11g.
  374  *
  375  * @return
  376  *      - LE_BAD_PARAMETER if invalid IEEE standard is set.
  377  *      - LE_OK if the function succeeded.
  378  *
  379  */
  380 //--------------------------------------------------------------------------------------------------
  381 le_result_t le_wifiAp_SetIeeeStandard
  382 (
  383     le_wifiAp_IeeeStdBitMask_t stdMask
  384         ///< [IN] Bit mask for the IEEE standard.
  385 );
  386 
  387 //--------------------------------------------------------------------------------------------------
  388 /**
  389  * Get which IEEE standard was set.
  390  * Default hardware mode is IEEE 802.11g.
  391  *
  392  * @return
  393  *      - LE_FAULT if the function failed.
  394  *      - LE_OK if the function succeeded.
  395  *
  396  */
  397 //--------------------------------------------------------------------------------------------------
  398 le_result_t le_wifiAp_GetIeeeStandard
  399 (
  400     le_wifiAp_IeeeStdBitMask_t* stdMaskPtrPtr
  401         ///< [OUT] Bit mask for the IEEE standard.
  402 );
  403 
  404 //--------------------------------------------------------------------------------------------------
  405 /**
  406  * Set which WiFi Channel to use.
  407  * Default value is 7.
  408  * Some legal restrictions might apply for your region.
  409  * The channel number must be between 1 and 14 for IEEE 802.11b/g.
  410  * The channel number must be between 7 and 196 for IEEE 802.11a.
  411  * The channel number must be between 1 and 6 for IEEE 802.11ad.
  412  * @return
  413  *      - LE_OUT_OF_RANGE if requested channel number is out of range.
  414  *      - LE_OK if the function succeeded.
  415  *
  416  */
  417 //--------------------------------------------------------------------------------------------------
  418 le_result_t le_wifiAp_SetChannel
  419 (
  420     uint16_t channelNumber
  421         ///< [IN] the channel number.
  422 );
  423 
  424 //--------------------------------------------------------------------------------------------------
  425 /**
  426  * Set what country code to use for regulatory domain.
  427  * ISO/IEC 3166-1 Alpha-2 code is used.
  428  * Default country code is US.
  429  * @return
  430  *      - LE_FAULT if the function failed.
  431  *      - LE_OK if the function succeeded.
  432  *
  433  */
  434 //--------------------------------------------------------------------------------------------------
  435 le_result_t le_wifiAp_SetCountryCode
  436 (
  437     const char* LE_NONNULL countryCode
  438         ///< [IN] the country code.
  439 );
  440 
  441 //--------------------------------------------------------------------------------------------------
  442 /**
  443  * Set number of maximally allowed clients to connect to the Access Point at the same time.
  444  *
  445  * @return
  446  *      - LE_OUT_OF_RANGE if requested number of users exceeds the capabilities of the Access Point.
  447  *      - LE_OK if the function succeeded.
  448  *
  449  */
  450 //--------------------------------------------------------------------------------------------------
  451 le_result_t le_wifiAp_SetMaxNumberOfClients
  452 (
  453     int8_t maxNumberOfClient
  454         ///< [IN] the maximum number of clients
  455 );
  456 
  457 //--------------------------------------------------------------------------------------------------
  458 /**
  459  * Defines the IP adresses range for the host AP.
  460  *
  461  * @return
  462  *      - LE_BAD_PARAMETER if at least one of the given IP addresses is invalid.
  463  *      - LE_FAULT if a system call failed.
  464  *      - LE_OK if the function succeeded.
  465  *
  466  */
  467 //--------------------------------------------------------------------------------------------------
  468 le_result_t le_wifiAp_SetIpRange
  469 (
  470     const char* LE_NONNULL ipAp,
  471         ///< [IN] the IP address of the Access Point.
  472     const char* LE_NONNULL ipStart,
  473         ///< [IN] the start IP address of the Access Point.
  474     const char* LE_NONNULL ipStop
  475         ///< [IN] the stop IP address of the Access Point.
  476 );
  477 
  478 #endif // LE_WIFIAP_INTERFACE_H_INCLUDE_GUARD
le_wifiAp_SetIpRange
le_result_t le_wifiAp_SetIpRange(const char *LE_NONNULL ipAp, const char *LE_NONNULL ipStart, const char *LE_NONNULL ipStop)
le_wifiAp_SetSsid
le_result_t le_wifiAp_SetSsid(const uint8_t *ssidPtr, size_t ssidSize)
le_result_t
le_result_t
Definition: le_basics.h:35
le_wifiAp_SetDiscoverable
le_result_t le_wifiAp_SetDiscoverable(bool discoverable)
le_wifiAp_SetChannel
le_result_t le_wifiAp_SetChannel(uint16_t channelNumber)
le_wifiAp_Stop
le_result_t le_wifiAp_Stop(void)
le_wifiDefs_interface.h
le_wifiAp_TryConnectService
le_result_t le_wifiAp_TryConnectService(void)
le_wifiAp_ConnectService
void le_wifiAp_ConnectService(void)
le_wifiAp_DisconnectService
void le_wifiAp_DisconnectService(void)
le_wifiAp_RemoveNewEventHandler
void le_wifiAp_RemoveNewEventHandler(le_wifiAp_NewEventHandlerRef_t handlerRef)
le_wifiAp_SetPassPhrase
le_result_t le_wifiAp_SetPassPhrase(const char *LE_NONNULL passPhrase)
le_wifiAp_GetIeeeStandard
le_result_t le_wifiAp_GetIeeeStandard(le_wifiAp_IeeeStdBitMask_t *stdMaskPtrPtr)
le_wifiAp_Start
le_result_t le_wifiAp_Start(void)
le_wifiAp_SetMaxNumberOfClients
le_result_t le_wifiAp_SetMaxNumberOfClients(int8_t maxNumberOfClient)
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_wifiAp_SetServerDisconnectHandler
LE_FULL_API void le_wifiAp_SetServerDisconnectHandler(le_wifiAp_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_wifiAp_SetCountryCode
le_result_t le_wifiAp_SetCountryCode(const char *LE_NONNULL countryCode)
le_wifiAp_DisconnectHandler_t
void(* le_wifiAp_DisconnectHandler_t)(void *)
Definition: le_wifiAp_interface.h:111
le_wifiAp_SetPreSharedKey
le_result_t le_wifiAp_SetPreSharedKey(const char *LE_NONNULL preSharedKey)
le_wifiAp_SetIeeeStandard
le_result_t le_wifiAp_SetIeeeStandard(le_wifiAp_IeeeStdBitMask_t stdMask)
LE_FULL_API
#define LE_FULL_API
Definition: le_basics.h:288