CellularBase.h

00001 /* Copyright (c) 2017 ARM Limited
00002  *
00003  * Licensed under the Apache License, Version 2.0 (the "License");
00004  * you may not use this file except in compliance with the License.
00005  * You may obtain a copy of the License at
00006  *
00007  *     http://www.apache.org/licenses/LICENSE-2.0
00008  *
00009  * Unless required by applicable law or agreed to in writing, software
00010  * distributed under the License is distributed on an "AS IS" BASIS,
00011  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00012  * See the License for the specific language governing permissions and
00013  * limitations under the License.
00014  */
00015 
00016 #ifndef CELLULAR_BASE_H
00017 #define CELLULAR_BASE_H
00018 
00019 #include "netsocket/NetworkInterface.h"
00020 
00021 /** CellularBase class
00022  *
00023  *  Common interface that is shared between Cellular interfaces
00024  */
00025 class CellularBase: public NetworkInterface {
00026 
00027 public:
00028 
00029     /** Get the default Cellular interface.
00030      *
00031      * This is provided as a weak method so applications can override.
00032      * Default behaviour is to get the target's default interface, if
00033      * any.
00034      *
00035      * @return pointer to interface, if any
00036      */
00037 
00038     static CellularBase *get_default_instance();
00039 
00040     /** Set the Cellular network credentials
00041      *
00042      *  Please check documentation of connect() for default behaviour of APN settings.
00043      *
00044      *  @param apn      Access point name
00045      *  @param uname    optionally, Username
00046      *  @param pwd      optionally, password
00047      */
00048     virtual void set_credentials(const char *apn, const char *uname = 0,
00049                                  const char *pwd = 0) = 0;
00050 
00051     /** Set the pin code for SIM card
00052      *
00053      *  @param sim_pin      PIN for the SIM card
00054      */
00055     virtual void set_sim_pin(const char *sim_pin) = 0;
00056 
00057     /** Start the interface
00058      *
00059      *  Attempts to connect to a Cellular network.
00060      *
00061      *  @param sim_pin     PIN for the SIM card
00062      *  @param apn         optionally, access point name
00063      *  @param uname       optionally, Username
00064      *  @param pwd         optionally, password
00065      *  @return            NSAPI_ERROR_OK on success, or negative error code on failure
00066      */
00067     virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
00068                                   const char *uname = 0,
00069                                   const char *pwd = 0) = 0;
00070 
00071     /** Start the interface
00072      *
00073      *  Attempts to connect to a Cellular network.
00074      *  If the SIM requires a PIN, and it is not set/invalid, NSAPI_ERROR_AUTH_ERROR is returned.
00075      *
00076      *  @return            NSAPI_ERROR_OK on success, or negative error code on failure
00077      */
00078     virtual nsapi_error_t connect() = 0;
00079 
00080     /** Stop the interface
00081      *
00082      *  @return         0 on success, or error code on failure
00083      */
00084     virtual nsapi_error_t disconnect() = 0;
00085 
00086     /** Check if the connection is currently established or not
00087      *
00088      * @return true/false   If the cellular module have successfully acquired a carrier and is
00089      *                      connected to an external packet data network using PPP, isConnected()
00090      *                      API returns true and false otherwise.
00091      */
00092     virtual bool is_connected() = 0;
00093 
00094     /** Get the local IP address
00095      *
00096      *  @return         Null-terminated representation of the local IP address
00097      *                  or null if no IP address has been received
00098      */
00099     virtual const char *get_ip_address() = 0;
00100 
00101     /** Get the local network mask
00102      *
00103      *  @return         Null-terminated representation of the local network mask
00104      *                  or null if no network mask has been received
00105      */
00106     virtual const char *get_netmask() = 0;
00107 
00108     /** Get the local gateways
00109      *
00110      *  @return         Null-terminated representation of the local gateway
00111      *                  or null if no network mask has been received
00112      */
00113     virtual const char *get_gateway() = 0;
00114 
00115     virtual CellularBase *cellularBase()
00116     {
00117         return this;
00118     }
00119 
00120 protected:
00121     /** Get the target's default Cellular interface.
00122      *
00123      * This is provided as a weak method so targets can override. The
00124      * default implementation configures and returns the OnBoardModemInterface
00125      * if available.
00126      *
00127      * @return pointer to interface, if any
00128      */
00129     static CellularBase *get_target_default_instance();
00130 };
00131 
00132 #endif //CELLULAR_BASE_H
00133 
00134 /** @}*/