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
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<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 @@ 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

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

@ -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<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.
*/
@ -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<void(nsapi_event_t, intptr_t)> _status_cb;
};
} // 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
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