CellularContext.h

00001 /*
00002  * Copyright (c) 2018, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 #ifndef _CELLULARCONTEXT_H_
00018 #define _CELLULARCONTEXT_H_
00019 
00020 #include "CellularInterface.h"
00021 #include "CellularDevice.h"
00022 #include "CellularUtil.h"
00023 #include "ControlPlane_netif.h"
00024 #include "PinNames.h"
00025 
00026 /** @file CellularContext.h
00027  * @brief Cellular PDP context class
00028  *
00029  */
00030 
00031 namespace mbed {
00032 
00033 /**
00034  * @addtogroup cellular
00035  * @{
00036  */
00037 
00038 /// CellularContext is CellularInterface/NetworkInterface with extensions for cellular connectivity
00039 class CellularContext : public CellularInterface {
00040 
00041 public:
00042 
00043     // max simultaneous PDP contexts active
00044     static const int PDP_CONTEXT_COUNT = 4;
00045 
00046     /* authentication type when activating or modifying the pdp context */
00047     enum AuthenticationType {
00048         NOAUTH = 0,
00049         PAP,
00050         CHAP,
00051         AUTOMATIC
00052     };
00053 
00054     /*  whether the additional exception reports are allowed to be sent when the maximum uplink rate is reached */
00055     enum RateControlExceptionReports {
00056         NotAllowedToBeSent = 0,
00057         AllowedToBeSent
00058     };
00059 
00060     /* specifies the time unit to be used for the maximum uplink rate */
00061     enum RateControlUplinkTimeUnit {
00062         Unrestricted = 0,
00063         Minute,
00064         Hour,
00065         Day,
00066         Week
00067     };
00068 
00069     /// PDP Context information
00070     struct pdpcontext_params_t {
00071         char apn[MAX_ACCESSPOINT_NAME_LENGTH + 1];
00072         char local_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00073         char local_subnet_mask[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00074         char gateway_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00075         char dns_primary_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00076         char dns_secondary_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00077         char p_cscf_prim_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00078         char p_cscf_sec_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00079         int cid;
00080         int bearer_id;
00081         int im_signalling_flag;
00082         int lipa_indication;
00083         int ipv4_mtu;
00084         int wlan_offload;
00085         int local_addr_ind;
00086         int non_ip_mtu;
00087         int serving_plmn_rate_control_value;
00088         pdpcontext_params_t *next;
00089 
00090         pdpcontext_params_t()
00091         {
00092             apn[0] = '\0';
00093             local_addr[0] = '\0';
00094             local_subnet_mask[0] = '\0';
00095             gateway_addr[0] = '\0';
00096             dns_primary_addr[0] = '\0';
00097             dns_secondary_addr[0] = '\0';
00098             p_cscf_prim_addr[0] = '\0';
00099             p_cscf_sec_addr[0] = '\0';
00100             cid = -1;
00101             bearer_id = -1;
00102             im_signalling_flag = -1;
00103             lipa_indication = -1;
00104             ipv4_mtu = -1;
00105             wlan_offload = -1;
00106             local_addr_ind = -1;
00107             non_ip_mtu = -1;
00108             serving_plmn_rate_control_value = -1;
00109             next = NULL;
00110         }
00111     };
00112     typedef CellularList<pdpcontext_params_t> pdpContextList_t;
00113 
00114     // pointer for next item when used as a linked list
00115     CellularContext *_next;
00116 protected:
00117     // friend of CellularDevice, so it's the only way to close or delete this class.
00118     friend class CellularDevice;
00119     CellularContext();
00120     virtual ~CellularContext() {}
00121 public: // from NetworkInterface
00122     virtual nsapi_error_t set_blocking(bool blocking) = 0;
00123     virtual NetworkStack *get_stack() = 0;
00124     virtual nsapi_error_t get_ip_address (SocketAddress *address) = 0;
00125     MBED_DEPRECATED_SINCE ("mbed-os-5.15", "String-based APIs are deprecated")
00126     virtual const char *get_ip_address () = 0;
00127 
00128     /** Register callback for status reporting.
00129      *
00130      *  The specified status callback function is called on the network, and the cellular device status changes.
00131      *  The parameters on the callback are the event type and event type dependent reason parameter.
00132      *
00133      *  @remark  deleting CellularDevice/CellularContext in callback is not allowed.
00134      *  @remark  Allocating/adding lots of traces not recommended as callback is called mostly from State machines thread which
00135      *           is now 2048. You can change to main thread for example via EventQueue.
00136      *
00137      *  @param status_cb The callback for status changes.
00138      */
00139     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
00140     virtual nsapi_error_t connect() = 0;
00141     virtual nsapi_error_t disconnect() = 0;
00142 
00143     // from CellularInterface
00144     virtual void set_plmn(const char *plmn) = 0;
00145     virtual void set_sim_pin(const char *sim_pin) = 0;
00146     virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0, const char *uname = 0,
00147                                   const char *pwd = 0) = 0;
00148     virtual void set_credentials(const char *apn, const char *uname = 0, const char *pwd = 0) = 0;
00149     virtual nsapi_error_t get_netmask (SocketAddress *address) = 0;
00150     MBED_DEPRECATED_SINCE ("mbed-os-5.15", "String-based APIs are deprecated")
00151     virtual const char *get_netmask () = 0;
00152     virtual nsapi_error_t get_gateway (SocketAddress *address) = 0;
00153     MBED_DEPRECATED_SINCE ("mbed-os-5.15", "String-based APIs are deprecated")
00154     virtual const char *get_gateway () = 0;
00155     virtual bool is_connected() = 0;
00156 
00157     /** Same as NetworkInterface::get_default_instance()
00158      *
00159      *  @note not to be used if get_default_nonip_instance() was already used
00160      *
00161      */
00162     static CellularContext *get_default_instance();
00163 
00164 
00165     /** Instantiates a default Non-IP cellular interface
00166      *
00167      *  This function creates a new Non-IP PDP context.
00168      *
00169      *  @note not to be used if get_default_instance() was already used
00170      *
00171      *  @return         A Non-IP cellular PDP context
00172      *
00173      */
00174     static CellularContext *get_default_nonip_instance();
00175 
00176     /** Get pointer to CellularDevice instance. May be null if not AT-layer.
00177      *
00178      *  @return pointer to CellularDevice instance
00179      */
00180     CellularDevice *get_device() const;
00181 
00182 // Operations, can be sync/async. Also Connect() is this kind of operation, inherited from NetworkInterface above.
00183 
00184     /** Start the interface
00185      *
00186      *  Initializes the modem for communication.
00187      *  By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
00188      *  In synchronous and asynchronous mode application can get result in from callback which is set with
00189      *  attach(...)
00190      *
00191      *  @return         NSAPI_ERROR_OK on success
00192      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
00193      */
00194     virtual nsapi_error_t set_device_ready() = 0;
00195 
00196     /** Start the interface
00197      *
00198      *  Attempts to open the SIM.
00199      *  By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
00200      *  In synchronous and asynchronous mode, the application can get result in from callback, which is set with
00201      *  attach(...)
00202      *
00203      *  @return         NSAPI_ERROR_OK on success
00204      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
00205      */
00206     virtual nsapi_error_t set_sim_ready() = 0;
00207 
00208     /** Start the interface
00209      *
00210      *  Attempts to register the device to cellular network.
00211      *  By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
00212      *  In synchronous and asynchronous mode, the application can get result in from callback, which is set with
00213      *  attach(...)
00214      *
00215      *  @return         NSAPI_ERROR_OK on success
00216      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
00217      */
00218     virtual nsapi_error_t register_to_network() = 0;
00219 
00220     /** Start the interface
00221      *
00222      *  Attempts to attach the device to cellular network.
00223      *  By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
00224      *  In synchronous and asynchronous mode, the application can get result in from callback, which is set with
00225      *  attach(...)
00226      *
00227      *  @return         NSAPI_ERROR_OK on success
00228      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
00229      */
00230     virtual nsapi_error_t attach_to_network() = 0;
00231 
00232 // PDP Context specific functions
00233 
00234     /** Get APN rate control.
00235      *
00236      *  @remark optional params are not updated if not received from network, so use good defaults
00237      *  @param reports       Additional exception reports at maximum rate reached are allowed to be sent [optional]
00238      *  @param time_unit     Uplink time unit with values 0=unrestricted, 1=minute, 2=hour, 3=day, 4=week [optional]
00239      *  @param uplink_rate   Maximum number of messages per timeUnit [optional]
00240      *  @return              NSAPI_ERROR_OK on success
00241      *                       NSAPI_ERROR_DEVICE_ERROR on case of failure
00242      */
00243     virtual nsapi_error_t get_rate_control(CellularContext::RateControlExceptionReports &reports,
00244                                            CellularContext::RateControlUplinkTimeUnit &time_unit, int &uplink_rate) = 0;
00245 
00246     /** Get the relevant information for an active nonsecondary PDP context.
00247      *
00248      *  @remark optional params are not updated if not received from network.
00249      *  @param params_list   reference to linked list, which is filled on successful call
00250      *  @return              NSAPI_ERROR_OK on success
00251      *                       NSAPI_ERROR_NO_MEMORY on memory failure
00252      *                       NSAPI_ERROR_DEVICE_ERROR on other failures
00253      */
00254     virtual nsapi_error_t get_pdpcontext_params(pdpContextList_t &params_list) = 0;
00255 
00256     /** Get backoff timer value
00257      *
00258      *  @param backoff_timer Backoff timer value associated with PDP APN in seconds
00259      *  @return              NSAPI_ERROR_OK on success
00260      *                       NSAPI_ERROR_PARAMETER if no access point is set or found when activating context
00261      *                       NSAPI_ERROR_DEVICE_ERROR on failure
00262      */
00263     virtual nsapi_error_t get_apn_backoff_timer(int &backoff_timer) = 0;
00264 
00265     /** Set the file handle used to communicate with the modem. You can use this to change the default file handle.
00266      *
00267      *  @param fh   file handle for communicating with the modem
00268      */
00269     virtual void set_file_handle(FileHandle *fh) = 0;
00270 
00271 #if (DEVICE_SERIAL && DEVICE_INTERRUPTIN) || defined(DOXYGEN_ONLY)
00272     /** Set the UART serial used to communicate with the modem. Can be used to change default file handle.
00273      *  File handle set with this method will use data carrier detect to be able to detect disconnection much faster in PPP mode.
00274      *
00275      *  @param serial       UARTSerial used in communication to modem. If null then the default file handle is used.
00276      *  @param dcd_pin      Pin used to set data carrier detect on/off for the given UART
00277      *  @param active_high  a boolean set to true if DCD polarity is active low
00278      */
00279     virtual void set_file_handle(UARTSerial *serial, PinName dcd_pin = NC, bool active_high = false) = 0;
00280 #endif // #if DEVICE_SERIAL
00281 
00282     /** Returns the control plane AT command interface
00283      */
00284     virtual ControlPlane_netif *get_cp_netif() = 0;
00285 
00286     /** Get the pdp context id associated with this context.
00287      *
00288      *  @return cid
00289      */
00290     int get_cid() const;
00291 
00292     /** Set the authentication type to be used in user authentication if user name and password are defined
00293      *
00294      *  @param type enum AuthenticationType
00295      */
00296     void set_authentication_type(AuthenticationType type);
00297 
00298 protected: // Device specific implementations might need these so protected
00299     enum ContextOperation {
00300         OP_INVALID      = -1,
00301         OP_DEVICE_READY = 0,
00302         OP_SIM_READY    = 1,
00303         OP_REGISTER     = 2,
00304         OP_ATTACH       = 3,
00305         OP_CONNECT      = 4,
00306         OP_MAX          = 5
00307     };
00308 
00309     /** The CellularDevice calls the status callback function on status changes on the network or CellularDevice.
00310     *
00311     *  @param ev   event type
00312     *  @param ptr  event-type dependent reason parameter
00313     */
00314     virtual void cellular_callback(nsapi_event_t ev, intptr_t ptr) = 0;
00315 
00316     /** Enable or disable hang-up detection
00317      *
00318      *  When in PPP data pump mode, it is helpful if the FileHandle will signal hang-up via
00319      *  POLLHUP, e.g., if the DCD line is deasserted on a UART. During command mode, this
00320      *  signaling is not desired. enable_hup() controls whether this function should be
00321      *  active.
00322      */
00323     virtual void enable_hup(bool enable) = 0;
00324 
00325     /** Triggers control plane's operations needed when control plane data is received,
00326      *  like socket event, for example.
00327      */
00328     void cp_data_received();
00329 
00330     /** Retry logic after device attached to network. Retry to find and activate pdp context or in case
00331      *  of PPP find correct pdp context and open data channel. Retry logic is the same which is used in
00332      *  CellularStateMachine.
00333      */
00334     virtual void do_connect_with_retry();
00335 
00336     /** Helper method to call callback function if it is provided
00337      *
00338      *  @param status connection status which is parameter in callback function
00339      */
00340     void call_network_cb(nsapi_connection_status_t status);
00341 
00342     /** Find and activate pdp context or in case of PPP find correct pdp context and open data channel.
00343      */
00344     virtual void do_connect();
00345 
00346     /** After we have connected successfully we must check that we have a valid IP address.
00347      *  Some modems/networks don't give IP address right after connect so we must poll it for a while.
00348      */
00349     void validate_ip_address();
00350 
00351     // member variables needed in target override methods
00352     NetworkStack *_stack; // must be pointer because of PPP
00353     pdp_type_t _pdp_type;
00354     CellularContext::AuthenticationType _authentication_type;
00355     nsapi_connection_status_t _connect_status;
00356     cell_callback_data_t _cb_data;
00357     Callback<void(nsapi_event_t, intptr_t)> _status_cb;
00358     int _cid;
00359     bool _new_context_set;
00360     bool _is_context_active;
00361     bool _is_context_activated; // did we activate the context
00362     const char *_apn;
00363     const char *_uname;
00364     const char *_pwd;
00365     PinName _dcd_pin;
00366     bool _active_high;
00367 
00368     ControlPlane_netif *_cp_netif;
00369     uint16_t _retry_timeout_array[CELLULAR_RETRY_ARRAY_SIZE];
00370     int _retry_array_length;
00371     int _retry_count;
00372     CellularDevice *_device;
00373     CellularNetwork *_nw;
00374     bool _is_blocking;
00375     // flag indicating if Non-IP context was requested to be setup
00376     bool _nonip_req;
00377     // tells if CCIOTOPTI received green from network for CP optimization use
00378     bool _cp_in_use;
00379 };
00380 
00381 /**
00382  * @}
00383  */
00384 
00385 } // namespace mbed
00386 
00387 
00388 #endif /* _CELLULARCONTEXT_H_ */