diff --git a/features/net/network-socket/NetworkInterface.h b/features/net/network-socket/NetworkInterface.h index 4defc0c5ecc..381dc83e511 100644 --- a/features/net/network-socket/NetworkInterface.h +++ b/features/net/network-socket/NetworkInterface.h @@ -36,6 +36,12 @@ class NetworkInterface { */ virtual const char *get_ip_address() = 0; + /** Get the local MAC address + * + * @return Null-terminated representation of the local MAC address + */ + virtual const char *get_mac_address() = 0; + protected: friend class Socket; friend class UDPSocket; diff --git a/features/net/network-socket/WiFiInterface.h b/features/net/network-socket/WiFiInterface.h index dada562aec9..21e4f10ca4c 100644 --- a/features/net/network-socket/WiFiInterface.h +++ b/features/net/network-socket/WiFiInterface.h @@ -1,5 +1,5 @@ /* WiFiInterface - * Copyright (c) 2015 ARM Limited + * Copyright (c) 2015 - 2016 ARM Limited * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -17,22 +17,19 @@ #ifndef WIFI_INTERFACE_H #define WIFI_INTERFACE_H +#include #include "network-socket/NetworkInterface.h" +typedef struct wifi_ap { + char ssid[33]; /* 32 is what 802.11 defines as longest possible name; +1 for the \0 */ + uint8_t bssid[6]; + nsapi_security_t security; + int8_t rssi; + uint8_t channel; +} wifi_ap_t; -/** Enum of WiFi encryption types - * - * The security type specifies a particular security to use when - * connected to a WiFi network - * - * @enum nsapi_protocol_t - */ -enum nsapi_security_t { - NSAPI_SECURITY_NONE = 0, /*!< open access point */ - NSAPI_SECURITY_WEP, /*!< phrase conforms to WEP */ - NSAPI_SECURITY_WPA, /*!< phrase conforms to WPA */ - NSAPI_SECURITY_WPA2, /*!< phrase conforms to WPA2 */ -}; +typedef void (*wifi_ap_scan_cb_t)(wifi_ap_t *ap, void *data); +typedef void (*wifi_connect_cb_t)(nsapi_error_t res, void *data); /** WiFiInterface class * @@ -43,28 +40,81 @@ class WiFiInterface: public NetworkInterface public: /** Start the interface * - * Attempts to connect to a WiFi network. If passphrase is invalid, - * NSAPI_ERROR_AUTH_ERROR is returned. + * Attempts to connect to a WiFi network. + * + * @param ssid Name of the network to connect to + * @param pass Security passphrase to connect to the network + * @param security Type of encryption for connection + * @param timeout Timeout in milliseconds; 0 for no timeout + * @return 0 on success, or error code on failure + */ + virtual nsapi_error_t connect(const char *ssid, const char *pass, nsapi_security_t security = NSAPI_SECURITY_NONE, + unsigned timeout = 0) = 0; + + /** Start the interface + * + * Attempts to connect to a WiFi network asynchronously, the call will return straight away. If the @a cb was NULL + * you'll need to query @a get_state until it's in NSAPI_IF_STATE_CONNECTED state, otherwise the @a cb will be + * called with connection results. + * + * Note: @a ssid and @a pass must be kept until the connection is made, that is the callback has been called or the + * state changed to @a NSAPI_IF_STATE_CONNECTED as they are passed by value. * * @param ssid Name of the network to connect to * @param pass Security passphrase to connect to the network * @param security Type of encryption for connection - * @return 0 on success, negative error code on failure + * @param cb Function to be called when the connect finishes + * @param data Arbitrary user data to pass to @a cb function */ - virtual int connect(const char *ssid, const char *pass, nsapi_security_t security = NSAPI_SECURITY_NONE) = 0; + virtual void connect_async(const char *ssid, const char *pass,nsapi_security_t security = NSAPI_SECURITY_NONE, + wifi_connect_cb_t cb = NULL, void *data = NULL) = 0; /** Stop the interface * - * @return 0 on success, negative error code on failure + * @return 0 on success, or error code on failure */ - virtual int disconnect() = 0; + virtual nsapi_error_t disconnect() = 0; /** Get the local MAC address * * @return Null-terminated representation of the local MAC address */ virtual const char *get_mac_address() = 0; -}; + /** Get the current WiFi interface state + * + * @returns Interface state enum + */ + virtual nsapi_if_state_t get_state() = 0; + + /** Gets the current radio signal strength for active connection + * + * @return Connection strength in dBm (negative value), or 0 if measurement impossible + */ + virtual int8_t get_rssi() = 0; + + /** Scan for available networks + * + * This function will block. + * + * @param ap Pointer to allocated array to store discovered AP + * @param count Size of allocated @a res array, or 0 to only count available AP + * @param timeout Timeout in milliseconds; 0 for no timeout + * @return Number of entries in @a, or if @a count was 0 number of available networks, negative on error + * see @a nsapi_error + */ + virtual int scan(wifi_ap_t *res, unsigned count, unsigned timeout = 0) = 0; + + /** Scan for available networks + * + * This function won't block, it'll return immediately and call provided callback for each discovered network with + * AP data and user @a data. After the last discovered network @a cb will be called with NULL as @a ap, so it + * will be always called at least once. + * + * @param cb Function to be called for every discovered network + * @param data A user handle that will be passed to @a cb along with the AP data + */ + virtual void scan_async(wifi_ap_scan_cb_t cb, void *data = NULL) = 0; +}; #endif diff --git a/features/net/network-socket/nsapi_types.h b/features/net/network-socket/nsapi_types.h index 669ef40311e..5044a877e53 100644 --- a/features/net/network-socket/nsapi_types.h +++ b/features/net/network-socket/nsapi_types.h @@ -24,7 +24,7 @@ extern "C" { #endif -/** Enum of standardized error codes +/** Enum of standardized error codes * * Valid error codes have negative values and may * be returned by any network operation. @@ -32,6 +32,7 @@ extern "C" { * @enum nsapi_error_t */ typedef enum nsapi_error { + NSAPI_ERROR_OK = 0, /*!< no error */ NSAPI_ERROR_WOULD_BLOCK = -3001, /*!< no data is not available but call is non-blocking */ NSAPI_ERROR_UNSUPPORTED = -3002, /*!< unsupported functionality */ NSAPI_ERROR_PARAMETER = -3003, /*!< invalid configuration */ @@ -41,10 +42,36 @@ typedef enum nsapi_error { NSAPI_ERROR_NO_MEMORY = -3007, /*!< memory resource not available */ NSAPI_ERROR_DNS_FAILURE = -3008, /*!< DNS failed to complete successfully */ NSAPI_ERROR_DHCP_FAILURE = -3009, /*!< DHCP failed to complete successfully */ - NSAPI_ERROR_AUTH_FAILURE = -3010, /*!< connection to access point faield */ - NSAPI_ERROR_DEVICE_ERROR = -3011, /*!< failure interfacing with the network procesor */ + NSAPI_ERROR_AUTH_FAILURE = -3010, /*!< connection to access point failed */ + NSAPI_ERROR_DEVICE_ERROR = -3011, /*!< failure interfacing with the network processor */ + NSAPI_ERROR_TIMEOUT = -3012, /*!< operation timed out */ + NSAPI_ERROR_BAD_SSID = -3013, /*!< ssid not found */ } nsapi_error_t; +/** Enum of encryption types + * + * The security type specifies a particular security to use when + * connected to a WiFi network + */ +typedef enum nsapi_security { + NSAPI_SECURITY_NONE = 0x0, /*!< open access point */ + NSAPI_SECURITY_WEP = 0x1, /*!< phrase conforms to WEP */ + NSAPI_SECURITY_WPA = 0x2, /*!< phrase conforms to WPA */ + NSAPI_SECURITY_WPA2 = 0x3, /*!< phrase conforms to WPA2 */ + NSAPI_SECURITY_WPA_WPA2 = 0x4, /*!< phrase conforms to WPA/WPA2 */ + NSAPI_SECURITY_UNSSUPPORTED = 0xFF, /*!< unknown/unsupported security in scan results */ +} nsapi_security_t; + +/** Enum of interface states + * + * List of all possible states a WiFi network interface can be in + */ +typedef enum nsapi_if_state { + NSAPI_IF_STATE_NOT_CONNECTED = 0x0, + NSAPI_IF_STATE_CONNECTING = 0x01, + NSAPI_IF_STATE_CONNECTED = 0x02, + NSAPI_IF_STATE_ERROR = 0xFF +} nsapi_if_state_t; /** Maximum size of IP address representation */