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;
/** Set socket options
*
* 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
/** @copydoc NetworkStack::setsockopt
*/
virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
int optname, const void *optval, unsigned optlen);
/** Get socket options
*
* 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
/** @copydoc NetworkStack::getsockopt
*/
virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname,
void *optval, unsigned *optlen);

85
features/netsocket/CellularBase.h
View File

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

58
features/netsocket/DNS.h
View File

@ -20,7 +20,7 @@
class DNS {
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
* 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
* will be resolve using a UDP socket on the stack.
*
* @param host Hostname to resolve
* @param address Destination for the host SocketAddress
* @param host Hostname to resolve.
* @param address Pointer to a SocketAddress to store the result.
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates
* version is chosen by the stack (defaults to NSAPI_UNSPEC)
* @return 0 on success, negative error code on failure
* version is chosen by the stack (defaults to NSAPI_UNSPEC).
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t gethostbyname(const char *host,
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
* 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
* calls or blocking operations.
*
* @param status 0 on success, negative error code on failure
* @param address On success, destination for the host SocketAddress
* @param result NSAPI_ERROR_OK on success, negative error code on failure.
* @param address On success, destination for the host SocketAddress.
*/
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
* hostname is an IP address, no network transactions will be performed.
*
* 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.
* If this function returns failure, callback will not be called. In case result
* is success (IP address was found from DNS cache), callback will be called
* before function returns.
* The call is non-blocking. The result of the DNS operation is returned by the callback.
* If this function returns failure, the callback will not be called. If it is successful,
* (the IP address was found from the DNS cache), the callback will be called
* before the function returns.
*
* @param host Hostname to resolve
* @param callback Callback that is called for result
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates
* version is chosen by the stack (defaults to NSAPI_UNSPEC)
* @return 0 on immediate success,
* @param host Hostname to resolve.
* @param callback Callback that is called to return the result.
* @param version IP version of address to resolve. NSAPI_UNSPEC indicates that the
* version is chosen by the stack (defaults to NSAPI_UNSPEC).
* @return NSAPI_ERROR_OK on immediate success,
* negative error code on immediate failure or
* a positive unique id that represents the hostname translation operation
* and can be passed to cancel
* a positive unique ID that represents the hostname translation operation
* and can be passed to cancel.
*/
virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback,
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
* @return 0 on success, negative error code on failure
* @param id Unique ID of the hostname translation operation returned by gethostbyname_async.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
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
* @return 0 on success, negative error code on failure
* @param address DNS server host address.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
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"
/** EthInterface class
*
* Common interface that is shared between ethernet hardware.
/** Common interface that is shared between Ethernet hardware.
*/
class EthInterface : public virtual NetworkInterface {
public:
/** @copydoc NetworkInterface::ethInterface
*/
virtual EthInterface *ethInterface()
{
return this;
@ -41,10 +41,11 @@ public:
* Default behaviour is to get the target's default interface, if
* any.
*
* @return pointer to interface, if any
* @return Pointer to interface, if one exists.
*/
static EthInterface *get_default_instance();
#if !defined(DOXYGEN_ONLY)
protected:
/** Get the target's default Ethernet interface.
@ -53,9 +54,10 @@ protected:
* default implementation will invoke EthernetInterface with the
* 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();
#endif //!defined(DOXYGEN_ONLY)
};

9
features/netsocket/EthernetInterface.h
View File

@ -21,12 +21,11 @@
#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 {
public:
/** Create an EMAC-based ethernet interface.
/** Create an EMAC-based Ethernet interface.
*
* The default arguments obtain the default EMAC, which will be target-
* 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
* work is done until the first call to connect().
*
* @param emac Reference to EMAC to use
* @param stack Reference to onboard-network stack to use
* @param emac Reference to EMAC to use.
* @param stack Reference to onboard-network stack to use.
*/
EthernetInterface(EMAC &emac = EMAC::get_default_instance(),
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);
/** Bind the socket to a specific address and port on which to receive
* 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).
/** @copydoc Socket::bind
*/
virtual nsapi_error_t bind(const SocketAddress &address);
/** Set blocking or nonblocking mode of the socket.
*
* 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.
/** @copydoc Socket::set_blocking
*/
virtual void set_blocking(bool blocking);
/** Set timeout on blocking socket operations.
*
* 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.
/** @copydoc Socket::set_timeout
*/
virtual void set_timeout(int timeout);
/** Pass stack-specific options to the underlying stack using 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 Option value.
* @param optlen Length of the option value.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
/** @copydoc Socket::setsockopt
*/
virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen);
/** Retrieve stack-specific options from the underlying stack using
* 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).
/** @copydoc Socket::getsockopt
*/
virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen);
/** Register a callback on state change of the socket.
*
* 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.
/** @copydoc Socket::sigio
*/
virtual void sigio(mbed::Callback<void()> func);

13
features/netsocket/MeshInterface.h
View File

@ -23,13 +23,12 @@
#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 {
public:
/** @copydoc NetworkInterface::meshInterface
*/
virtual MeshInterface *meshInterface()
{
return this;
@ -41,10 +40,11 @@ public:
* Default behaviour is to get the target's default interface, if
* any.
*
* @return pointer to interface, if any
* @return pointer to interface, if any.
*/
static MeshInterface *get_default_instance();
#if !defined(DOXYGEN_ONLY)
protected:
/** Get the target's default Mesh interface.
@ -53,9 +53,10 @@ protected:
* default implementation will invoke LoWPANNDInterface or ThreadInterface
* with the default NanostackRfPhy.
*
* @return pointer to interface, if any
* @return pointer to interface, if any.
*/
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 EMACInterface;
/** NetworkInterface class
/** Common interface that is shared between network devices.
*
* Common interface that is shared between network devices
* @addtogroup netsocket
*/
class NetworkInterface: public DNS {
@ -41,13 +40,14 @@ public:
virtual ~NetworkInterface() {};
/** Return the default network interface
/** Return the default network interface.
*
* Returns the default network interface, as determined by JSON option
* target.network-default-interface-type or other overrides.
*
* The type of the interface returned can be tested via the ethInterface()
* etc downcasts.
* The type of the interface returned can be tested by calling ethInterface(),
* wifiInterface(), meshInterface(), cellularBase(), emacInterface() and checking
* for NULL pointers.
*
* The default behaviour is to return the default interface for the
* interface type specified by target.network-default-interface-type. Targets
@ -79,75 +79,72 @@ public:
*/
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
* may not be provided if the underlying network interface does not
* provide a MAC address
* may be not provided if the underlying network interface does not
* provide a 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();
/** Get the local IP address
/** Get 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();
/** Get the local network mask
/** Get 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();
/** Get the local gateway
/** Get 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();
/** Set a static IP address
*
* Configures this network interface to use a static IP address.
/** Configure this network interface to use a static IP address.
* Implicitly disables DHCP, which can be enabled in set_dhcp.
* Requires that the network is disconnected.
*
* @param ip_address Null-terminated representation of the local IP address
* @param netmask Null-terminated representation of the local network mask
* @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);
/** 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
* a static IP address has been assigned. Requires that the network is
* disconnected.
* Enabled by default unless a static IP address has been assigned. Requires
* that the network is disconnected.
*
* @param dhcp True to enable DHCP
* @return 0 on success, negative error code on failure
* @param dhcp True to enable DHCP.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
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;
/** 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;
/** 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
* 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
* will be resolve using a UDP socket on the stack.
*
* @param host Hostname to resolve
* @param address Destination for the host SocketAddress
* @param host Hostname to resolve.
* @param address Pointer to a SocketAddress to store the result.
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates
* version is chosen by the stack (defaults to NSAPI_UNSPEC)
* @return 0 on success, negative error code on failure
* version is chosen by the stack (defaults to NSAPI_UNSPEC).
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t gethostbyname(const char *host,
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 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
* should not make calls to network operations due to stack size limitations.
* The callback should not perform expensive operations such as socket recv/send
* calls or blocking operations.
*
* @param status 0 on success, negative error code on failure
* @param address On success, destination for the host SocketAddress
* @param result NSAPI_ERROR_OK on success, negative error code on failure.
* @param address On success, destination for the host SocketAddress.
*/
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.
*
* 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
* before function returns.
*
* @param host Hostname to resolve
* @param callback Callback that is called for result
* @param host Hostname to resolve.
* @param callback Callback that is called for result.
* @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,
* negative error code on immediate failure or
* 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,
nsapi_version_t version = NSAPI_UNSPEC);
/** Cancels asynchronous hostname translation
/** Cancel asynchronous hostname translation.
*
* When translation is cancelled, callback will not be called.
*
* @param id Unique id of the hostname translation operation
* @return 0 on success, negative error code on failure
* @param id Unique id of the hostname translation operation (returned
* by gethostbyname_async)
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t gethostbyname_async_cancel(int id);
/** Add a domain name server to list of servers to query
*
* @param address Destination for the host address
* @return 0 on success, negative error code on failure
* @param address Address for the dns host.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
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
* on the network. The parameters on the callback are the event type and
* 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);
/** 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;
/** 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
* @return 0 on success, negative error code on failure
* @param blocking Use true to make connect() blocking.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
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()
{
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()
{
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()
{
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()
{
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()
{
return 0;
}
#if !defined(DOXYGEN_ONLY)
protected:
friend class InternetSocket;
friend class UDPSocket;
@ -318,6 +328,7 @@ protected:
* performs the search described by get_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.
*
* @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
* 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,
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
* 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
*/
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.
*
* @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);
/** Add a domain name server to list of servers to query
*
* @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);
@ -125,7 +125,7 @@ public:
*
* @param index Index of the DNS server, starts from zero
* @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);
@ -142,7 +142,7 @@ public:
* @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
* @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);
@ -156,7 +156,7 @@ public:
* @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
* @return NSAPI_ERROR_OK on success, negative error code on failure
*/
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 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;
@ -192,7 +192,7 @@ protected:
* with the socket.
*
* @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;
@ -203,7 +203,7 @@ protected:
*
* @param handle Socket handle
* @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;
@ -215,7 +215,7 @@ protected:
* @param handle Socket handle
* @param backlog Number of pending connections that can be queued
* 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;
@ -226,7 +226,7 @@ protected:
*
* @param handle Socket handle
* @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;
@ -246,7 +246,7 @@ protected:
* @param server Socket handle to server to accept from
* @param handle Destination for a handle to the newly created socket
* @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,
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;
/* Set stack-specific socket options
/** Set stack-specific socket options.
*
* 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
* @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 NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
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
* from the underlying stack. For unsupported options,
* NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
*
* @param handle Socket handle
* @param level Stack-specific protocol level
* @param optname Stack-specific option identifier
* @param optval Destination for option value
* @param optlen Length of the option value
* @return 0 on success, negative error code on failure
* @param handle Socket handle.
* @param level Stack-specific protocol level.
* @param optname Stack-specific option identifier.
* @param optval Destination for option value.
* @param optlen Length of the option value.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level,
int optname, void *optval, unsigned *optlen);
@ -397,7 +397,7 @@ private:
*
* @param delay Delay in milliseconds
* @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);
};

33
features/netsocket/Socket.h
View File

@ -38,7 +38,7 @@ public:
* Closes any open connection and deallocates any memory associated
* 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;
@ -54,7 +54,7 @@ public:
* object have to be in the address parameter.
*
* @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;
@ -142,10 +142,11 @@ public:
/** 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
* @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;
@ -190,7 +191,7 @@ public:
* such functionality. The exact timing of when the registered function
* 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;
@ -203,11 +204,11 @@ public:
* 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
* @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 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;
@ -220,11 +221,11 @@ public:
* 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
* @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 NSAPI_ERROR_OK on success, negative error code on failure.
*/
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
* 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;
};

75
features/netsocket/WiFiInterface.h
View File

@ -22,104 +22,103 @@
#include "netsocket/NetworkInterface.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
*/
class WiFiInterface: public virtual NetworkInterface {
public:
/** Get the default WiFi interface.
/** Get the default Wi-Fi interface.
*
* This is provided as a weak method so applications can override.
* Default behaviour is to get the target's default interface, if
* any.
*
* @return pointer to interface, if any
* @return pointer to interface, if any.
*/
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 pass Security passphrase to connect to the 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
* (defaults to NSAPI_SECURITY_NONE)
* @return 0 on success, or error code on failure
* (defaults to NSAPI_SECURITY_NONE).
* @return NSAPI_ERROR_OK on success, or error code on failure.
*/
virtual nsapi_error_t set_credentials(const char *ssid, const char *pass,
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)
* @return 0 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 NSAPI_ERROR_OK on success, or error code on failure.
*/
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),
* or 0 if measurement impossible
* or 0 if measurement impossible.
*/
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 security Type of encryption for connection (Default: NSAPI_SECURITY_NONE)
* @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
* @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 (Default: NSAPI_SECURITY_NONE).
* @param channel Channel on which the connection is to be made, or 0 for any (Default: 0).
* @return NSAPI_ERROR_OK 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, uint8_t channel = 0) = 0;
/** Start the interface
*
* Attempts to connect to a WiFi network. Requires ssid and passphrase to be set.
/** Attempt to connect to a Wi-Fi network. Requires ssid and passphrase to be set.
* 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;
/** 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;
/** 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
* 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
* with discovered networks up to value of \p count.
* 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 count is grater than 0 and the a \p res is not NULL it'll be populated
* with discovered networks up to value of count.
*
* @param res Pointer to allocated array to store discovered AP
* @param count Size of allocated @a res array, or 0 to only count available AP
* @return Number of entries in \p count, or if \p count was 0 number of available networks,
* negative on error see @a nsapi_error
* @param res Pointer to allocated array to store discovered APs.
* @param count Size of allocated res array, or 0 to only count available APs.
* @return Number of entries in res, or if count was 0 number of available networks.
* Negative on error (@see nsapi_types.h for nsapi_error).
*/
virtual nsapi_size_or_error_t scan(WiFiAccessPoint *res, nsapi_size_t count) = 0;
/** @copydoc NetworkInterface::wifiInterface
*/
virtual WiFiInterface *wifiInterface()
{
return this;
}
#if !defined(DOXYGEN_ONLY)
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
* default implementation returns NULL.
*
* @return pointer to interface, if any
* @return pointer to interface, if any.
*/
static WiFiInterface *get_target_default_instance();
#endif //!defined(DOXYGEN_ONLY)
};
#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);
/* Set stack-specific stack options
/** Set stack-specific stack options
*
* The setstackopt allow an application to pass stack-specific hints
* 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,
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
* 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 (*callback)(void *), void *data);
/* Set stack-specific socket options
/** Set stack-specific socket options
*
* The setsockopt allow an application to pass stack-specific hints
* 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,
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
* from the underlying stack. For unsupported options,