ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'docs-fix-networkiface' of ssh://github.com/paul-szczepanek-arm/mbed-os into rollup

pull/8552/head
Cruz Monrreal II 2018-10-26 11:48:45 -05:00
parent 99e198aa4f 2bab24ffc5
commit e8728148ac
12 changed files with 256 additions and 326 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
components/wifi/esp8266-driver/ESP8266Interface.h
View File

@ -153,36 +153,12 @@ public:
*/ */
using NetworkInterface::add_dns_server; using NetworkInterface::add_dns_server;
/** Set socket options /** @copydoc NetworkStack::setsockopt
*
* The setsockopt allow an application to pass stack-specific hints
* to the underlying stack. For unsupported options,
* NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
*
* @param handle Socket handle
* @param level Stack-specific protocol level
* @param optname Stack-specific option identifier
* @param optval Option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
*/ */
virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
int optname, const void *optval, unsigned optlen); int optname, const void *optval, unsigned optlen);
/** Get socket options /** @copydoc NetworkStack::getsockopt
*
* getsockopt allows an application to retrieve stack-specific options
* from the underlying stack using stack-specific level and option names,
* or to request generic options using levels from nsapi_socket_level_t.
*
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
* and the socket is unmodified.
*
* @param level Stack-specific protocol level or nsapi_socket_level_t
* @param optname Level-specific option name
* @param optval Destination for option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
*/ */
virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname, virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname,
void *optval, unsigned *optlen); void *optval, unsigned *optlen);

85
features/netsocket/CellularBase.h
View File

@ -18,115 +18,114 @@
#include "netsocket/NetworkInterface.h" #include "netsocket/NetworkInterface.h"
/** CellularBase class /** Common interface that is shared between cellular interfaces.
* * @addtogroup netsocket
* Common interface that is shared between Cellular interfaces
*/ */
class CellularBase: public NetworkInterface { class CellularBase: public NetworkInterface {
public: public:
/** Get the default cellular interface.
/** Get the default Cellular interface.
* *
* This is provided as a weak method so applications can override. * This is provided as a weak method so applications can override.
* Default behaviour is to get the target's default interface, if * Default behaviour is to get the target's default interface, if
* any. * any.
* *
* @return pointer to interface, if any * @return pointer to interface, if any.
*/ */
static CellularBase *get_default_instance(); static CellularBase *get_default_instance();
/** Set the Cellular network credentials /** Set the cellular network credentials.
* *
* Please check documentation of connect() for default behaviour of APN settings. * Please check documentation of connect() for default behaviour of APN settings.
* *
* @param apn Access point name * @param apn Access point name.
* @param uname optionally, Username * @param uname Username (optional).
* @param pwd optionally, password * @param pwd Password (optional).
*/ */
virtual void set_credentials(const char *apn, const char *uname = 0, virtual void set_credentials(const char *apn, const char *uname = 0,
const char *pwd = 0) = 0; const char *pwd = 0) = 0;
/** Set the pin code for SIM card /** Set the PIN code for SIM card.
* *
* @param sim_pin PIN for the SIM card * @param sim_pin PIN for the SIM card.
*/ */
virtual void set_sim_pin(const char *sim_pin) = 0; virtual void set_sim_pin(const char *sim_pin) = 0;
/** Start the interface /** Attempt to connect to a cellular network with a PIN and credentials.
* *
* Attempts to connect to a Cellular network. * @param sim_pin PIN for the SIM card.
* * @param apn Access point name (optional).
* @param sim_pin PIN for the SIM card * @param uname Username (optional).
* @param apn optionally, access point name * @param pwd Password (optional).
* @param uname optionally, Username * @return NSAPI_ERROR_OK on success, or negative error code on failure.
* @param pwd optionally, password
* @return NSAPI_ERROR_OK on success, or negative error code on failure
*/ */
virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0, virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
const char *uname = 0, const char *uname = 0,
const char *pwd = 0) = 0; const char *pwd = 0) = 0;
/** Start the interface /** Attempt to connect to a cellular network.
* *
* Attempts to connect to a Cellular network. * If the SIM requires a PIN, and it is invalid or not set, NSAPI_ERROR_AUTH_ERROR is returned.
* If the SIM requires a PIN, and it is not set/invalid, NSAPI_ERROR_AUTH_ERROR is returned.
* *
* @return NSAPI_ERROR_OK on success, or negative error code on failure * @return NSAPI_ERROR_OK on success, or negative error code on failure.
*/ */
virtual nsapi_error_t connect() = 0; virtual nsapi_error_t connect() = 0;
/** Stop the interface /** Stop the interface.
* *
* @return 0 on success, or error code on failure * @return NSAPI_ERROR_OK on success, or error code on failure.
*/ */
virtual nsapi_error_t disconnect() = 0; virtual nsapi_error_t disconnect() = 0;
/** Check if the connection is currently established or not /** Check if the connection is currently established.
* *
* @return true/false If the cellular module have successfully acquired a carrier and is * @return `true` if the cellular module have successfully acquired a carrier and is
* connected to an external packet data network using PPP, isConnected() * connected to an external packet data network using PPP, `false` otherwise.
* API returns true and false otherwise.
*/ */
virtual bool is_connected() = 0; virtual bool is_connected() = 0;
/** Get the local IP address /** Get the local IP address.
* *
* @return Null-terminated representation of the local IP address * @return Null-terminated representation of the local IP address,
* or null if no IP address has been received * or null if no IP address has been received.
*/ */
virtual const char *get_ip_address() = 0; virtual const char *get_ip_address() = 0;
/** Get the local network mask /** Get the local network mask.
* *
* @return Null-terminated representation of the local network mask * @return Null-terminated representation of the local network mask,
* or null if no network mask has been received * or null if no network mask has been received.
*/ */
virtual const char *get_netmask() = 0; virtual const char *get_netmask() = 0;
/** Get the local gateways /** Get the local gateways.
* *
* @return Null-terminated representation of the local gateway * @return Null-terminated representation of the local gateway,
* or null if no network mask has been received * or null if no network mask has been received.
*/ */
virtual const char *get_gateway() = 0; virtual const char *get_gateway() = 0;
/** @copydoc NetworkInterface::cellularBase
*/
virtual CellularBase *cellularBase() virtual CellularBase *cellularBase()
{ {
return this; return this;
} }
#if !defined(DOXYGEN_ONLY)
protected: protected:
/** Get the target's default Cellular interface. /** Get the target's default cellular interface.
* *
* This is provided as a weak method so targets can override. The * This is provided as a weak method so targets can override. The
* default implementation configures and returns the OnBoardModemInterface * default implementation configures and returns the OnBoardModemInterface,
* if available. * if available.
* *
* @return pointer to interface, if any * @return Pointer to interface, if any.
*/ */
static CellularBase *get_target_default_instance(); static CellularBase *get_target_default_instance();
#endif //!defined(DOXYGEN_ONLY)
}; };
#endif //CELLULAR_BASE_H #endif //CELLULAR_BASE_H

