Mistake on this page?
Report an issue in GitHub or email us
CellularInterface.h
1 /* Copyright (c) 2019 ARM Limited
2  * SPDX-License-Identifier: Apache-2.0
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef CELLULAR_INTERFACE_H_
18 #define CELLULAR_INTERFACE_H_
19 
21 
22 /**
23  * @addtogroup cellular
24  * @{
25  */
26 
27 /** Common interface that is shared between cellular interfaces.
28  */
30 
31 public:
32  /** Get the default cellular interface.
33  *
34  * This is provided as a weak method so applications can override.
35  * Default behavior is to get the target's default interface, if
36  * any.
37  *
38  * @return pointer to interface, if any.
39  */
41 
42  /** Set the cellular network credentials.
43  *
44  * Please check documentation of connect() for default behavior of APN settings.
45  *
46  * @param apn Access point name.
47  * @param uname Username (optional).
48  * @param pwd Password (optional).
49  */
50  virtual void set_credentials(const char *apn, const char *uname = 0,
51  const char *pwd = 0) = 0;
52 
53  /** Set the plmn. PLMN controls to what network device registers.
54  *
55  * @param plmn user to force what network to register.
56  */
57  virtual void set_plmn(const char *plmn) = 0;
58 
59  /** Set the PIN code for SIM card.
60  *
61  * @param sim_pin PIN for the SIM card.
62  */
63  virtual void set_sim_pin(const char *sim_pin) = 0;
64 
65  /** Attempt to connect to a cellular network with a PIN and credentials.
66  *
67  * @param sim_pin PIN for the SIM card.
68  * @param apn Access point name (optional).
69  * @param uname Username (optional).
70  * @param pwd Password (optional).
71  * @return NSAPI_ERROR_OK on success, or negative error code on failure.
72  */
73  virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
74  const char *uname = 0,
75  const char *pwd = 0) = 0;
76 
77  /** Attempt to connect to a cellular network.
78  *
79  * If the SIM requires a PIN, and it is invalid or not set, NSAPI_ERROR_AUTH_ERROR is returned.
80  *
81  * @return NSAPI_ERROR_OK on success, or negative error code on failure.
82  */
83  virtual nsapi_error_t connect() = 0;
84 
85  /** Stop the interface.
86  *
87  * @return NSAPI_ERROR_OK on success, or error code on failure.
88  */
89  virtual nsapi_error_t disconnect() = 0;
90 
91  /** Check if the connection is currently established.
92  *
93  * @return `true` if the cellular module have successfully acquired a carrier and is
94  * connected to an external packet data network using PPP, `false` otherwise.
95  */
96  virtual bool is_connected() = 0;
97 
98  /** Get the local IP address.
99  *
100  * @return Null-terminated representation of the local IP address,
101  * or null if no IP address has been received.
102  */
103  virtual const char *get_ip_address() = 0;
104 
105  /** Get the local network mask.
106  *
107  * @return Null-terminated representation of the local network mask,
108  * or null if no network mask has been received.
109  */
110  virtual const char *get_netmask() = 0;
111 
112  /** Get the local gateways.
113  *
114  * @return Null-terminated representation of the local gateway,
115  * or null if no network mask has been received.
116  */
117  virtual const char *get_gateway() = 0;
118 
119  /** @copydoc NetworkInterface::cellularBase
120  */
121  MBED_DEPRECATED_SINCE("mbed-os-5.12", "Migrated to CellularInterface")
123  {
124  return this;
125  }
126 
127  /** @copydoc NetworkInterface::cellularInterface
128  */
130  {
131  return this;
132  }
133 
134 #if !defined(DOXYGEN_ONLY)
135 
136 protected:
137  /** Get the target's default cellular interface.
138  *
139  * This is provided as a weak method so targets can override. The
140  * default implementation configures and returns the OnBoardModemInterface,
141  * if available.
142  *
143  * @return Pointer to interface, if any.
144  */
145  static CellularInterface *get_target_default_instance();
146 
147 #endif //!defined(DOXYGEN_ONLY)
148 
149 public:
150  /** Set default parameters on a cellular interface.
151  *
152  * A cellular interface instantiated directly or using
153  * CellularInterface::get_default_instance() is initially unconfigured.
154  * This call can be used to set the default parameters that would
155  * have been set if the interface had been requested using
156  * NetworkInterface::get_default_instance() (see nsapi JSON
157  * configuration).
158  */
159  virtual void set_default_parameters();
160 };
161 
162 #endif // CELLULAR_INTERFACE_H_
virtual CellularInterface * cellularInterface()
Return pointer to a CellularInterface.
virtual bool is_connected()=0
Check if the connection is currently established.
Network Interface base class.
virtual void set_credentials(const char *apn, const char *uname=0, const char *pwd=0)=0
Set the cellular network credentials.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
virtual void set_sim_pin(const char *sim_pin)=0
Set the PIN code for SIM card.
virtual const char * get_gateway()=0
Get the local gateways.
virtual const char * get_netmask()=0
Get the local network mask.
static CellularInterface * get_default_instance()
Get the default cellular interface.
Common interface that is shared between network devices.
virtual nsapi_error_t connect()=0
Attempt to connect to a cellular network.
Common interface that is shared between cellular interfaces.
virtual const char * get_ip_address()=0
Get the local IP address.
virtual nsapi_error_t disconnect()=0
Stop the interface.
virtual CellularInterface * cellularBase()
Return pointer to a CellularInterface.
virtual void set_plmn(const char *plmn)=0
Set the plmn.
virtual void set_default_parameters()
defined(DOXYGEN_ONLY)
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.