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.

Author: Seppo Takalo

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;
     }
 

features/netsocket/NetworkInterface.h

@@ -133,29 +133,39 @@ class NetworkInterface: public DNS {
      */
     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 @@ class NetworkInterface: public DNS {
      */
     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);
 

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 */
 };