58
features/netsocket/DNS.h
View File

@ -20,7 +20,7 @@
class DNS { class DNS {
public: public:
/** Translates a hostname to an IP address with specific version /** Translate a hostname to an IP address with specific version.
* *
* The hostname may be either a domain name or an IP address. If the * The hostname may be either a domain name or an IP address. If the
* hostname is an IP address, no network transactions will be performed. * hostname is an IP address, no network transactions will be performed.
@ -28,18 +28,18 @@ public:
* If no stack-specific DNS resolution is provided, the hostname * If no stack-specific DNS resolution is provided, the hostname
* will be resolve using a UDP socket on the stack. * will be resolve using a UDP socket on the stack.
* *
* @param host Hostname to resolve * @param host Hostname to resolve.
* @param address Destination for the host SocketAddress * @param address Pointer to a SocketAddress to store the result.
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
* version is chosen by the stack (defaults to NSAPI_UNSPEC) * version is chosen by the stack (defaults to NSAPI_UNSPEC).
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t gethostbyname(const char *host, virtual nsapi_error_t gethostbyname(const char *host,
SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC) = 0; SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC) = 0;
/** Hostname translation callback (asynchronous) /** Hostname translation callback for gethostbyname_async.
* *
* Callback will be called after DNS resolution completes or a failure occurs. * The callback is called after DNS resolution completes, or a failure occurs.
* *
* Callback should not take more than 10ms to execute, otherwise it might * Callback should not take more than 10ms to execute, otherwise it might
* prevent underlying thread processing. A portable user of the callback * prevent underlying thread processing. A portable user of the callback
@ -47,49 +47,49 @@ public:
* The callback should not perform expensive operations such as socket recv/send * The callback should not perform expensive operations such as socket recv/send
* calls or blocking operations. * calls or blocking operations.
* *
* @param status 0 on success, negative error code on failure * @param result NSAPI_ERROR_OK on success, negative error code on failure.
* @param address On success, destination for the host SocketAddress * @param address On success, destination for the host SocketAddress.
*/ */
typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t; typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
/** Translates a hostname to an IP address (asynchronous) /** Translate a hostname to an IP address (asynchronous).
* *
* The hostname may be either a domain name or an IP address. If the * The hostname may be either a domain name or an IP address. If the
* hostname is an IP address, no network transactions will be performed. * hostname is an IP address, no network transactions will be performed.
* *
* If no stack-specific DNS resolution is provided, the hostname * If no stack-specific DNS resolution is provided, the hostname
* will be resolve using a UDP socket on the stack. * will be resolved using a UDP socket on the stack.
* *
* Call is non-blocking. Result of the DNS operation is returned by the callback. * The call is non-blocking. The result of the DNS operation is returned by the callback.
* If this function returns failure, callback will not be called. In case result * If this function returns failure, the callback will not be called. If it is successful,
* is success (IP address was found from DNS cache), callback will be called * (the IP address was found from the DNS cache), the callback will be called
* before function returns. * before the function returns.
* *
* @param host Hostname to resolve * @param host Hostname to resolve.
* @param callback Callback that is called for result * @param callback Callback that is called to return the result.
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates * @param version IP version of address to resolve. NSAPI_UNSPEC indicates that the
* version is chosen by the stack (defaults to NSAPI_UNSPEC) * version is chosen by the stack (defaults to NSAPI_UNSPEC).
* @return 0 on immediate success, * @return NSAPI_ERROR_OK on immediate success,
* negative error code on immediate failure or * negative error code on immediate failure or
* a positive unique id that represents the hostname translation operation * a positive unique ID that represents the hostname translation operation
* and can be passed to cancel * and can be passed to cancel.
*/ */
virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback,
nsapi_version_t version = NSAPI_UNSPEC) = 0; nsapi_version_t version = NSAPI_UNSPEC) = 0;
/** Cancels asynchronous hostname translation /** Cancel asynchronous hostname translation.
* *
* When translation is cancelled, callback will not be called. * When translation is canceled, callback is not called.
* *
* @param id Unique id of the hostname translation operation * @param id Unique ID of the hostname translation operation returned by gethostbyname_async.
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t gethostbyname_async_cancel(int id) = 0; virtual nsapi_error_t gethostbyname_async_cancel(int id) = 0;
/** Add a domain name server to list of servers to query /** Add a domain name server to list of servers to query.
* *
* @param address Destination for the host address * @param address DNS server host address.
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t add_dns_server(const SocketAddress &address) = 0; virtual nsapi_error_t add_dns_server(const SocketAddress &address) = 0;
}; };

12
features/netsocket/EthInterface.h
View File

@ -23,13 +23,13 @@
#include "netsocket/NetworkInterface.h" #include "netsocket/NetworkInterface.h"
/** EthInterface class /** Common interface that is shared between Ethernet hardware.
*
* Common interface that is shared between ethernet hardware.
*/ */
class EthInterface : public virtual NetworkInterface { class EthInterface : public virtual NetworkInterface {
public: public:
/** @copydoc NetworkInterface::ethInterface
*/
virtual EthInterface *ethInterface() virtual EthInterface *ethInterface()
{ {
return this; return this;
@ -41,10 +41,11 @@ public:
* Default behaviour is to get the target's default interface, if * Default behaviour is to get the target's default interface, if
* any. * any.
* *
* @return pointer to interface, if any * @return Pointer to interface, if one exists.
*/ */
static EthInterface *get_default_instance(); static EthInterface *get_default_instance();
#if !defined(DOXYGEN_ONLY)
protected: protected:
/** Get the target's default Ethernet interface. /** Get the target's default Ethernet interface.
@ -53,9 +54,10 @@ protected:
* default implementation will invoke EthernetInterface with the * default implementation will invoke EthernetInterface with the
* default EMAC and default network stack, if DEVICE_EMAC is set. * default EMAC and default network stack, if DEVICE_EMAC is set.
* *
* @return pointer to interface, if any * @return Pointer to interface, if one exists.
*/ */
static EthInterface *get_target_default_instance(); static EthInterface *get_target_default_instance();
#endif //!defined(DOXYGEN_ONLY)
}; };

9
features/netsocket/EthernetInterface.h
View File

@ -21,12 +21,11 @@
#include "EMACInterface.h" #include "EMACInterface.h"
/** EthernetInterface class /** Implementation of the NetworkStack for an EMAC-based Ethernet driver.
* Implementation of the NetworkStack for an EMAC-based Ethernet driver
*/ */
class EthernetInterface : public EMACInterface, public EthInterface { class EthernetInterface : public EMACInterface, public EthInterface {
public: public:
/** Create an EMAC-based ethernet interface. /** Create an EMAC-based Ethernet interface.
* *
* The default arguments obtain the default EMAC, which will be target- * The default arguments obtain the default EMAC, which will be target-
* dependent (and the target may have some JSON option to choose which * dependent (and the target may have some JSON option to choose which
@ -36,8 +35,8 @@ public:
* Due to inability to return errors from the constructor, no real * Due to inability to return errors from the constructor, no real
* work is done until the first call to connect(). * work is done until the first call to connect().
* *
* @param emac Reference to EMAC to use * @param emac Reference to EMAC to use.
* @param stack Reference to onboard-network stack to use * @param stack Reference to onboard-network stack to use.
*/ */
EthernetInterface(EMAC &emac = EMAC::get_default_instance(), EthernetInterface(EMAC &emac = EMAC::get_default_instance(),
OnboardNetworkStack &stack = OnboardNetworkStack::get_default_instance()) : EMACInterface(emac, stack) { } OnboardNetworkStack &stack = OnboardNetworkStack::get_default_instance()) : EMACInterface(emac, stack) { }

70
features/netsocket/InternetSocket.h
View File

@ -93,85 +93,27 @@ public:
*/ */
nsapi_error_t bind(const char *address, uint16_t port); nsapi_error_t bind(const char *address, uint16_t port);
/** Bind the socket to a specific address and port on which to receive /** @copydoc Socket::bind
* data. If the IP address is zeroed, only the port is bound.
*
* @param address Local SocketAddress to bind, which includes the address and port.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/ */
virtual nsapi_error_t bind(const SocketAddress &address); virtual nsapi_error_t bind(const SocketAddress &address);
/** Set blocking or nonblocking mode of the socket. /** @copydoc Socket::set_blocking
*
* Initially all sockets are in blocking mode. In nonblocking mode,
* blocking operations, such as send/recv/accept, return
* NSAPI_ERROR_WOULD_BLOCK if they cannot continue.
*
* @note set_blocking(false) is equivalent to set_timeout(-1) and
* set_blocking(true) is equivalent to set_timeout(0).
*
* @param blocking Use true for blocking mode, false for nonblocking mode.
*/ */
virtual void set_blocking(bool blocking); virtual void set_blocking(bool blocking);
/** Set timeout on blocking socket operations. /** @copydoc Socket::set_timeout
*
* Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
* is returned if a blocking operation takes longer than the specified
* timeout. A timeout of 0 removes the timeout from the socket. A negative
* value give the socket an unbounded timeout.
*
* @note set_timeout(0) is equivalent to set_blocking(false) and
* set_timeout(-1) is equivalent to set_blocking(true).
*
* @param timeout Timeout in milliseconds.
*/ */
virtual void set_timeout(int timeout); virtual void set_timeout(int timeout);
/** Pass stack-specific options to the underlying stack using stack-specific /** @copydoc Socket::setsockopt
* level and option names, or request generic options using levels from nsapi_socket_level_t.
*
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned,
* and the socket is unmodified.
*
* @param level Stack-specific protocol level or nsapi_socket_level_t.
* @param optname Level-specific option name.
* @param optval Option value.
* @param optlen Length of the option value.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/ */
virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen); virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen);
/** Retrieve stack-specific options from the underlying stack using /** @copydoc Socket::getsockopt
* stack-specific level and option names, or request generic options
* using levels from nsapi_socket_level_t.
*
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned,
* and the socket is unmodified.
*
* @param level Stack-specific protocol level or nsapi_socket_level_t.
* @param optname Level-specific option name.
* @param optval Destination for option value.
* @param optlen Length of the option value.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
*/ */
virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen); virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen);
/** Register a callback on state change of the socket. /** @copydoc Socket::sigio
*
* The specified callback is called on state changes, such as when
* the socket can recv/send/accept successfully and when an error
* occurs. The callback may also be called spuriously without a reason.
*
* The callback may be called in an interrupt context and should not
* perform expensive operations, such as recv/send calls.
*
* @note This is not intended as a replacement for a poll or attach-like
* asynchronous API, but rather as a building block for constructing
* such functionality. The exact timing of when the registered function
* is called is not guaranteed and is susceptible to change.
*
* @param func Function to call on state change.
*/ */
virtual void sigio(mbed::Callback<void()> func); virtual void sigio(mbed::Callback<void()> func);

