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 /** Common interface that is shared between cellular interfaces.
00022  *  @addtogroup netsocket
00023  */
00024 class CellularBase: public NetworkInterface {
00025 
00026 public:
00027     /** Get the default cellular interface.
00028      *
00029      * This is provided as a weak method so applications can override.
00030      * Default behaviour is to get the target's default interface, if
00031      * any.
00032      *
00033      * @return pointer to interface, if any.
00034      */
00035     static CellularBase *get_default_instance();
00036 
00037     /** Set the cellular network credentials.
00038      *
00039      *  Please check documentation of connect() for default behaviour of APN settings.
00040      *
00041      *  @param apn      Access point name.
00042      *  @param uname    Username (optional).
00043      *  @param pwd      Password (optional).
00044      */
00045     virtual void set_credentials(const char *apn, const char *uname = 0,
00046                                  const char *pwd = 0) = 0;
00047 
00048     /** Set the PIN code for SIM card.
00049      *
00050      *  @param sim_pin      PIN for the SIM card.
00051      */
00052     virtual void set_sim_pin(const char *sim_pin) = 0;
00053 
00054     /** Attempt to connect to a cellular network with a PIN and credentials.
00055      *
00056      *  @param sim_pin     PIN for the SIM card.
00057      *  @param apn         Access point name (optional).
00058      *  @param uname       Username (optional).
00059      *  @param pwd         Password (optional).
00060      *  @return            NSAPI_ERROR_OK on success, or negative error code on failure.
00061      */
00062     virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
00063                                   const char *uname = 0,
00064                                   const char *pwd = 0) = 0;
00065 
00066     /** Attempt to connect to a cellular network.
00067      *
00068      *  If the SIM requires a PIN, and it is invalid or not set, NSAPI_ERROR_AUTH_ERROR is returned.
00069      *
00070      *  @return         NSAPI_ERROR_OK on success, or negative error code on failure.
00071      */
00072     virtual nsapi_error_t connect() = 0;
00073 
00074     /** Stop the interface.
00075      *
00076      *  @return         NSAPI_ERROR_OK on success, or error code on failure.
00077      */
00078     virtual nsapi_error_t disconnect() = 0;
00079 
00080     /** Check if the connection is currently established.
00081      *
00082      * @return `true` if the cellular module have successfully acquired a carrier and is
00083      *         connected to an external packet data network using PPP, `false` otherwise.
00084      */
00085     virtual bool is_connected() = 0;
00086 
00087     /** Get the local IP address.
00088      *
00089      *  @return         Null-terminated representation of the local IP address,
00090      *                  or null if no IP address has been received.
00091      */
00092     virtual const char *get_ip_address() = 0;
00093 
00094     /** Get the local network mask.
00095      *
00096      *  @return         Null-terminated representation of the local network mask,
00097      *                  or null if no network mask has been received.
00098      */
00099     virtual const char *get_netmask() = 0;
00100 
00101     /** Get the local gateways.
00102      *
00103      *  @return         Null-terminated representation of the local gateway,
00104      *                  or null if no network mask has been received.
00105      */
00106     virtual const char *get_gateway() = 0;
00107 
00108     /** @copydoc NetworkInterface::cellularBase
00109      */
00110     virtual CellularBase *cellularBase()
00111     {
00112         return this;
00113     }
00114 
00115 #if !defined(DOXYGEN_ONLY)
00116 
00117 protected:
00118     /** Get the target's default cellular interface.
00119      *
00120      * This is provided as a weak method so targets can override. The
00121      * default implementation configures and returns the OnBoardModemInterface,
00122      * if available.
00123      *
00124      * @return Pointer to interface, if any.
00125      */
00126     static CellularBase *get_target_default_instance();
00127 
00128 #endif //!defined(DOXYGEN_ONLY)
00129 };
00130 
00131 #endif //CELLULAR_BASE_H
00132 
00133 /** @}*/