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