13
features/netsocket/MeshInterface.h
View File

@ -23,13 +23,12 @@
#include "netsocket/NetworkInterface.h" #include "netsocket/NetworkInterface.h"
/** MeshInterface class /** Common interface that is shared between mesh hardware
*
* Common interface that is shared between mesh hardware
*/ */
class MeshInterface : public virtual NetworkInterface { class MeshInterface : public virtual NetworkInterface {
public: public:
/** @copydoc NetworkInterface::meshInterface
*/
virtual MeshInterface *meshInterface() virtual MeshInterface *meshInterface()
{ {
return this; return this;
@ -41,10 +40,11 @@ public:
* Default behaviour is to get the target's default interface, if * Default behaviour is to get the target's default interface, if
* any. * any.
* *
* @return pointer to interface, if any * @return pointer to interface, if any.
*/ */
static MeshInterface *get_default_instance(); static MeshInterface *get_default_instance();
#if !defined(DOXYGEN_ONLY)
protected: protected:
/** Get the target's default Mesh interface. /** Get the target's default Mesh interface.
@ -53,9 +53,10 @@ protected:
* default implementation will invoke LoWPANNDInterface or ThreadInterface * default implementation will invoke LoWPANNDInterface or ThreadInterface
* with the default NanostackRfPhy. * with the default NanostackRfPhy.
* *
* @return pointer to interface, if any * @return pointer to interface, if any.
*/ */
static MeshInterface *get_target_default_instance(); static MeshInterface *get_target_default_instance();
#endif //!defined(DOXYGEN_ONLY)
}; };

133
features/netsocket/NetworkInterface.h
View File

@ -31,9 +31,8 @@ class MeshInterface;
class CellularBase; class CellularBase;
class EMACInterface; class EMACInterface;
/** NetworkInterface class /** Common interface that is shared between network devices.
* *
* Common interface that is shared between network devices
* @addtogroup netsocket * @addtogroup netsocket
*/ */
class NetworkInterface: public DNS { class NetworkInterface: public DNS {
@ -41,13 +40,14 @@ public:
virtual ~NetworkInterface() {}; virtual ~NetworkInterface() {};
/** Return the default network interface /** Return the default network interface.
* *
* Returns the default network interface, as determined by JSON option * Returns the default network interface, as determined by JSON option
* target.network-default-interface-type or other overrides. * target.network-default-interface-type or other overrides.
* *
* The type of the interface returned can be tested via the ethInterface() * The type of the interface returned can be tested by calling ethInterface(),
* etc downcasts. * wifiInterface(), meshInterface(), cellularBase(), emacInterface() and checking
* for NULL pointers.
* *
* The default behaviour is to return the default interface for the * The default behaviour is to return the default interface for the
* interface type specified by target.network-default-interface-type. Targets * interface type specified by target.network-default-interface-type. Targets
@ -79,75 +79,72 @@ public:
*/ */
static NetworkInterface *get_default_instance(); static NetworkInterface *get_default_instance();
/** Get the local MAC address /** Get the local MAC address.
* *
* Provided MAC address is intended for info or debug purposes and * Provided MAC address is intended for info or debug purposes and
* may not be provided if the underlying network interface does not * may be not provided if the underlying network interface does not
* provide a MAC address * provide a MAC address.
* *
* @return Null-terminated representation of the local MAC address * @return Null-terminated representation of the local MAC address
* or null if no MAC address is available * or null if no MAC address is available.
*/ */
virtual const char *get_mac_address(); virtual const char *get_mac_address();
/** Get the local IP address /** Get the local IP address.
* *
* @return Null-terminated representation of the local IP address * @return Null-terminated representation of the local IP address
* or null if no IP address has been received * or null if no IP address has been received.
*/ */
virtual const char *get_ip_address(); virtual const char *get_ip_address();
/** Get the local network mask /** Get the local network mask.
* *
* @return Null-terminated representation of the local network mask * @return Null-terminated representation of the local network mask
* or null if no network mask has been received * or null if no network mask has been received.
*/ */
virtual const char *get_netmask(); virtual const char *get_netmask();
/** Get the local gateway /** Get the local gateway.
* *
* @return Null-terminated representation of the local gateway * @return Null-terminated representation of the local gateway
* or null if no network mask has been received * or null if no network mask has been received.
*/ */
virtual const char *get_gateway(); virtual const char *get_gateway();
/** Set a static IP address /** Configure this network interface to use a static IP address.
*
* Configures this network interface to use a static IP address.
* Implicitly disables DHCP, which can be enabled in set_dhcp. * Implicitly disables DHCP, which can be enabled in set_dhcp.
* Requires that the network is disconnected. * Requires that the network is disconnected.
* *
* @param ip_address Null-terminated representation of the local IP address * @param ip_address Null-terminated representation of the local IP address
* @param netmask Null-terminated representation of the local network mask * @param netmask Null-terminated representation of the local network mask
* @param gateway Null-terminated representation of the local gateway * @param gateway Null-terminated representation of the local gateway
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t set_network(const char *ip_address, const char *netmask, const char *gateway); virtual nsapi_error_t set_network(const char *ip_address, const char *netmask, const char *gateway);
/** Enable or disable DHCP on the network /** Enable or disable DHCP on connecting the network.
* *
* Enables DHCP on connecting the network. Defaults to enabled unless * Enabled by default unless a static IP address has been assigned. Requires
* a static IP address has been assigned. Requires that the network is * that the network is disconnected.
* disconnected.
* *
* @param dhcp True to enable DHCP * @param dhcp True to enable DHCP.
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t set_dhcp(bool dhcp); virtual nsapi_error_t set_dhcp(bool dhcp);
/** Start the interface /** Start the interface.
* *
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t connect() = 0; virtual nsapi_error_t connect() = 0;
/** Stop the interface /** Stop the interface.
* *
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t disconnect() = 0; virtual nsapi_error_t disconnect() = 0;
/** Translates a hostname to an IP address with specific version /** Translate a hostname to an IP address with specific version.
* *
* The hostname may be either a domain name or an IP address. If the * The hostname may be either a domain name or an IP address. If the
* hostname is an IP address, no network transactions will be performed. * hostname is an IP address, no network transactions will be performed.
@ -155,33 +152,33 @@ public:
* If no stack-specific DNS resolution is provided, the hostname * If no stack-specific DNS resolution is provided, the hostname
* will be resolve using a UDP socket on the stack. * will be resolve using a UDP socket on the stack.
* *
* @param host Hostname to resolve * @param host Hostname to resolve.
* @param address Destination for the host SocketAddress * @param address Pointer to a SocketAddress to store the result.
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
* version is chosen by the stack (defaults to NSAPI_UNSPEC) * version is chosen by the stack (defaults to NSAPI_UNSPEC).
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t gethostbyname(const char *host, virtual nsapi_error_t gethostbyname(const char *host,
SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC); SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC);
/** Hostname translation callback (asynchronous) /** Hostname translation callback (for use with gethostbyname_async()).
* *
* Callback will be called after DNS resolution completes or a failure occurs. * Callback will be called after DNS resolution completes or a failure occurs.
* *
* Callback should not take more than 10ms to execute, otherwise it might * @note Callback should not take more than 10ms to execute, otherwise it might
* prevent underlying thread processing. A portable user of the callback * prevent underlying thread processing. A portable user of the callback
* should not make calls to network operations due to stack size limitations. * should not make calls to network operations due to stack size limitations.
* The callback should not perform expensive operations such as socket recv/send * The callback should not perform expensive operations such as socket recv/send
* calls or blocking operations. * calls or blocking operations.
* *
* @param status 0 on success, negative error code on failure * @param result NSAPI_ERROR_OK on success, negative error code on failure.
* @param address On success, destination for the host SocketAddress * @param address On success, destination for the host SocketAddress.
*/ */
typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t; typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
/** Translates a hostname to an IP address (asynchronous) /** Translate a hostname to an IP address (asynchronous).
* *
* The hostname may be either a domain name or an IP address. If the * The hostname may be either a domain name or a dotted IP address. If the
* hostname is an IP address, no network transactions will be performed. * hostname is an IP address, no network transactions will be performed.
* *
* If no stack-specific DNS resolution is provided, the hostname * If no stack-specific DNS resolution is provided, the hostname
@ -192,87 +189,100 @@ public:
* is success (IP address was found from DNS cache), callback will be called * is success (IP address was found from DNS cache), callback will be called
* before function returns. * before function returns.
* *
* @param host Hostname to resolve * @param host Hostname to resolve.
* @param callback Callback that is called for result * @param callback Callback that is called for result.
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
* version is chosen by the stack (defaults to NSAPI_UNSPEC) * version is chosen by the stack (defaults to NSAPI_UNSPEC).
* @return 0 on immediate success, * @return 0 on immediate success,
* negative error code on immediate failure or * negative error code on immediate failure or
* a positive unique id that represents the hostname translation operation * a positive unique id that represents the hostname translation operation
* and can be passed to cancel * and can be passed to cancel.
*/ */
virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback,
nsapi_version_t version = NSAPI_UNSPEC); nsapi_version_t version = NSAPI_UNSPEC);
/** Cancels asynchronous hostname translation /** Cancel asynchronous hostname translation.
* *
* When translation is cancelled, callback will not be called. * When translation is cancelled, callback will not be called.
* *
* @param id Unique id of the hostname translation operation * @param id Unique id of the hostname translation operation (returned
* @return 0 on success, negative error code on failure * by gethostbyname_async)
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t gethostbyname_async_cancel(int id); virtual nsapi_error_t gethostbyname_async_cancel(int id);
/** Add a domain name server to list of servers to query /** Add a domain name server to list of servers to query
* *
* @param address Destination for the host address * @param address Address for the dns host.
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t add_dns_server(const SocketAddress &address); virtual nsapi_error_t add_dns_server(const SocketAddress &address);
/** Register callback for status reporting /** Register callback for status reporting.
* *
* The specified status callback function will be called on status changes * The specified status callback function will be called on status changes
* on the network. The parameters on the callback are the event type and * on the network. The parameters on the callback are the event type and
* event-type dependent reason parameter. * event-type dependent reason parameter.
* *
* @param status_cb The callback for status changes * @param status_cb The callback for status changes.
*/ */
virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb); virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
/** Get the connection status /** Get the connection status.
* *
* @return The connection status according to ConnectionStatusType * @return The connection status (@see nsapi_types.h).
*/ */
virtual nsapi_connection_status_t get_connection_status() const; virtual nsapi_connection_status_t get_connection_status() const;
/** Set blocking status of connect() which by default should be blocking /** Set blocking status of connect() which by default should be blocking.
* *
* @param blocking true if connect is blocking * @param blocking Use true to make connect() blocking.
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t set_blocking(bool blocking); virtual nsapi_error_t set_blocking(bool blocking);
/** Dynamic downcast to an EthInterface */ /** Return pointer to an EthInterface.
* @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
*/
virtual EthInterface *ethInterface() virtual EthInterface *ethInterface()
{ {
return 0; return 0;
} }
/** Dynamic downcast to a WiFiInterface */ /** Return pointer to a WiFiInterface.
* @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
*/
virtual WiFiInterface *wifiInterface() virtual WiFiInterface *wifiInterface()
{ {
return 0; return 0;
} }
/** Dynamic downcast to a MeshInterface */ /** Return pointer to a MeshInterface.
* @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
*/
virtual MeshInterface *meshInterface() virtual MeshInterface *meshInterface()
{ {
return 0; return 0;
} }
/** Dynamic downcast to a CellularBase */ /** Return pointer to a CellularBase.
* @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
*/
virtual CellularBase *cellularBase() virtual CellularBase *cellularBase()
{ {
return 0; return 0;
} }
/** Dynamic downcast to an EMACInterface */ /** Return pointer to an EMACInterface.
* @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
*/
virtual EMACInterface *emacInterface() virtual EMACInterface *emacInterface()
{ {
return 0; return 0;
} }
#if !defined(DOXYGEN_ONLY)
protected: protected:
friend class InternetSocket; friend class InternetSocket;
friend class UDPSocket; friend class UDPSocket;
@ -318,6 +328,7 @@ protected:
* performs the search described by get_default_instance. * performs the search described by get_default_instance.
*/ */
static NetworkInterface *get_target_default_instance(); static NetworkInterface *get_target_default_instance();
#endif //!defined(DOXYGEN_ONLY)
}; };

