CellularNetwork.h

00001 /*
00002  * Copyright (c) 2017, 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 
00018 #ifndef CELLULAR_NETWORK_H_
00019 #define CELLULAR_NETWORK_H_
00020 
00021 #include "NetworkInterface.h"
00022 #include "CellularList.h"
00023 
00024 namespace mbed {
00025 
00026 /* Maximum length of IPV6 address in ipv4-like dotted format. More info in 3gpp 27007.*/
00027 const int MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT = 63;
00028 /* Maximum length of access point name */
00029 const int MAX_ACCESSPOINT_NAME_LENGTH = 100;
00030 const int MAX_OPERATOR_NAME_LONG = 16;
00031 const int MAX_OPERATOR_NAME_SHORT = 8;
00032 
00033 /**
00034  *  Class CellularNetwork
00035  *
00036  *  An abstract interface for connecting to a network and getting information from it.
00037  */
00038 class CellularNetwork : public NetworkInterface
00039 {
00040 protected:
00041     // friend of CellularDevice so that it's the only way to close/delete this class.
00042     friend class CellularDevice;
00043 
00044     /**
00045      * virtual Destructor
00046      */
00047     virtual ~CellularNetwork() {}
00048 
00049 public:
00050     /* Definition for Supported CIoT EPS optimizations type. */
00051     enum Supported_UE_Opt {
00052         SUPPORTED_UE_OPT_NO_SUPPORT = 0, /* No support. */
00053         SUPPORTED_UE_OPT_CONTROL_PLANE,  /* Support for control plane CIoT EPS optimization. */
00054         SUPPORTED_UE_OPT_USER_PLANE,     /* Support for user plane CIoT EPS optimization. */
00055         SUPPORTED_UE_OPT_BOTH,           /* Support for both control plane CIoT EPS optimization and user plane CIoT EPS
00056                                             optimization. */
00057         SUPPORTED_UE_OPT_MAX
00058     };
00059 
00060     /* Definition for Preferred CIoT EPS optimizations type. */
00061     enum Preferred_UE_Opt {
00062         PREFERRED_UE_OPT_NO_PREFERENCE = 0, /* No preference. */
00063         PREFERRED_UE_OPT_CONTROL_PLANE,     /* Preference for control plane CIoT EPS optimization. */
00064         PREFERRED_UE_OPT_USER_PLANE,        /* Preference for user plane CIoT EPS optimization. */
00065         PREFERRED_UE_OPT_MAX
00066     };
00067 
00068     /* Network registration status */
00069     enum RegistrationStatus {
00070         NotRegistered = 0,
00071         RegisteredHomeNetwork,
00072         SearchingNetwork,
00073         RegistrationDenied,
00074         Unknown,
00075         RegisteredRoaming,
00076         RegisteredSMSOnlyHome,
00077         RegisteredSMSOnlyRoaming,
00078         AttachedEmergencyOnly,
00079         RegisteredCSFBNotPreferredHome,
00080         RegisteredCSFBNotPreferredRoaming = 10
00081     };
00082 
00083     /* Network registration type */
00084     enum RegistrationType {
00085         C_EREG = 0,
00086         C_GREG,
00087         C_REG,
00088         C_MAX
00089     };
00090 
00091     /* device attach status to network */
00092     enum AttachStatus {
00093         Detached = 0,
00094         Attached,
00095     };
00096 
00097     /*  whether the additional exception reports are allowed to be sent when the maximum uplink rate is reached */
00098     enum RateControlExceptionReports {
00099         NotAllowedToBeSent = 0,
00100         AllowedToBeSent
00101     };
00102 
00103     /* specifies the time unit to be used for the maximum uplink rate */
00104     enum RateControlUplinkTimeUnit {
00105         Unrestricted = 0,
00106         Minute,
00107         Hour,
00108         Day,
00109         Week
00110     };
00111 
00112     /* authentication type when activating or modifying the pdp context */
00113     enum AuthenticationType {
00114         NOAUTH = 0,
00115         PAP,
00116         CHAP
00117     };
00118 
00119     // 3GPP TS 27.007 - 7.3 PLMN selection +COPS
00120     struct operator_t {
00121         enum Status {
00122             Unknown,
00123             Available,
00124             Current,
00125             Forbiden
00126         };
00127 
00128         enum RadioAccessTechnology {
00129             RAT_GSM,
00130             RAT_GSM_COMPACT,
00131             RAT_UTRAN,
00132             RAT_EGPRS,
00133             RAT_HSDPA,
00134             RAT_HSUPA,
00135             RAT_HSDPA_HSUPA,
00136             RAT_E_UTRAN,
00137             RAT_CATM1,
00138             RAT_NB1,
00139             RAT_UNKNOWN
00140         };
00141 
00142 
00143         Status op_status;
00144         char op_long[MAX_OPERATOR_NAME_LONG+1];
00145         char op_short[MAX_OPERATOR_NAME_SHORT+1];
00146         char op_num[MAX_OPERATOR_NAME_SHORT+1];
00147         RadioAccessTechnology op_rat;
00148         operator_t *next;
00149 
00150         operator_t() {
00151             op_status = Unknown;
00152             op_rat = RAT_UNKNOWN;
00153             next = NULL;
00154         }
00155     };
00156 
00157     typedef CellularList<operator_t> operList_t;
00158 
00159     /* PDP Context information */
00160     struct pdpcontext_params_t {
00161         char apn[MAX_ACCESSPOINT_NAME_LENGTH+1];
00162         char local_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT+1];
00163         char local_subnet_mask[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT+1];
00164         char gateway_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT+1];
00165         char dns_primary_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT+1];
00166         char dns_secondary_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT+1];
00167         char p_cscf_prim_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT+1];
00168         char p_cscf_sec_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT+1];
00169         int cid;
00170         int bearer_id;
00171         int im_signalling_flag;
00172         int lipa_indication;
00173         int ipv4_mtu;
00174         int wlan_offload;
00175         int local_addr_ind;
00176         int non_ip_mtu;
00177         int serving_plmn_rate_control_value;
00178         pdpcontext_params_t* next;
00179 
00180         pdpcontext_params_t() {
00181             apn[0] = '\0';
00182             local_addr[0] = '\0';
00183             local_subnet_mask[0] = '\0';
00184             gateway_addr[0] = '\0';
00185             dns_primary_addr[0] = '\0';
00186             dns_secondary_addr[0] = '\0';
00187             p_cscf_prim_addr[0] = '\0';
00188             p_cscf_sec_addr[0] = '\0';
00189             cid = -1;
00190             bearer_id = -1;
00191             im_signalling_flag = -1;
00192             lipa_indication = -1;
00193             ipv4_mtu = -1;
00194             wlan_offload = -1;
00195             local_addr_ind = -1;
00196             non_ip_mtu = -1;
00197             serving_plmn_rate_control_value = -1;
00198             next = NULL;
00199         }
00200     };
00201     typedef CellularList<pdpcontext_params_t> pdpContextList_t;
00202 
00203     /** Request registering to network.
00204      *
00205      *  @param plmn     format is in numeric format or 0 for automatic network registration
00206      *  @return         zero on success
00207      */
00208     virtual nsapi_error_t set_registration(const char *plmn = 0) = 0;
00209 
00210     /** Gets the network registration status.
00211      *
00212      * @param type      see RegistrationType values
00213      * @param status    see RegistrationStatus values
00214      * @return zero on success
00215      */
00216     virtual nsapi_error_t get_registration_status(RegistrationType type, RegistrationStatus &status) = 0;
00217 
00218     /** Set the cellular network APN and credentials
00219      *
00220      *  @param apn      Optional name of the network to connect to
00221      *  @param username Optional username for the APN
00222      *  @param password Optional password fot the APN
00223      *  @return         0 on success, negative error code on failure
00224      */
00225     virtual nsapi_error_t set_credentials(const char *apn,
00226                                           const char *username = 0, const char *password = 0) = 0;
00227 
00228     /** Set the cellular network APN and credentials
00229      *
00230      *  @param apn      Name of the network to connect to
00231      *  @param type     Authentication type to use
00232      *  @param username Optional username for the APN
00233      *  @param password Optional password fot the APN
00234      *  @return         0 on success, negative error code on failure
00235      */
00236     virtual nsapi_error_t set_credentials(const char *apn, AuthenticationType type,
00237                 const char *username = 0, const char *password = 0) = 0;
00238 
00239     /** Request attach to network.
00240      *
00241      *  @param timeout milliseconds to wait for attach response
00242      *  @return        zero on success
00243      */
00244     virtual nsapi_error_t set_attach(int timeout = 10*1000) = 0;
00245 
00246     /** Request attach status from network.
00247      *
00248      *  @param status see AttachStatus values
00249      *  @return       zero on success
00250      */
00251     virtual nsapi_error_t get_attach(AttachStatus &status) = 0;
00252 
00253     /** Get APN rate control.
00254      *
00255      *  @remark optional params are not updated if not received from network, so use good defaults
00256      *  @param reports       Additional exception reports at maximum rate reached are allowed to be sent [optional]
00257      *  @param time_unit     Uplink time unit with values 0=unrestricted, 1=minute, 2=hour, 3=day, 4=week [optional]
00258      *  @param uplink_rate   Maximum number of messages per timeUnit [optional]
00259      *  @return              zero on success
00260      */
00261     virtual nsapi_error_t get_rate_control(CellularNetwork::RateControlExceptionReports &reports,
00262         CellularNetwork::RateControlUplinkTimeUnit &time_unit, int &uplink_rate) = 0;
00263 
00264     /** Get backoff timer value
00265      *
00266      *  @param backoff_timer Backoff timer value associated with PDP APN in seconds
00267      *  @return              zero on success
00268      */
00269     virtual nsapi_error_t get_apn_backoff_timer(int &backoff_timer) = 0;
00270 
00271     /** Sets radio access technology.
00272      *
00273      *  @param op_rat Radio access technology
00274      *  @return       zero on success
00275      */
00276     virtual nsapi_error_t set_access_technology(operator_t::RadioAccessTechnology op_rat) = 0;
00277 
00278     /** Scans for operators module can reach.
00279      *
00280      *  @param operators Container of reachable operators and their access technologies
00281      *  @param ops_count Number of found operators
00282      *  @return          zero on success
00283      */
00284     virtual nsapi_error_t scan_plmn(operList_t &operators, int &ops_count) = 0;
00285 
00286     /** Set CIoT optimizations.
00287      *
00288      *  @param supported_opt Supported CIoT EPS optimizations.
00289      *  @param preferred_opt Preferred CIoT EPS optimizations.
00290      *  @return zero on success
00291      */
00292     virtual nsapi_error_t set_ciot_optimization_config(Supported_UE_Opt supported_opt,
00293                                                        Preferred_UE_Opt preferred_opt) = 0;
00294 
00295     /** Get CIoT optimizations.
00296      *
00297      *  @param supported_opt Supported CIoT EPS optimizations.
00298      *  @param preferred_opt Preferred CIoT EPS optimizations.
00299      *  @return zero on success
00300      */
00301     virtual nsapi_error_t get_ciot_optimization_config(Supported_UE_Opt& supported_opt,
00302                                                        Preferred_UE_Opt& preferred_opt) = 0;
00303 
00304     /** Start the interface. Attempts to connect to a cellular network.
00305      *
00306      *  @return 0 on success, negative error code on failure
00307      */
00308     virtual nsapi_error_t connect() = 0;
00309 
00310     /** Start the interface. Attempts to connect to a cellular network.
00311      *
00312      *  @param apn      Optional name of the network to connect to
00313      *  @param username Optional username for your APN
00314      *  @param password Optional password for your APN
00315      *  @return         0 on success, negative error code on failure
00316      */
00317     virtual nsapi_error_t connect(const char *apn,
00318                                   const char *username = 0, const char *password = 0) = 0;
00319 
00320     /**
00321      * Set the pdn type to be used
00322      *
00323      * @param stack_type the stack type to be used.
00324      *
00325      * @return NSAPI_ERROR_OK on success
00326      */
00327     virtual nsapi_error_t set_stack_type(nsapi_ip_stack_t stack_type) = 0;
00328 
00329     /**
00330      * Get the pdn type in use
00331      *
00332      * @return stack type
00333      */
00334     virtual nsapi_ip_stack_t get_stack_type() = 0;
00335 
00336     /** Get the relevant information for an active non secondary PDP context.
00337      *
00338      *  @remark optional params are not updated if not received from network.
00339      *  @param params_list  reference to linked list which is filled on successful call
00340      *  @return             0 on success, negative error code on failure
00341      */
00342     virtual nsapi_error_t get_pdpcontext_params(pdpContextList_t& params_list) = 0;
00343 
00344     /** Get extended signal quality parameters.
00345      *
00346      *  @param rxlev signal strength level
00347      *  @param ber bit error rate
00348      *  @param rscp signal code power
00349      *  @param ecno ratio of the received energy per PN chip to the total received power spectral density
00350      *  @param rsrq signal received quality
00351      *  @param rsrp signal received power
00352      *  @return NSAPI_ERROR_OK on success, negative error code on failure
00353      */
00354     virtual nsapi_error_t get_extended_signal_quality(int &rxlev, int &ber, int &rscp, int &ecno, int &rsrq, int &rsrp) = 0;
00355 
00356     /** Get signal quality parameters.
00357      *
00358      *  @param rssi signal strength level
00359      *  @param ber bit error rate
00360      *  @return NSAPI_ERROR_OK on success, negative error code on failure
00361      */
00362     virtual nsapi_error_t get_signal_quality(int &rssi, int &ber) = 0;
00363 
00364     /** Get cell id.
00365      *
00366      *  @param cell_id cell id
00367      *  @return NSAPI_ERROR_OK on success, negative error code on failure
00368      */
00369     virtual nsapi_error_t get_cell_id(int &cell_id) = 0;
00370 
00371     /** Get the last 3GPP error code
00372      *  @return see 3GPP TS 27.007 error codes
00373      */
00374     virtual int get_3gpp_error() = 0;
00375 
00376     /** Get the operator parameters.
00377      *
00378      *  @param format format of the operator field
00379      *  @param operator_params applicable operator param fields filled
00380      *  @return NSAPI_ERROR_OK on success, negative error code on failure
00381      */
00382     virtual nsapi_error_t get_operator_params(int &format, operator_t &operator_params) = 0;
00383 
00384     /** Register callback for status reporting
00385      *
00386      *  The specified status callback function will be called on status changes
00387      *  on the network. The parameters on the callback are the event type and
00388      *  event-type dependent reason parameter.
00389      *
00390      *  @param status_cb The callback for status changes
00391      */
00392     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
00393 
00394     /** Get the connection status
00395      *
00396      *  @return         The connection status according to ConnectionStatusType
00397      */
00398     virtual nsapi_connection_status_t get_connection_status() const = 0;
00399 
00400     /** Set blocking status of connect() which by default should be blocking
00401      *
00402      *  @param blocking true if connect is blocking
00403      *  @return         0 on success, negative error code on failure
00404      */
00405     virtual nsapi_error_t set_blocking(bool blocking) = 0;
00406 
00407 };
00408 
00409 } // namespace mbed
00410 
00411 #endif // CELLULAR_NETWORK_H_