diff --git a/features/cellular/framework/API/CellularContext.h b/features/cellular/framework/API/CellularContext.h index 9107d585e6..0e3cdaa4b5 100644 --- a/features/cellular/framework/API/CellularContext.h +++ b/features/cellular/framework/API/CellularContext.h @@ -98,7 +98,7 @@ public: // 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() {} @@ -106,6 +106,16 @@ 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 status_cb) = 0; virtual nsapi_error_t connect() = 0; virtual nsapi_error_t disconnect() = 0; @@ -122,13 +132,13 @@ public: // from NetworkInterface 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 @@ public: // from NetworkInterface /** 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 @@ public: // from NetworkInterface /** 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 @@ public: // from NetworkInterface /** 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 @@ public: // from NetworkInterface 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 @@ public: // from NetworkInterface */ 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 @@ protected: // Device specific implementations might need these so protected 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 diff --git a/features/cellular/framework/API/CellularDevice.h b/features/cellular/framework/API/CellularDevice.h index 4dc952f863..e42bad08e6 100644 --- a/features/cellular/framework/API/CellularDevice.h +++ b/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 @@ public: /** 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,8 +95,8 @@ public: 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 */ @@ -103,10 +104,9 @@ public: /** 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 @@ public: /** 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 @@ public: /** 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,18 +138,30 @@ public: /** 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 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. */ @@ -159,7 +169,7 @@ public: /** 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. */ @@ -167,7 +177,7 @@ public: /** 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. */ @@ -175,7 +185,7 @@ public: /** 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. */ @@ -183,7 +193,7 @@ public: /** 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 @@ private: char _sim_pin[MAX_PIN_SIZE + 1]; char _plmn[MAX_PLMN_SIZE + 1]; PlatformMutex _mutex; + Callback _status_cb; }; } // namespace mbed diff --git a/features/cellular/framework/device/CellularDevice.cpp b/features/cellular/framework/device/CellularDevice.cpp index 6ad46ddc67..bb623fe501 100644 --- a/features/cellular/framework/device/CellularDevice.cpp +++ b/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 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