58
features/netsocket/NetworkStack.h
View File

@ -54,10 +54,10 @@ public:
* will be resolve using a UDP socket on the stack. * will be resolve using a UDP socket on the stack.
* *
* @param host Hostname to resolve * @param host Hostname to resolve
* @param address Destination for the host SocketAddress * @param address Pointer to a SocketAddress to store the result.
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
* version is chosen by the stack (defaults to NSAPI_UNSPEC) * version is chosen by the stack (defaults to NSAPI_UNSPEC)
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t gethostbyname(const char *host, virtual nsapi_error_t gethostbyname(const char *host,
SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC); SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC);
@ -72,7 +72,7 @@ public:
* The callback should not perform expensive operations such as socket recv/send * The callback should not perform expensive operations such as socket recv/send
* calls or blocking operations. * calls or blocking operations.
* *
* @param status 0 on success, negative error code on failure * @param status NSAPI_ERROR_OK on success, negative error code on failure
* @param address On success, destination for the host SocketAddress * @param address On success, destination for the host SocketAddress
*/ */
typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t; typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
@ -107,14 +107,14 @@ public:
* When translation is cancelled, callback will not be called. * When translation is cancelled, callback will not be called.
* *
* @param id Unique id of the hostname translation operation * @param id Unique id of the hostname translation operation
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t gethostbyname_async_cancel(int id); virtual nsapi_error_t gethostbyname_async_cancel(int id);
/** Add a domain name server to list of servers to query /** Add a domain name server to list of servers to query
* *
* @param address Destination for the host address * @param address Destination for the host address
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t add_dns_server(const SocketAddress &address); virtual nsapi_error_t add_dns_server(const SocketAddress &address);
@ -125,7 +125,7 @@ public:
* *
* @param index Index of the DNS server, starts from zero * @param index Index of the DNS server, starts from zero
* @param address Destination for the host address * @param address Destination for the host address
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t get_dns_server(int index, SocketAddress *address); virtual nsapi_error_t get_dns_server(int index, SocketAddress *address);
@ -142,7 +142,7 @@ public:
* @param optname Level-specific option name * @param optname Level-specific option name
* @param optval Option value * @param optval Option value
* @param optlen Length of the option value * @param optlen Length of the option value
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t setstackopt(int level, int optname, const void *optval, unsigned optlen); virtual nsapi_error_t setstackopt(int level, int optname, const void *optval, unsigned optlen);
@ -156,7 +156,7 @@ public:
* @param optname Level-specific option name * @param optname Level-specific option name
* @param optval Destination for option value * @param optval Destination for option value
* @param optlen Length of the option value * @param optlen Length of the option value
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t getstackopt(int level, int optname, void *optval, unsigned *optlen); virtual nsapi_error_t getstackopt(int level, int optname, void *optval, unsigned *optlen);
@ -182,7 +182,7 @@ protected:
* *
* @param handle Destination for the handle to a newly created socket * @param handle Destination for the handle to a newly created socket
* @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto) = 0; virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto) = 0;
@ -192,7 +192,7 @@ protected:
* with the socket. * with the socket.
* *
* @param handle Socket handle * @param handle Socket handle
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t socket_close(nsapi_socket_t handle) = 0; virtual nsapi_error_t socket_close(nsapi_socket_t handle) = 0;
@ -203,7 +203,7 @@ protected:
* *
* @param handle Socket handle * @param handle Socket handle
* @param address Local address to bind * @param address Local address to bind
* @return 0 on success, negative error code on failure. * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address) = 0; virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address) = 0;
@ -215,7 +215,7 @@ protected:
* @param handle Socket handle * @param handle Socket handle
* @param backlog Number of pending connections that can be queued * @param backlog Number of pending connections that can be queued
* simultaneously * simultaneously
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog) = 0; virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog) = 0;
@ -226,7 +226,7 @@ protected:
* *
* @param handle Socket handle * @param handle Socket handle
* @param address The SocketAddress of the remote host * @param address The SocketAddress of the remote host
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address) = 0; virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address) = 0;
@ -246,7 +246,7 @@ protected:
* @param server Socket handle to server to accept from * @param server Socket handle to server to accept from
* @param handle Destination for a handle to the newly created socket * @param handle Destination for a handle to the newly created socket
* @param address Destination for the remote address or NULL * @param address Destination for the remote address or NULL
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t socket_accept(nsapi_socket_t server, virtual nsapi_error_t socket_accept(nsapi_socket_t server,
nsapi_socket_t *handle, SocketAddress *address = 0) = 0; nsapi_socket_t *handle, SocketAddress *address = 0) = 0;
@ -336,34 +336,34 @@ protected:
*/ */
virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data) = 0; virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data) = 0;
/* Set stack-specific socket options /** Set stack-specific socket options.
* *
* The setsockopt allow an application to pass stack-specific hints * The setsockopt allow an application to pass stack-specific hints
* to the underlying stack. For unsupported options, * to the underlying stack. For unsupported options,
* NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified. * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
* *
* @param handle Socket handle * @param handle Socket handle.
* @param level Stack-specific protocol level * @param level Stack-specific protocol level.
* @param optname Stack-specific option identifier * @param optname Stack-specific option identifier.
* @param optval Option value * @param optval Option value.
* @param optlen Length of the option value * @param optlen Length of the option value.
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
int optname, const void *optval, unsigned optlen); int optname, const void *optval, unsigned optlen);
/* Get stack-specific socket options /** Get stack-specific socket options.
* *
* The getstackopt allow an application to retrieve stack-specific hints * The getstackopt allow an application to retrieve stack-specific hints
* from the underlying stack. For unsupported options, * from the underlying stack. For unsupported options,
* NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified. * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
* *
* @param handle Socket handle * @param handle Socket handle.
* @param level Stack-specific protocol level * @param level Stack-specific protocol level.
* @param optname Stack-specific option identifier * @param optname Stack-specific option identifier.
* @param optval Destination for option value * @param optval Destination for option value.
* @param optlen Length of the option value * @param optlen Length of the option value.
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level,
int optname, void *optval, unsigned *optlen); int optname, void *optval, unsigned *optlen);
@ -397,7 +397,7 @@ private:
* *
* @param delay Delay in milliseconds * @param delay Delay in milliseconds
* @param func Callback to be called * @param func Callback to be called
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t call_in(int delay, mbed::Callback<void()> func); virtual nsapi_error_t call_in(int delay, mbed::Callback<void()> func);
}; };

33
features/netsocket/Socket.h
View File

@ -38,7 +38,7 @@ public:
* Closes any open connection and deallocates any memory associated * Closes any open connection and deallocates any memory associated
* with the socket. Called from destructor if socket is not closed. * with the socket. Called from destructor if socket is not closed.
* *
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t close() = 0; virtual nsapi_error_t close() = 0;
@ -54,7 +54,7 @@ public:
* object have to be in the address parameter. * object have to be in the address parameter.
* *
* @param address The SocketAddress of the remote peer * @param address The SocketAddress of the remote peer
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t connect(const SocketAddress &address) = 0; virtual nsapi_error_t connect(const SocketAddress &address) = 0;
@ -142,10 +142,11 @@ public:
/** Bind a specific address to a socket. /** Bind a specific address to a socket.
* *
* Binding assigns a local address to a socket. * Binding a socket specifies the address and port on which to receive
* data. If the IP address is zeroed, only the port is bound.
* *
* @param address Local address to bind * @param address Local address to bind
* @return 0 on success, negative error code on failure. * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t bind(const SocketAddress &address) = 0; virtual nsapi_error_t bind(const SocketAddress &address) = 0;
@ -190,7 +191,7 @@ public:
* such functionality. The exact timing of when the registered function * such functionality. The exact timing of when the registered function
* is called is not guaranteed and susceptible to change. * is called is not guaranteed and susceptible to change.
* *
* @param func Function to call on state change * @param func Function to call on state change.
*/ */
virtual void sigio(mbed::Callback<void()> func) = 0; virtual void sigio(mbed::Callback<void()> func) = 0;
@ -203,11 +204,11 @@ public:
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
* and the socket is unmodified. * and the socket is unmodified.
* *
* @param level Stack-specific protocol level or nsapi_socket_level_t * @param level Stack-specific protocol level or nsapi_socket_level_t.
* @param optname Level-specific option name * @param optname Level-specific option name.
* @param optval Option value * @param optval Option value.
* @param optlen Length of the option value * @param optlen Length of the option value.
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0; virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0;
@ -220,11 +221,11 @@ public:
* For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
* and the socket is unmodified. * and the socket is unmodified.
* *
* @param level Stack-specific protocol level or nsapi_socket_level_t * @param level Stack-specific protocol level or nsapi_socket_level_t.
* @param optname Level-specific option name * @param optname Level-specific option name.
* @param optval Destination for option value * @param optval Destination for option value.
* @param optlen Length of the option value * @param optlen Length of the option value.
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0; virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0;
@ -250,7 +251,7 @@ public:
* *
* @param backlog Number of pending connections that can be queued * @param backlog Number of pending connections that can be queued
* simultaneously, defaults to 1 * simultaneously, defaults to 1
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure
*/ */
virtual nsapi_error_t listen(int backlog = 1) = 0; virtual nsapi_error_t listen(int backlog = 1) = 0;
}; };

