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

Clarify asyncronous Networkinterface::connect() and disconnect() API 

This is slight API change, as a new return code is introduced.
Intention is to properly support asyncronous drivers that might
not be able to get new operation into execution, therefore they
need to return BUSY.
pull/9414/head
Seppo Takalo 2019-01-17 15:52:13 +02:00
parent 1a8844e8ed
commit 6c5b845517
3 changed files with 33 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
features/lwipstack/LWIPInterface.cpp
View File

@ -503,7 +503,7 @@ nsapi_error_t LWIP::Interface::bringup(bool dhcp, const char *ip, const char *ne
if (connected == NSAPI_STATUS_GLOBAL_UP) {
return NSAPI_ERROR_IS_CONNECTED;
} else if (connected == NSAPI_STATUS_CONNECTING) {
return NSAPI_ERROR_ALREADY;
return NSAPI_ERROR_BUSY;
}
connected = NSAPI_STATUS_CONNECTING;
@ -595,7 +595,6 @@ nsapi_error_t LWIP::Interface::bringup(bool dhcp, const char *ip, const char *ne
if (!blocking) {
// Done enough - as addresses are acquired, there will be
// connected callbacks.
// XXX shouldn't this be NSAPI_ERROR_IN_PROGRESS if in CONNECTING state?
return NSAPI_ERROR_OK;
}

47
features/netsocket/NetworkInterface.h
View File

@ -133,29 +133,39 @@ public:
*/
virtual nsapi_error_t set_dhcp(bool dhcp);
/** Start the interface.
/** Connect to a network.
*
* This blocks until connection is established, but asynchronous operation can be enabled
* by calling NetworkInterface::set_blocking(false).
* This blocks until connection is established, but asynchronous operation can be enabled
* by calling NetworkInterface::set_blocking(false).
*
* In asynchronous mode this starts the connection sequence and returns immediately.
* Status of the connection can then checked from NetworkInterface::get_connection_status()
* or from status callbacks.
* In asynchronous mode this starts the connection sequence and returns immediately.
* Status of the connection can then checked from NetworkInterface::get_connection_status()
* or from status callbacks.
*
* @return NSAPI_ERROR_OK on success, or if asynchronous operation started.
* @return NSAPI_ERROR_ALREADY if asynchronous connect operation already ongoing.
* @return NSAPI_ERROR_IS_CONNECTED if interface is already connected.
* @return negative error code on failure.
* NetworkInterface internally handles reconnections until disconnect() is called.
*
* @return NSAPI_ERROR_OK if connection established in blocking mode.
* @return NSAPI_ERROR_OK if asynchronous operation started.
* @return NSAPI_ERROR_BUSY if asynchronous operation cannot be started.
Implementation guarantees event generation, which can be used as an
trigger to reissue the rejected request.
* @return NSAPI_ERROR_IS_CONNECTED if already connected.
* @return negative error code on failure.
*/
virtual nsapi_error_t connect() = 0;
/** Stop the interface.
/** Disconnect from the network
*
* This blocks until interface is disconnected, unless interface is set to
* asynchronous (non-blocking) mode by calling NetworkInterface::set_blocking(false).
*
* @return NSAPI_ERROR_OK on success, or if asynchronous operation started.
@ @return negative error code on failure.
* @return NSAPI_ERROR_OK on successfully disconnected in blocking mode.
* @return NSAPI_ERROR_OK if asynchronous operation started.
* @return NSAPI_ERROR_BUSY if asynchronous operation cannot be started.
Implementation guarantees event generation, which can be used as an
trigger to reissue the rejected request.
* @return NSAPI_ERROR_NO_CONNECTION if already disconnected.
* @return negative error code on failure.
*/
virtual nsapi_error_t disconnect() = 0;
@ -249,10 +259,15 @@ public:
*/
virtual nsapi_connection_status_t get_connection_status() const;
/** Set blocking status of connect() which by default should be blocking.
/** Set asynchronous operation of connect() and disconnect() calls.
*
* @param blocking Use true to make connect() blocking.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
* By default, interfaces are in synchronous mode which means that
* connect() or disconnect() blocks until it reach the target state or requested operation fails.
*
* @param blocking Use true to set NetworkInterface in asynchronous mode.
* @return NSAPI_ERROR_OK on success
* @return NSAPI_ERROR_UNSUPPORTED if driver does not support asynchronous mode.
* @return negative error code on failure.
*/
virtual nsapi_error_t set_blocking(bool blocking);

1
features/netsocket/nsapi_types.h
View File

@ -55,6 +55,7 @@ enum nsapi_error {
NSAPI_ERROR_CONNECTION_TIMEOUT = -3017, /*!< connection timed out */
NSAPI_ERROR_ADDRESS_IN_USE = -3018, /*!< Address already in use */
NSAPI_ERROR_TIMEOUT = -3019, /*!< operation timed out */
NSAPI_ERROR_BUSY = -3020, /*!< device is busy and cannot accept new operation */
};