CellularInterface.h

00001 /* Copyright (c) 2019 ARM Limited
00002  * SPDX-License-Identifier: Apache-2.0
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef CELLULAR_INTERFACE_H_
00018 #define CELLULAR_INTERFACE_H_
00019 
00020 #include "netsocket/NetworkInterface.h"
00021 
00022 /**
00023  * @addtogroup cellular
00024  * @{
00025  */
00026 
00027 /** Common interface that is shared between cellular interfaces.
00028  */
00029 class CellularInterface: public NetworkInterface {
00030 
00031 public:
00032     /** Get the default cellular interface.
00033      *
00034      * This is provided as a weak method so applications can override.
00035      * Default behavior is to get the target's default interface, if
00036      * any.
00037      *
00038      * @return pointer to interface, if any.
00039      */
00040     static CellularInterface *get_default_instance();
00041 
00042     /** Set the cellular network credentials.
00043      *
00044      *  Please check documentation of connect() for default behavior of APN settings.
00045      *
00046      *  @param apn      Access point name.
00047      *  @param uname    Username (optional).
00048      *  @param pwd      Password (optional).
00049      */
00050     virtual void set_credentials(const char *apn, const char *uname = 0,
00051                                  const char *pwd = 0) = 0;
00052 
00053     /** Set the plmn. PLMN controls to what network device registers.
00054      *
00055      *  @param plmn     user to force what network to register.
00056      */
00057     virtual void set_plmn(const char *plmn) = 0;
00058 
00059     /** Set the PIN code for SIM card.
00060      *
00061      *  @param sim_pin      PIN for the SIM card.
00062      */
00063     virtual void set_sim_pin(const char *sim_pin) = 0;
00064 
00065     /** Attempt to connect to a cellular network with a PIN and credentials.
00066      *
00067      *  @param sim_pin     PIN for the SIM card.
00068      *  @param apn         Access point name (optional).
00069      *  @param uname       Username (optional).
00070      *  @param pwd         Password (optional).
00071      *  @return            NSAPI_ERROR_OK on success, or negative error code on failure.
00072      */
00073     virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
00074                                   const char *uname = 0,
00075                                   const char *pwd = 0) = 0;
00076 
00077     /** Attempt to connect to a cellular network.
00078      *
00079      *  If the SIM requires a PIN, and it is invalid or not set, NSAPI_ERROR_AUTH_ERROR is returned.
00080      *
00081      *  @return         NSAPI_ERROR_OK on success, or negative error code on failure.
00082      */
00083     virtual nsapi_error_t connect() = 0;
00084 
00085     /** Stop the interface.
00086      *
00087      *  @return         NSAPI_ERROR_OK on success, or error code on failure.
00088      */
00089     virtual nsapi_error_t disconnect() = 0;
00090 
00091     /** Check if the connection is currently established.
00092      *
00093      * @return `true` if the cellular module have successfully acquired a carrier and is
00094      *         connected to an external packet data network using PPP, `false` otherwise.
00095      */
00096     virtual bool is_connected() = 0;
00097 
00098     /** @copydoc NetworkInterface::get_ip_address */
00099     virtual nsapi_error_t get_ip_address (SocketAddress *address) = 0;
00100 
00101     MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
00102     virtual const char *get_ip_address () = 0;
00103 
00104     /** @copydoc NetworkInterface::get_netmask */
00105     virtual nsapi_error_t get_netmask (SocketAddress *address) = 0;
00106 
00107     MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
00108     virtual const char *get_netmask () = 0;
00109 
00110     /** @copydoc NetworkInterface::get_gateway */
00111     virtual nsapi_error_t get_gateway (SocketAddress *address) = 0;
00112 
00113     MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
00114     virtual const char *get_gateway () = 0;
00115 
00116     /** @copydoc NetworkInterface::cellularInterface
00117      */
00118     virtual CellularInterface *cellularInterface ()
00119     {
00120         return this;
00121     }
00122 
00123 #if !defined(DOXYGEN_ONLY)
00124 
00125 protected:
00126     /** Get the target's default cellular interface.
00127      *
00128      * This is provided as a weak method so targets can override. The
00129      * default implementation configures and returns the OnBoardModemInterface,
00130      * if available.
00131      *
00132      * @return Pointer to interface, if any.
00133      */
00134     static CellularInterface *get_target_default_instance();
00135 
00136 #endif //!defined(DOXYGEN_ONLY)
00137 
00138 public:
00139     /** Set default parameters on a cellular interface.
00140      *
00141      * A cellular interface instantiated directly or using
00142      * CellularInterface::get_default_instance() is initially unconfigured.
00143      * This call can be used to set the default parameters that would
00144      * have been set if the interface had been requested using
00145      * NetworkInterface::get_default_instance() (see nsapi JSON
00146      * configuration).
00147      */
00148     virtual void set_default_parameters();
00149 };
00150 
00151 #endif // CELLULAR_INTERFACE_H_