75
features/netsocket/WiFiInterface.h
View File

@ -22,104 +22,103 @@
#include "netsocket/NetworkInterface.h" #include "netsocket/NetworkInterface.h"
#include "netsocket/WiFiAccessPoint.h" #include "netsocket/WiFiAccessPoint.h"
/** WiFiInterface class /** Common interface that is shared between Wi-Fi devices.
* *
* Common interface that is shared between WiFi devices
* @addtogroup netsocket * @addtogroup netsocket
*/ */
class WiFiInterface: public virtual NetworkInterface { class WiFiInterface: public virtual NetworkInterface {
public: public:
/** Get the default WiFi interface. /** Get the default Wi-Fi interface.
* *
* This is provided as a weak method so applications can override. * This is provided as a weak method so applications can override.
* Default behaviour is to get the target's default interface, if * Default behaviour is to get the target's default interface, if
* any. * any.
* *
* @return pointer to interface, if any * @return pointer to interface, if any.
*/ */
static WiFiInterface *get_default_instance(); static WiFiInterface *get_default_instance();
/** Set the WiFi network credentials /** Set the Wi-Fi network credentials.
* *
* @param ssid Name of the network to connect to * @param ssid Name of the network to connect to.
* @param pass Security passphrase to connect to the network * @param pass Security passphrase to connect to the network.
* @param security Type of encryption for connection * @param security Type of encryption for connection
* (defaults to NSAPI_SECURITY_NONE) * (defaults to NSAPI_SECURITY_NONE).
* @return 0 on success, or error code on failure * @return NSAPI_ERROR_OK on success, or error code on failure.
*/ */
virtual nsapi_error_t set_credentials(const char *ssid, const char *pass, virtual nsapi_error_t set_credentials(const char *ssid, const char *pass,
nsapi_security_t security = NSAPI_SECURITY_NONE) = 0; nsapi_security_t security = NSAPI_SECURITY_NONE) = 0;
/** Set the WiFi network channel /** Set the Wi-Fi network channel.
* *
* @param channel Channel on which the connection is to be made, or 0 for any (Default: 0) * @param channel Channel on which the connection is to be made, or 0 for any (Default: 0).
* @return 0 on success, or error code on failure * @return NSAPI_ERROR_OK on success, or error code on failure.
*/ */
virtual nsapi_error_t set_channel(uint8_t channel) = 0; virtual nsapi_error_t set_channel(uint8_t channel) = 0;
/** Gets the current radio signal strength for active connection /** Get the current radio signal strength for active connection.
* *
* @return Connection strength in dBm (negative value), * @return Connection strength in dBm (negative value),
* or 0 if measurement impossible * or 0 if measurement impossible.
*/ */
virtual int8_t get_rssi() = 0; virtual int8_t get_rssi() = 0;
/** Start the interface /** Attempt to connect to a Wi-Fi network.
* *
* 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 ssid Name of the network to connect to * @param security Type of encryption for connection (Default: NSAPI_SECURITY_NONE).
* @param pass Security passphrase to connect to the network * @param channel Channel on which the connection is to be made, or 0 for any (Default: 0).
* @param security Type of encryption for connection (Default: NSAPI_SECURITY_NONE) * @return NSAPI_ERROR_OK on success, or error code on failure.
* @param channel Channel on which the connection is to be made, or 0 for any (Default: 0)
* @return 0 on success, or error code on failure
*/ */
virtual nsapi_error_t connect(const char *ssid, const char *pass, virtual nsapi_error_t connect(const char *ssid, const char *pass,
nsapi_security_t security = NSAPI_SECURITY_NONE, uint8_t channel = 0) = 0; nsapi_security_t security = NSAPI_SECURITY_NONE, uint8_t channel = 0) = 0;
/** Start the interface /** Attempt to connect to a Wi-Fi network. Requires ssid and passphrase to be set.
*
* Attempts to connect to a WiFi network. Requires ssid and passphrase to be set.
* If passphrase is invalid, NSAPI_ERROR_AUTH_ERROR is returned. * If passphrase is invalid, NSAPI_ERROR_AUTH_ERROR is returned.
* *
* @return 0 on success, negative error code on failure * @return NSAPI_ERROR_OK on success, negative error code on failure.
*/ */
virtual nsapi_error_t connect() = 0; virtual nsapi_error_t connect() = 0;
/** Stop the interface /** Stop the interface.
* *
* @return 0 on success, or error code on failure * @return NSAPI_ERROR_OK on success, or error code on failure.
*/ */
virtual nsapi_error_t disconnect() = 0; virtual nsapi_error_t disconnect() = 0;
/** Scan for available networks /** Scan for available networks.
* *
* This function will block. If the @a count is 0, function will only return count of available networks, so that * This function will block. If the count is 0, function will only return count of available networks, so that
* user can allocated necessary memory. If the \p count is grater than 0 and the a \p res is not NULL it'll be populated * user can allocated necessary memory. If the count is grater than 0 and the a \p res is not NULL it'll be populated
* with discovered networks up to value of \p count. * with discovered networks up to value of count.
* *
* @param res Pointer to allocated array to store discovered AP * @param res Pointer to allocated array to store discovered APs.
* @param count Size of allocated @a res array, or 0 to only count available AP * @param count Size of allocated res array, or 0 to only count available APs.
* @return Number of entries in \p count, or if \p count was 0 number of available networks, * @return Number of entries in res, or if count was 0 number of available networks.
* negative on error see @a nsapi_error * Negative on error (@see nsapi_types.h for nsapi_error).
*/ */
virtual nsapi_size_or_error_t scan(WiFiAccessPoint *res, nsapi_size_t count) = 0; virtual nsapi_size_or_error_t scan(WiFiAccessPoint *res, nsapi_size_t count) = 0;
/** @copydoc NetworkInterface::wifiInterface
*/
virtual WiFiInterface *wifiInterface() virtual WiFiInterface *wifiInterface()
{ {
return this; return this;
} }
#if !defined(DOXYGEN_ONLY)
protected: protected:
/** Get the target's default WiFi interface. /** Get the target's default Wi-Fi interface.
* *
* This is provided as a weak method so targets can override. The * This is provided as a weak method so targets can override. The
* default implementation returns NULL. * default implementation returns NULL.
* *
* @return pointer to interface, if any * @return pointer to interface, if any.
*/ */
static WiFiInterface *get_target_default_instance(); static WiFiInterface *get_target_default_instance();
#endif //!defined(DOXYGEN_ONLY)
}; };
#endif #endif

