From 6c5b8455174ca3180663fef4a56905073f826d05 Mon Sep 17 00:00:00 2001 From: Seppo Takalo Date: Thu, 17 Jan 2019 15:52:13 +0200 Subject: [PATCH] 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. --- features/lwipstack/LWIPInterface.cpp | 3 +- features/netsocket/NetworkInterface.h | 47 ++++++++++++++++++--------- features/netsocket/nsapi_types.h | 1 + 3 files changed, 33 insertions(+), 18 deletions(-) diff --git a/features/lwipstack/LWIPInterface.cpp b/features/lwipstack/LWIPInterface.cpp index 9bbfaa82fd..d4adde9b31 100644 --- a/features/lwipstack/LWIPInterface.cpp +++ b/features/lwipstack/LWIPInterface.cpp @@ -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; } diff --git a/features/netsocket/NetworkInterface.h b/features/netsocket/NetworkInterface.h index c84fff2504..f2360222c1 100644 --- a/features/netsocket/NetworkInterface.h +++ b/features/netsocket/NetworkInterface.h @@ -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); diff --git a/features/netsocket/nsapi_types.h b/features/netsocket/nsapi_types.h index 21f91d01dc..ce6c19ddec 100644 --- a/features/netsocket/nsapi_types.h +++ b/features/netsocket/nsapi_types.h @@ -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 */ };