Cellular: retire CellularBase class

It was decided to retire CellularBase class which served as a pure
virtual interface class from which Cellular network stack
implementations would get inherited. However, the current view is that
we may be the only user of it so we could retire CellularBase.

Author: Jari Poyhonen

features/cellular/framework/API/CellularContext.h

@@ -17,7 +17,7 @@
 #ifndef _CELLULARCONTEXT_H_
 #define _CELLULARCONTEXT_H_
 
-#include "CellularBase.h"
+#include "CellularInterface.h"
 #include "CellularDevice.h"
 #include "ControlPlane_netif.h"
 
@@ -36,8 +36,8 @@ typedef enum pdp_type {
  * @{
  */
 
-/// CellularContext is CellularBase/NetworkInterface with extensions for cellular connectivity
-class CellularContext : public CellularBase {
+/// CellularContext is CellularInterface/NetworkInterface with extensions for cellular connectivity
+class CellularContext : public CellularInterface {
 
 public:
 
@@ -135,7 +135,7 @@ class CellularContext : public CellularBase {
     virtual nsapi_error_t connect() = 0;
     virtual nsapi_error_t disconnect() = 0;
 
-    // from CellularBase
+    // from CellularInterface
     virtual void set_plmn(const char *plmn) = 0;
     virtual void set_sim_pin(const char *sim_pin) = 0;
     virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0, const char *uname = 0,

features/cellular/framework/device/CellularContext.cpp

@@ -16,7 +16,7 @@
  */
 #include "CellularContext.h"
 
-MBED_WEAK CellularBase *CellularBase::get_target_default_instance()
+MBED_WEAK CellularInterface *CellularInterface::get_target_default_instance()
 {
     return mbed::CellularContext::get_default_instance();
 }

features/netsocket/CellularBase.h

@@ -22,134 +22,14 @@
 #ifndef CELLULAR_BASE_H
 #define CELLULAR_BASE_H
 
-#include "netsocket/NetworkInterface.h"
-
-/** Common interface that is shared between cellular interfaces.
+/**
+ * This class is deprecated and will be removed altogether after expiration of
+ * deprecation notice.
  */
-class CellularBase: public NetworkInterface {
-
-public:
-    /** Get the default cellular interface.
-     *
-     * This is provided as a weak method so applications can override.
-     * Default behavior is to get the target's default interface, if
-     * any.
-     *
-     * @return pointer to interface, if any.
-     */
-    static CellularBase *get_default_instance();
-
-    /** Set the cellular network credentials.
-     *
-     *  Please check documentation of connect() for default behavior of APN settings.
-     *
-     *  @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 plmn. PLMN controls to what network device registers.
-     *
-     *  @param plmn     user to force what network to register.
-     */
-    virtual void set_plmn(const char *plmn) = 0;
-
-    /** Set the PIN code for SIM card.
-     *
-     *  @param sim_pin      PIN for the SIM card.
-     */
-    virtual void set_sim_pin(const char *sim_pin) = 0;
-
-    /** Attempt to connect to a cellular network with a PIN and credentials.
-     *
-     *  @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;
-
-    /** Attempt to connect to a cellular network.
-     *
-     *  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.
-     */
-    virtual nsapi_error_t connect() = 0;
-
-    /** Stop the interface.
-     *
-     *  @return         NSAPI_ERROR_OK on success, or error code on failure.
-     */
-    virtual nsapi_error_t disconnect() = 0;
-
-    /** Check if the connection is currently established.
-     *
-     * @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.
-     *
-     *  @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.
-     *
-     *  @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.
-     *
-     *  @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.
-     *
-     * This is provided as a weak method so targets can override. The
-     * default implementation configures and returns the OnBoardModemInterface,
-     * if available.
-     *
-     * @return Pointer to interface, if any.
-     */
-    static CellularBase *get_target_default_instance();
-
-#endif //!defined(DOXYGEN_ONLY)
+#include "CellularInterface.h"
 
-public:
-    /** Set default parameters on a cellular interface.
-     *
-     * A cellular interface instantiated directly or using
-     * CellularBase::get_default_instance() is initially unconfigured.
-     * This call can be used to set the default parameters that would
-     * have been set if the interface had been requested using
-     * NetworkInterface::get_default_instance() (see nsapi JSON
-     * configuration).
-     */
-    virtual void set_default_parameters();
-};
+MBED_DEPRECATED_SINCE("mbed-os-5.12", "Migrated to CellularInterface")
+typedef CellularInterface CellularBase;
 
 #endif //CELLULAR_BASE_H
 

features/netsocket/CellularInterface.h

@@ -0,0 +1,161 @@
+/* Copyright (c) 2019 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef CELLULAR_INTERFACE_H_
+#define CELLULAR_INTERFACE_H_
+
+#include "netsocket/NetworkInterface.h"
+
+/**
+ * @addtogroup cellular
+ * @{
+ */
+
+/** Common interface that is shared between cellular interfaces.
+ */
+class CellularInterface: public NetworkInterface {
+
+public:
+    /** Get the default cellular interface.
+     *
+     * This is provided as a weak method so applications can override.
+     * Default behavior is to get the target's default interface, if
+     * any.
+     *
+     * @return pointer to interface, if any.
+     */
+    static CellularInterface *get_default_instance();
+
+    /** Set the cellular network credentials.
+     *
+     *  Please check documentation of connect() for default behavior of APN settings.
+     *
+     *  @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 plmn. PLMN controls to what network device registers.
+     *
+     *  @param plmn     user to force what network to register.
+     */
+    virtual void set_plmn(const char *plmn) = 0;
+
+    /** Set the PIN code for SIM card.
+     *
+     *  @param sim_pin      PIN for the SIM card.
+     */
+    virtual void set_sim_pin(const char *sim_pin) = 0;
+
+    /** Attempt to connect to a cellular network with a PIN and credentials.
+     *
+     *  @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;
+
+    /** Attempt to connect to a cellular network.
+     *
+     *  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.
+     */
+    virtual nsapi_error_t connect() = 0;
+
+    /** Stop the interface.
+     *
+     *  @return         NSAPI_ERROR_OK on success, or error code on failure.
+     */
+    virtual nsapi_error_t disconnect() = 0;
+
+    /** Check if the connection is currently established.
+     *
+     * @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.
+     *
+     *  @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.
+     *
+     *  @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.
+     *
+     *  @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
+     */
+    MBED_DEPRECATED_SINCE("mbed-os-5.12", "Migrated to CellularInterface")
+    virtual CellularInterface *cellularBase()
+    {
+        return this;
+    }
+
+    /** @copydoc NetworkInterface::cellularInterface
+     */
+    virtual CellularInterface *cellularInterface()
+    {
+        return this;
+    }
+
+#if !defined(DOXYGEN_ONLY)
+
+protected:
+    /** 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,
+     * if available.
+     *
+     * @return Pointer to interface, if any.
+     */
+    static CellularInterface *get_target_default_instance();
+
+#endif //!defined(DOXYGEN_ONLY)
+
+public:
+    /** Set default parameters on a cellular interface.
+     *
+     * A cellular interface instantiated directly or using
+     * CellularInterface::get_default_instance() is initially unconfigured.
+     * This call can be used to set the default parameters that would
+     * have been set if the interface had been requested using
+     * NetworkInterface::get_default_instance() (see nsapi JSON
+     * configuration).
+     */
+    virtual void set_default_parameters();
+};
+
+#endif // CELLULAR_INTERFACE_H_

features/netsocket/NetworkInterface.h

@@ -34,7 +34,7 @@ class NetworkStack;
 class EthInterface;
 class WiFiInterface;
 class MeshInterface;
-class CellularBase;
+class CellularInterface;
 class EMACInterface;
 
 /** Common interface that is shared between network devices.
@@ -325,10 +325,19 @@ class NetworkInterface: public DNS {
         return 0;
     }
 
-    /** Return pointer to a CellularBase.
+    /** Return pointer to a CellularInterface.
      * @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
      */
-    virtual CellularBase *cellularBase()
+    MBED_DEPRECATED_SINCE("mbed-os-5.12", "Migrated to CellularInterface")
+    virtual CellularInterface *cellularBase()
+    {
+        return 0;
+    }
+
+    /** Return pointer to a CellularInterface.
+     * @return Pointer to requested interface type or NULL if this class doesn't implement the interface.
+     */
+    virtual CellularInterface *cellularInterface()
     {
         return 0;
     }