8
features/netsocket/nsapi_types.h
View File

@ -351,7 +351,7 @@ typedef struct nsapi_stack_api {
*/ */
nsapi_error_t (*add_dns_server)(nsapi_stack_t *stack, nsapi_addr_t addr); nsapi_error_t (*add_dns_server)(nsapi_stack_t *stack, nsapi_addr_t addr);
/* Set stack-specific stack options /** Set stack-specific stack options
* *
* The setstackopt allow an application to pass stack-specific hints * The setstackopt allow an application to pass stack-specific hints
* to the underlying stack. For unsupported options, * to the underlying stack. For unsupported options,
@ -367,7 +367,7 @@ typedef struct nsapi_stack_api {
nsapi_error_t (*setstackopt)(nsapi_stack_t *stack, int level, nsapi_error_t (*setstackopt)(nsapi_stack_t *stack, int level,
int optname, const void *optval, unsigned optlen); int optname, const void *optval, unsigned optlen);
/* Get stack-specific stack options /** Get stack-specific stack options
* *
* The getstackopt allow an application to retrieve stack-specific hints * The getstackopt allow an application to retrieve stack-specific hints
* from the underlying stack. For unsupported options, * from the underlying stack. For unsupported options,
@ -567,7 +567,7 @@ typedef struct nsapi_stack_api {
void (*socket_attach)(nsapi_stack_t *stack, nsapi_socket_t socket, void (*socket_attach)(nsapi_stack_t *stack, nsapi_socket_t socket,
void (*callback)(void *), void *data); void (*callback)(void *), void *data);
/* Set stack-specific socket options /** Set stack-specific socket options
* *
* The setsockopt allow an application to pass stack-specific hints * The setsockopt allow an application to pass stack-specific hints
* to the underlying stack. For unsupported options, * to the underlying stack. For unsupported options,
@ -584,7 +584,7 @@ typedef struct nsapi_stack_api {
nsapi_error_t (*setsockopt)(nsapi_stack_t *stack, nsapi_socket_t socket, int level, nsapi_error_t (*setsockopt)(nsapi_stack_t *stack, nsapi_socket_t socket, int level,
int optname, const void *optval, unsigned optlen); int optname, const void *optval, unsigned optlen);
/* Get stack-specific socket options /** Get stack-specific socket options
* *
* The getstackopt allow an application to retrieve stack-specific hints * The getstackopt allow an application to retrieve stack-specific hints
* from the underlying stack. For unsupported options, * from the underlying stack. For unsupported options,