ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #8852 from jarvte/cellular_doxygen_update 

Cellular: update doxygen and add attach CellularDevice.
pull/9018/head
Cruz Monrreal 2018-12-07 11:23:22 -06:00 committed by GitHub
parent c4e913baa4 446c428645
commit fce4dc6dc3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 71 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
features/cellular/framework/API/CellularContext.h
View File

@ -98,7 +98,7 @@ public:
// pointer for next item when used as a linked list // pointer for next item when used as a linked list
CellularContext *_next; CellularContext *_next;
protected: 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; friend class CellularDevice;
virtual ~CellularContext() {} virtual ~CellularContext() {}
@ -106,6 +106,16 @@ public: // from NetworkInterface
virtual nsapi_error_t set_blocking(bool blocking) = 0; virtual nsapi_error_t set_blocking(bool blocking) = 0;
virtual NetworkStack *get_stack() = 0; virtual NetworkStack *get_stack() = 0;
virtual const char *get_ip_address() = 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 void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
virtual nsapi_error_t connect() = 0; virtual nsapi_error_t connect() = 0;
virtual nsapi_error_t disconnect() = 0; virtual nsapi_error_t disconnect() = 0;
@ -122,13 +132,13 @@ public: // from NetworkInterface
static CellularContext *get_default_instance(); 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 /** Start the interface
* *
* Power on the device and does the initializations for communication with the modem.. * 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(...). * 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 * In synchronous and asynchronous mode, the application can get result in from callback, which is set with
* attach(...) * attach(...)
* *
* @return NSAPI_ERROR_OK on success * @return NSAPI_ERROR_OK on success
@ -138,9 +148,9 @@ public: // from NetworkInterface
/** Start the interface /** Start the interface
* *
* Attempts to open the sim. * Attempts to open the SIM.
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...). * 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 * In synchronous and asynchronous mode, the application can get result in from callback, which is set with
* attach(...) * attach(...)
* *
* @return NSAPI_ERROR_OK on success * @return NSAPI_ERROR_OK on success
@ -151,8 +161,8 @@ public: // from NetworkInterface
/** Start the interface /** Start the interface
* *
* Attempts to register the device to cellular network. * Attempts to register the device to cellular network.
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...). * 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 * In synchronous and asynchronous mode, the application can get result in from callback, which is set with
* attach(...) * attach(...)
* *
* @return NSAPI_ERROR_OK on success * @return NSAPI_ERROR_OK on success
@ -163,8 +173,8 @@ public: // from NetworkInterface
/** Start the interface /** Start the interface
* *
* Attempts to attach the device to cellular network. * Attempts to attach the device to cellular network.
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...). * 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 * In synchronous and asynchronous mode, the application can get result in from callback, which is set with
* attach(...) * attach(...)
* *
* @return NSAPI_ERROR_OK on success * @return NSAPI_ERROR_OK on success
@ -186,7 +196,7 @@ public: // from NetworkInterface
virtual nsapi_error_t get_rate_control(CellularContext::RateControlExceptionReports &reports, virtual nsapi_error_t get_rate_control(CellularContext::RateControlExceptionReports &reports,
CellularContext::RateControlUplinkTimeUnit &time_unit, int &uplink_rate) = 0; 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. * @remark optional params are not updated if not received from network.
* @param params_list reference to linked list, which is filled on successful call * @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; 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 * @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 OP_MAX = 5
}; };
/** Status callback function will be called on status changes on the network or CellularDevice /** The CellularDevice calls the status callback function on status changes on the network or CellularDevice.
* by the CellularDevice.
* *
* @param ev event type * @param ev event type
* @param ptr event-type dependent reason parameter * @param ptr event-type dependent reason parameter

59
features/cellular/framework/API/CellularDevice.h
View File

@ -20,6 +20,7 @@
#include "CellularTargets.h" #include "CellularTargets.h"
#include "CellularStateMachine.h" #include "CellularStateMachine.h"
#include "Callback.h"
namespace mbed { namespace mbed {
@ -38,13 +39,13 @@ const int MAX_PLMN_SIZE = 16;
* Class CellularDevice * Class CellularDevice
* *
* An abstract interface that defines opening and closing of cellular interfaces. * 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 { class CellularDevice {
public: public:
/** Return singleton instance of CellularDevice if CELLULAR_DEVICE is defined. If CELLULAR_DEVICE is not /** Returns singleton instance of CellularDevice if CELLULAR_DEVICE is defined. If CELLULAR_DEVICE is not
* defined then returns NULL. Implementation is marked as weak. * defined, then it returns NULL. Implementation is marked as weak.
* *
* @return CellularDevice* instance if any * @return CellularDevice* instance if any
*/ */
@ -62,7 +63,7 @@ public:
/** Creates a new CellularContext interface. /** 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. * file handle is used.
* @param apn access point to use with context, can be null. * @param apn access point to use with context, can be null.
* *
@ -94,8 +95,8 @@ public:
void set_sim_pin(const char *sim_pin); void set_sim_pin(const char *sim_pin);
/** Plmn to use when registering to cellular network. /** 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 * 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. * registering is used when registering to a cellular network. It doesn't start any operations.
* *
* @param plmn plmn used when registering to cellular network * @param plmn plmn used when registering to cellular network
*/ */
@ -103,10 +104,9 @@ public:
/** Start the interface /** Start the interface
* *
* Power on the device and does the initializations for communication with the modem.. * 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(...). * API is asynchronous. Application can get results from CellularContext callback, which is set
* In synchronous and asynchronous mode application can get result in from callback which is set with * with attach(...), or callback, which is set by attach(...), in this class.
* attach(...)
* *
* @return NSAPI_ERROR_OK on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on case of memory failure * NSAPI_ERROR_NO_MEMORY on case of memory failure
@ -116,9 +116,8 @@ public:
/** Start the interface /** Start the interface
* *
* Attempts to open the sim. * Attempts to open the sim.
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...). * API is asynchronous. Application can get results from CellularContext callback, which is set
* In synchronous and asynchronous mode application can get result in from callback which is set with * with attach(...), or callback, which is set by attach(...), in this class.
* attach(...)
* *
* @return NSAPI_ERROR_OK on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on case of memory failure * NSAPI_ERROR_NO_MEMORY on case of memory failure
@ -128,9 +127,8 @@ public:
/** Start the interface /** Start the interface
* *
* Attempts to register the device to cellular network. * Attempts to register the device to cellular network.
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...). * API is asynchronous. Application can get results from CellularContext callback, which is set
* In synchronous and asynchronous mode application can get result in from callback which is set with * with attach(...), or callback, which is set by attach(...), in this class.
* attach(...)
* *
* @return NSAPI_ERROR_OK on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on case of memory failure * NSAPI_ERROR_NO_MEMORY on case of memory failure
@ -140,18 +138,30 @@ public:
/** Start the interface /** Start the interface
* *
* Attempts to attach the device to cellular network. * Attempts to attach the device to cellular network.
* By default this API is synchronous. API can be set to asynchronous with method set_blocking(...). * API is asynchronous. Application can get results from CellularContext callback, which is set
* In synchronous and asynchronous mode application can get result in from callback which is set with * with attach(...), or callback, which is set by attach(...), in this class.
* attach(...)
* *
* @return NSAPI_ERROR_OK on success * @return NSAPI_ERROR_OK on success
* NSAPI_ERROR_NO_MEMORY on case of memory failure * NSAPI_ERROR_NO_MEMORY on case of memory failure
*/ */
nsapi_error_t attach_to_network(); 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. /** 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. * file handle is used.
* @return New instance of interface CellularNetwork. * @return New instance of interface CellularNetwork.
*/ */
@ -159,7 +169,7 @@ public:
/** Create new CellularSMS interface. /** 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. * file handle is used.
* @return New instance of interface CellularSMS. * @return New instance of interface CellularSMS.
*/ */
@ -167,7 +177,7 @@ public:
/** Create new CellularPower interface. /** 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. * file handle is used.
* @return New instance of interface CellularPower. * @return New instance of interface CellularPower.
*/ */
@ -175,7 +185,7 @@ public:
/** Create new CellularSIM interface. /** 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. * file handle is used.
* @return New instance of interface CellularSIM. * @return New instance of interface CellularSIM.
*/ */
@ -183,7 +193,7 @@ public:
/** Create new CellularInformation interface. /** 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. * file handle is used.
* @return New instance of interface CellularInformation. * @return New instance of interface CellularInformation.
*/ */
@ -266,6 +276,7 @@ private:
char _sim_pin[MAX_PIN_SIZE + 1]; char _sim_pin[MAX_PIN_SIZE + 1];
char _plmn[MAX_PLMN_SIZE + 1]; char _plmn[MAX_PLMN_SIZE + 1];
PlatformMutex _mutex; PlatformMutex _mutex;
Callback<void(nsapi_event_t, intptr_t)> _status_cb;
}; };
} // namespace mbed } // namespace mbed

12
features/cellular/framework/device/CellularDevice.cpp
View File

@ -51,7 +51,7 @@ MBED_WEAK CellularDevice *CellularDevice::get_default_instance()
#endif // CELLULAR_DEVICE #endif // CELLULAR_DEVICE
CellularDevice::CellularDevice(FileHandle *fh) : _network_ref_count(0), _sms_ref_count(0), _power_ref_count(0), _sim_ref_count(0), 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_sim_pin(NULL);
set_plmn(NULL); set_plmn(NULL);
@ -158,6 +158,11 @@ nsapi_error_t CellularDevice::start_state_machine(CellularStateMachine::Cellular
return err; 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) void CellularDevice::cellular_callback(nsapi_event_t ev, intptr_t ptr)
{ {
if (ev >= NSAPI_EVENT_CELLULAR_STATUS_BASE && ev <= NSAPI_EVENT_CELLULAR_STATUS_END) { 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->cellular_callback(ev, ptr);
curr = curr->_next; curr = curr->_next;
} }
// forward to callback function if set by attach(...)
if (_status_cb) {
_status_cb(ev, ptr);
}
} }
} // namespace mbed } // namespace mbed