pa_wifi_ap.h

    1 #ifndef PA_WIFI_AP_H
    2 #define PA_WIFI_AP_H
    3 // -------------------------------------------------------------------------------------------------
    4 /**
    5  *
    6  *
    7  *  Copyright (C) Sierra Wireless Inc.
    8  *
    9  */
   10 // -------------------------------------------------------------------------------------------------
   11 #include "legato.h"
   12 #include "interfaces.h"
   13 
   14 //--------------------------------------------------------------------------------------------------
   15 /**
   16  * Event handler for PA WiFi access point changes.
   17  *
   18  * Handles the PA WiFi events.
   19  */
   20 //--------------------------------------------------------------------------------------------------
   21 typedef void (*pa_wifiAp_NewEventHandlerFunc_t)
   22 (
   23     le_wifiAp_Event_t event,
   24         ///< [IN]
   25         ///< WiFi event to process
   26     void *contextPtr
   27         ///< [IN]
   28         ///< Associated WiFi event context
   29 );
   30 
   31 //--------------------------------------------------------------------------------------------------
   32 /**
   33  * Add handler function for WiFi related events.
   34  *
   35  * These events provide information on WiFi access point status.
   36  *
   37  * @return LE_OK Function succeeded.
   38  */
   39 //--------------------------------------------------------------------------------------------------
   40 LE_SHARED le_result_t pa_wifiAp_AddEventHandler
   41 (
   42     pa_wifiAp_NewEventHandlerFunc_t handlerPtr,
   43         ///< [IN]
   44         ///< Event handler function pointer
   45 
   46     void *contextPtr
   47         ///< [IN]
   48         ///< Associated event context
   49 );
   50 
   51 //--------------------------------------------------------------------------------------------------
   52 /**
   53  * This function must be called to initialize the PA WiFi Access Point.
   54  *
   55  * @return LE_OK     The function succeeded.
   56  */
   57 //--------------------------------------------------------------------------------------------------
   58 LE_SHARED le_result_t pa_wifiAp_Init
   59 (
   60     void
   61 );
   62 
   63 //--------------------------------------------------------------------------------------------------
   64 /**
   65  * This function must be called to release the platform adaptor WiFi module.
   66  *
   67  * @return LE_OK     The function succeeded.
   68  */
   69 //--------------------------------------------------------------------------------------------------
   70 LE_SHARED le_result_t pa_wifiAp_Release
   71 (
   72     void
   73 );
   74 
   75 //--------------------------------------------------------------------------------------------------
   76 /**
   77  * This function starts the WiFi access point.
   78  * Note that all settings, if to be used, such as security, username, password must set prior to
   79  * starting the access point.
   80  *
   81  * @return LE_FAULT         The function failed.
   82  * @return LE_OK            The function succeeded.
   83  *
   84  */
   85 //--------------------------------------------------------------------------------------------------
   86 le_result_t pa_wifiAp_Start
   87 (
   88     void
   89 );
   90 
   91 //--------------------------------------------------------------------------------------------------
   92 /**
   93  * This function stops the WiFi access point.
   94  *
   95  * @return LE_FAULT         The function failed.
   96  * @return LE_OK            The function succeeded.
   97  *
   98  */
   99 //--------------------------------------------------------------------------------------------------
  100 le_result_t pa_wifiAp_Stop
  101 (
  102     void
  103 );
  104 
  105 //--------------------------------------------------------------------------------------------------
  106 /**
  107  * Set the security protocol to use.
  108  *
  109  * @note WEP is not supported as it is unsecure and has been deprecated in favor of WPA/WPA2.
  110  * This limitation applies to access point mode only.
  111  *
  112  * @return LE_BAD_PARAMETER Some parameter is invalid.
  113  * @return LE_OK            Function succeeded.
  114  */
  115 //--------------------------------------------------------------------------------------------------
  116 le_result_t pa_wifiAp_SetSecurityProtocol
  117 (
  118     le_wifiAp_SecurityProtocol_t securityProtocol
  119         ///< [IN]
  120         ///< The security protocol used to communicate with the access point.
  121 );
  122 
  123 //--------------------------------------------------------------------------------------------------
  124 /**
  125  * Set the Service Set IDentification (SSID) of the access point.
  126  *
  127  * @note The SSID does not have to be human readable ASCII values, but often is.
  128  *
  129  * @return LE_BAD_PARAMETER Some parameter is invalid.
  130  * @return LE_OK            Function succeeded.
  131  */
  132 //--------------------------------------------------------------------------------------------------
  133 le_result_t pa_wifiAp_SetSsid
  134 (
  135     const uint8_t *ssidPtr,
  136         ///< [IN]
  137         ///< The SSID to set as an octet array.
  138 
  139     size_t ssidNumElements
  140         ///< [IN]
  141         ///< The length of the SSID in octets.
  142 );
  143 
  144 //--------------------------------------------------------------------------------------------------
  145 /**
  146  * Set the passphrase used to generate the PSK.
  147  *
  148  * @note This is one way to authenticate against the access point. The other one is provided by the
  149  * le_wifiAp_SetPreSharedKey() function. Both ways are exclusive and are effective only when used
  150  * with WPA-personal authentication.
  151  *
  152  * @return LE_BAD_PARAMETER Parameter is invalid.
  153  * @return LE_OK            Function succeeded.
  154  */
  155 //--------------------------------------------------------------------------------------------------
  156 le_result_t pa_wifiAp_SetPassPhrase
  157 (
  158     const char *passphrasePtr
  159         ///< [IN]
  160         ///< Passphrase to authenticate against the access point.
  161 );
  162 
  163 //--------------------------------------------------------------------------------------------------
  164 /**
  165  * Set the pre-shared key (PSK).
  166  *
  167  * @note This is one way to authenticate against the access point. The other one is provided by the
  168  * le_wifiAp_SetPassPhrase() function. Both ways are exclusive and are effective only when used
  169  * with WPA-personal authentication.
  170  *
  171  * @return LE_BAD_PARAMETER Parameter is invalid.
  172  * @return LE_OK            Function succeeded.
  173  */
  174 //--------------------------------------------------------------------------------------------------
  175 le_result_t pa_wifiAp_SetPreSharedKey
  176 (
  177     const char *preSharedKeyPtr
  178         ///< [IN]
  179         ///< Pre-shared key used to authenticate against the access point.
  180 );
  181 
  182 //--------------------------------------------------------------------------------------------------
  183 /**
  184  * Set if the Access Point should announce it's presence.
  185  * Default value is TRUE.
  186  * If the value is set to FALSE, the access point will be hidden.
  187  *
  188  * @return LE_OK            Function succeeded.
  189  *
  190  */
  191 //--------------------------------------------------------------------------------------------------
  192 le_result_t pa_wifiAp_SetDiscoverable
  193 (
  194     bool isDiscoverable
  195         ///< [IN]
  196         ///< If TRUE, the access point SSID is visible by the clients otherwise it is hidden.
  197 );
  198 
  199 //--------------------------------------------------------------------------------------------------
  200 /**
  201  * Set the WiFi channel to use.
  202  * Default value is 1.
  203  * Some legal restrictions for values 12 - 14 might apply for your region.
  204  *
  205  * @return LE_OUT_OF_RANGE Requested channel number is out of range.
  206  * @return LE_OK           Function succeeded.
  207  *
  208  */
  209 //--------------------------------------------------------------------------------------------------
  210 le_result_t pa_wifiAp_SetChannel
  211 (
  212     int8_t channelNumber
  213         ///< [IN]
  214         ///< the channel number must be between 1 and 14.
  215 );
  216 
  217 //--------------------------------------------------------------------------------------------------
  218 /**
  219  * Set the maximum number of clients connected to WiFi access point at the same time.
  220  * Default value is 10.
  221  *
  222  * @note This value depends on the hardware/software capabilities of the WiFi module used.
  223  *
  224  * @return LE_OUT_OF_RANGE  Requested number of users exceeds the capabilities of the Access Point.
  225  * @return LE_OK            Function succeeded.
  226  *
  227  */
  228 //--------------------------------------------------------------------------------------------------
  229 le_result_t pa_wifiAp_SetMaxNumberClients
  230 (
  231     int maxNumberClients
  232         ///< [IN]
  233         ///< the maximum number of clients regarding the WiFi driver and hardware capabilities.
  234 );
  235 
  236 //--------------------------------------------------------------------------------------------------
  237 /**
  238  * Define the access point IP address and the client IP addresses range.
  239  *
  240  * @note The access point IP address must be defined outside the client IP addresses range.
  241  *
  242  * @return LE_BAD_PARAMETER At least, one of the given IP addresses is invalid.
  243  * @return LE_FAULT         A system call has failed.
  244  * @return LE_OK            Function succeeded.
  245  *
  246  */
  247 //--------------------------------------------------------------------------------------------------
  248 le_result_t pa_wifiAp_SetIpRange
  249 (
  250     const char *ipApPtr,
  251         ///< [IN]
  252         ///< the IP address of the Access Point.
  253     const char *ipStartPtr,
  254         ///< [IN]
  255         ///< the start IP address of the Access Point.
  256     const char *ipStopPtr
  257         ///< [IN]
  258         ///< the stop IP address of the Access Point.
  259 );
  260 #endif // PA_WIFI_AP_H
LE_SHARED
#define LE_SHARED
Definition: le_basics.h:240
le_wifiAp_Event_t
le_wifiAp_Event_t
Definition: le_wifiAp_interface.h:184
le_result_t
le_result_t
Definition: le_basics.h:35
le_wifiAp_SecurityProtocol_t
le_wifiAp_SecurityProtocol_t
Definition: le_wifiAp_interface.h:199
legato.h