Merge pull request #8852 from jarvte/cellular_doxygen_update

Cellular: update doxygen and add attach CellularDevice.

Author: Cruz Monrreal

features/cellular/framework/API/CellularContext.h

@@ -98,14 +98,24 @@ class CellularContext : public CellularBase {
     // pointer for next item when used as a linked list
     CellularContext *_next;
 protected:
-    // friend of CellularDevice so that it's the only way to close/delete this class.
+    // friend of CellularDevice, so it's the only way to close or delete this class.
     friend class CellularDevice;
     virtual ~CellularContext() {}
 
 public: // from NetworkInterface
     virtual nsapi_error_t set_blocking(bool blocking) = 0;
     virtual NetworkStack *get_stack() = 0;
     virtual const char *get_ip_address() = 0;
+
+    /** Register callback for status reporting.
+     *
+     *  The specified status callback function is called on the network, and the cellular device status changes.
+     *  The parameters on the callback are the event type and event type dependent reason parameter.
+     *
+     *  @remark  deleting CellularDevice/CellularContext in callback is not allowed.
+     *
+     *  @param status_cb The callback for status changes.
+     */
     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
     virtual nsapi_error_t connect() = 0;
     virtual nsapi_error_t disconnect() = 0;
@@ -122,13 +132,13 @@ class CellularContext : public CellularBase {
     static CellularContext *get_default_instance();
 
 
-// Operations, can be sync/async. Also Connect() is this kind of operations, inherited from NetworkInterface above.
+// Operations, can be sync/async. Also Connect() is this kind of operation, inherited from NetworkInterface above.
 
     /** Start the interface
      *
-     *  Power on the device and does the initializations for communication with the modem..
-     *  By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
-     *  In synchronous and asynchronous mode application can get result in from callback which is set with
+     *  Powers on the device and does the initializations for communication with the modem.
+     *  By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
+     *  In synchronous and asynchronous mode, the application can get result in from callback, which is set with
      *  attach(...)
      *
      *  @return         NSAPI_ERROR_OK on success
@@ -138,9 +148,9 @@ class CellularContext : public CellularBase {
 
     /** Start the interface
      *
-     *  Attempts to open the sim.
-     *  By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
-     *  In synchronous and asynchronous mode application can get result in from callback which is set with
+     *  Attempts to open the SIM.
+     *  By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
+     *  In synchronous and asynchronous mode, the application can get result in from callback, which is set with
      *  attach(...)
      *
      *  @return         NSAPI_ERROR_OK on success
@@ -151,8 +161,8 @@ class CellularContext : public CellularBase {
     /** Start the interface
      *
      *  Attempts to register the device to cellular network.
-     *  By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
-     *  In synchronous and asynchronous mode application can get result in from callback which is set with
+     *  By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
+     *  In synchronous and asynchronous mode, the application can get result in from callback, which is set with
      *  attach(...)
      *
      *  @return         NSAPI_ERROR_OK on success
@@ -163,8 +173,8 @@ class CellularContext : public CellularBase {
     /** Start the interface
      *
      *  Attempts to attach the device to cellular network.
-     *  By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
-     *  In synchronous and asynchronous mode application can get result in from callback which is set with
+     *  By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
+     *  In synchronous and asynchronous mode, the application can get result in from callback, which is set with
      *  attach(...)
      *
      *  @return         NSAPI_ERROR_OK on success
@@ -186,7 +196,7 @@ class CellularContext : public CellularBase {
     virtual nsapi_error_t get_rate_control(CellularContext::RateControlExceptionReports &reports,
                                            CellularContext::RateControlUplinkTimeUnit &time_unit, int &uplink_rate) = 0;
 
-    /** Get the relevant information for an active non secondary PDP context.
+    /** Get the relevant information for an active nonsecondary PDP context.
      *
      *  @remark optional params are not updated if not received from network.
      *  @param params_list   reference to linked list, which is filled on successful call
@@ -205,7 +215,7 @@ class CellularContext : public CellularBase {
      */
     virtual nsapi_error_t get_apn_backoff_timer(int &backoff_timer) = 0;
 
-    /** Set the file handle used to communicate with the modem. Can be used to change default file handle.
+    /** Set the file handle used to communicate with the modem. You can use this to change the default file handle.
      *
      *  @param fh   file handle for communicating with the modem
      */
@@ -222,8 +232,7 @@ class CellularContext : public CellularBase {
         OP_MAX          = 5
     };
 
-    /** Status callback function will be called on status changes on the network or CellularDevice
-     *  by the CellularDevice.
+    /** The CellularDevice calls the status callback function on status changes on the network or CellularDevice.
     *
     *  @param ev   event type
     *  @param ptr  event-type dependent reason parameter

features/cellular/framework/API/CellularDevice.h

@@ -20,6 +20,7 @@
 
 #include "CellularTargets.h"
 #include "CellularStateMachine.h"
+#include "Callback.h"
 
 namespace mbed {
 
@@ -38,13 +39,13 @@ const int MAX_PLMN_SIZE = 16;
  *  Class CellularDevice
  *
  *  An abstract interface that defines opening and closing of cellular interfaces.
- *  Deleting/Closing of opened interfaces can be done only via this class.
+ *  You can delete or close opened interfaces only through this class.
  */
 class CellularDevice {
 public:
 
-    /** Return singleton instance of CellularDevice if CELLULAR_DEVICE is defined. If CELLULAR_DEVICE is not
-     *  defined then returns NULL. Implementation is marked as weak.
+    /** Returns singleton instance of CellularDevice if CELLULAR_DEVICE is defined. If CELLULAR_DEVICE is not
+     *  defined, then it returns NULL. Implementation is marked as weak.
      *
      *  @return CellularDevice* instance if any
      */
@@ -62,7 +63,7 @@ class CellularDevice {
 
     /** Creates a new CellularContext interface.
      *
-     *  @param fh       file handle used in communication to modem. Can be for example UART handle. If null then the default
+     *  @param fh       file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
      *                  file handle is used.
      *  @param apn      access point to use with context, can be null.
      *
@@ -94,19 +95,18 @@ class CellularDevice {
     void set_sim_pin(const char *sim_pin);
 
     /** Plmn to use when registering to cellular network.
-     *  If plmn is set then registering is forced to this plmn. If plmn is not set then automatic
-     *  registering is used when registering to a cellular network. Does not start any operations.
+     *  If plmn is set, then registering is forced to this plmn. If plmn is not set, then automatic
+     *  registering is used when registering to a cellular network. It doesn't start any operations.
      *
      *  @param plmn     plmn used when registering to cellular network
      */
     void set_plmn(const char *plmn);
 
     /** Start the interface
      *
-     *  Power on the device and does the initializations for communication with the modem..
-     *  By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
-     *  In synchronous and asynchronous mode application can get result in from callback which is set with
-     *  attach(...)
+     *  Powers on the device and does the initializations for communication with the modem.
+     *  API is asynchronous. Application can get results from CellularContext callback, which is set
+     *  with attach(...), or callback, which is set by attach(...), in this class.
      *
      *  @return         NSAPI_ERROR_OK on success
      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
@@ -116,9 +116,8 @@ class CellularDevice {
     /** Start the interface
      *
      *  Attempts to open the sim.
-     *  By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
-     *  In synchronous and asynchronous mode application can get result in from callback which is set with
-     *  attach(...)
+     *  API is asynchronous. Application can get results from CellularContext callback, which is set
+     *  with attach(...), or callback, which is set by attach(...), in this class.
      *
      *  @return         NSAPI_ERROR_OK on success
      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
@@ -128,9 +127,8 @@ class CellularDevice {
     /** Start the interface
      *
      *  Attempts to register the device to cellular network.
-     *  By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
-     *  In synchronous and asynchronous mode application can get result in from callback which is set with
-     *  attach(...)
+     *  API is asynchronous. Application can get results from CellularContext callback, which is set
+     *  with attach(...), or callback, which is set by attach(...), in this class.
      *
      *  @return         NSAPI_ERROR_OK on success
      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
@@ -140,50 +138,62 @@ class CellularDevice {
     /** Start the interface
      *
      *  Attempts to attach the device to cellular network.
-     *  By default this API is synchronous. API can be set to asynchronous with method set_blocking(...).
-     *  In synchronous and asynchronous mode application can get result in from callback which is set with
-     *  attach(...)
+     *  API is asynchronous. Application can get results from CellularContext callback, which is set
+     *  with attach(...), or callback, which is set by attach(...), in this class.
      *
      *  @return         NSAPI_ERROR_OK on success
      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
      */
     nsapi_error_t attach_to_network();
 
+    /** Register callback for status reporting.
+     *
+     *  The specified status callback function is called on the network, and the cellular device status changes.
+     *  The parameters on the callback are the event type and event type dependent reason parameter.
+     *
+     *  @remark  deleting CellularDevice/CellularContext in callback is not allowed.
+     *  @remark  application should not attach to this function if it uses CellularContext::attach because it contains the
+     *           same information.
+     *
+     *  @param status_cb The callback for status changes.
+     */
+    void attach(Callback<void(nsapi_event_t, intptr_t)> status_cb);
+
     /** Create new CellularNetwork interface.
      *
-     *  @param fh    file handle used in communication to modem. Can be for example UART handle. If null then the default
+     *  @param fh    file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
      *               file handle is used.
      *  @return      New instance of interface CellularNetwork.
      */
     virtual CellularNetwork *open_network(FileHandle *fh = NULL) = 0;
 
     /** Create new CellularSMS interface.
      *
-     *  @param fh    file handle used in communication to modem. Can be for example UART handle. If null then the default
+     *  @param fh    file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
      *               file handle is used.
      *  @return      New instance of interface CellularSMS.
      */
     virtual CellularSMS *open_sms(FileHandle *fh = NULL) = 0;
 
     /** Create new CellularPower interface.
      *
-     *  @param fh    file handle used in communication to modem. Can be for example UART handle. If null then the default
+     *  @param fh    file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
      *               file handle is used.
      *  @return      New instance of interface CellularPower.
      */
     virtual CellularPower *open_power(FileHandle *fh = NULL) = 0;
 
     /** Create new CellularSIM interface.
      *
-     *  @param fh    file handle used in communication to modem. Can be for example UART handle. If null then the default
+     *  @param fh    file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
      *               file handle is used.
      *  @return      New instance of interface CellularSIM.
      */
     virtual CellularSIM *open_sim(FileHandle *fh = NULL) = 0;
 
     /** Create new CellularInformation interface.
      *
-     *  @param fh    file handle used in communication to modem. Can be for example UART handle. If null then the default
+     *  @param fh    file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
      *               file handle is used.
      *  @return      New instance of interface CellularInformation.
      */
@@ -266,6 +276,7 @@ class CellularDevice {
     char _sim_pin[MAX_PIN_SIZE + 1];
     char _plmn[MAX_PLMN_SIZE + 1];
     PlatformMutex _mutex;
+    Callback<void(nsapi_event_t, intptr_t)> _status_cb;
 };
 
 } // namespace mbed

features/cellular/framework/device/CellularDevice.cpp

@@ -51,7 +51,7 @@ MBED_WEAK CellularDevice *CellularDevice::get_default_instance()
 #endif // CELLULAR_DEVICE
 
 CellularDevice::CellularDevice(FileHandle *fh) : _network_ref_count(0), _sms_ref_count(0), _power_ref_count(0), _sim_ref_count(0),
-    _info_ref_count(0), _fh(fh), _queue(5 * EVENTS_EVENT_SIZE), _state_machine(0), _nw(0)
+    _info_ref_count(0), _fh(fh), _queue(5 * EVENTS_EVENT_SIZE), _state_machine(0), _nw(0), _status_cb(0)
 {
     set_sim_pin(NULL);
     set_plmn(NULL);
@@ -158,6 +158,11 @@ nsapi_error_t CellularDevice::start_state_machine(CellularStateMachine::Cellular
     return err;
 }
 
+void CellularDevice::attach(Callback<void(nsapi_event_t, intptr_t)> status_cb)
+{
+    _status_cb = status_cb;
+}
+
 void CellularDevice::cellular_callback(nsapi_event_t ev, intptr_t ptr)
 {
     if (ev >= NSAPI_EVENT_CELLULAR_STATUS_BASE && ev <= NSAPI_EVENT_CELLULAR_STATUS_END) {
@@ -200,6 +205,11 @@ void CellularDevice::cellular_callback(nsapi_event_t ev, intptr_t ptr)
         curr->cellular_callback(ev, ptr);
         curr = curr->_next;
     }
+
+    // forward to callback function if set by attach(...)
+    if (_status_cb) {
+        _status_cb(ev, ptr);
+    }
 }
 
 } // namespace mbed