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