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

Merge pull request #9414 from SeppoTakalo/ONME-4013 

Clarify asynchronous Networkinterface::connect() and disconnect() API
pull/9572/head
Martin Kojtal 2019-01-31 11:30:29 +01:00 committed by GitHub
parent dbc3c6250b 6c5b845517
commit a12ab30f98
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
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) { if (connected == NSAPI_STATUS_GLOBAL_UP) {
return NSAPI_ERROR_IS_CONNECTED; return NSAPI_ERROR_IS_CONNECTED;
} else if (connected == NSAPI_STATUS_CONNECTING) { } else if (connected == NSAPI_STATUS_CONNECTING) {
return NSAPI_ERROR_ALREADY; return NSAPI_ERROR_BUSY;
} }
connected = NSAPI_STATUS_CONNECTING; connected = NSAPI_STATUS_CONNECTING;
@ -595,7 +595,6 @@ nsapi_error_t LWIP::Interface::bringup(bool dhcp, const char *ip, const char *ne
if (!blocking) { if (!blocking) {
// Done enough - as addresses are acquired, there will be // Done enough - as addresses are acquired, there will be
// connected callbacks. // connected callbacks.
// XXX shouldn't this be NSAPI_ERROR_IN_PROGRESS if in CONNECTING state?
return NSAPI_ERROR_OK; return NSAPI_ERROR_OK;
} }

35
features/netsocket/NetworkInterface.h
View File

@ -137,7 +137,7 @@ public:
*/ */
virtual nsapi_error_t set_dhcp(bool dhcp); 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 * This blocks until connection is established, but asynchronous operation can be enabled
* by calling NetworkInterface::set_blocking(false). * by calling NetworkInterface::set_blocking(false).
@ -146,20 +146,30 @@ public:
* Status of the connection can then checked from NetworkInterface::get_connection_status() * Status of the connection can then checked from NetworkInterface::get_connection_status()
* or from status callbacks. * or from status callbacks.
* *
* @return NSAPI_ERROR_OK on success, or if asynchronous operation started. * NetworkInterface internally handles reconnections until disconnect() is called.
* @return NSAPI_ERROR_ALREADY if asynchronous connect operation already ongoing. *
* @return NSAPI_ERROR_IS_CONNECTED if interface is already connected. * @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. * @return negative error code on failure.
*/ */
virtual nsapi_error_t connect() = 0; virtual nsapi_error_t connect() = 0;
/** Stop the interface. /** Disconnect from the network
* *
* This blocks until interface is disconnected, unless interface is set to * This blocks until interface is disconnected, unless interface is set to
* asynchronous (non-blocking) mode by calling NetworkInterface::set_blocking(false). * asynchronous (non-blocking) mode by calling NetworkInterface::set_blocking(false).
* *
* @return NSAPI_ERROR_OK on success, or if asynchronous operation started. * @return NSAPI_ERROR_OK on successfully disconnected in blocking mode.
@ @return negative error code on failure. * @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; virtual nsapi_error_t disconnect() = 0;
@ -253,10 +263,15 @@ public:
*/ */
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 asynchronous operation of connect() and disconnect() calls.
* *
* @param blocking Use true to make connect() blocking. * By default, interfaces are in synchronous mode which means that
* @return NSAPI_ERROR_OK on success, negative error code on failure. * 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); 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_CONNECTION_TIMEOUT = -3017, /*!< connection timed out */
NSAPI_ERROR_ADDRESS_IN_USE = -3018, /*!< Address already in use */ NSAPI_ERROR_ADDRESS_IN_USE = -3018, /*!< Address already in use */
NSAPI_ERROR_TIMEOUT = -3019, /*!< operation timed out */ NSAPI_ERROR_TIMEOUT = -3019, /*!< operation timed out */
NSAPI_ERROR_BUSY = -3020, /*!< device is busy and cannot accept new operation */
}; };