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  nsapi_error_t connect() override = 0;
84 
85  /** Stop the interface.
86  *
87  * @return NSAPI_ERROR_OK on success, or error code on failure.
88  */
89  nsapi_error_t disconnect() override = 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  /** @copydoc NetworkInterface::get_ip_address */
99  nsapi_error_t get_ip_address(SocketAddress *address) override = 0;
100 
101  /** @copydoc NetworkInterface::cellularInterface
102  */
104  {
105  return this;
106  }
107 
108 #if !defined(DOXYGEN_ONLY)
109 
110 protected:
111  /** Get the target's default cellular interface.
112  *
113  * This is provided as a weak method so targets can override. The
114  * default implementation configures and returns the OnBoardModemInterface,
115  * if available.
116  *
117  * @return Pointer to interface, if any.
118  */
119  static CellularInterface *get_target_default_instance();
120 
121 #endif //!defined(DOXYGEN_ONLY)
122 
123 public:
124  /** Set default parameters on a cellular interface.
125  *
126  * A cellular interface instantiated directly or using
127  * CellularInterface::get_default_instance() is initially unconfigured.
128  * This call can be used to set the default parameters that would
129  * have been set if the interface had been requested using
130  * NetworkInterface::get_default_instance() (see nsapi JSON
131  * configuration).
132  */
133  void set_default_parameters() override;
134 };
135 
136 #endif // CELLULAR_INTERFACE_H_
nsapi_error_t get_ip_address(SocketAddress *address) override=0
Get the local IP address.
virtual bool is_connected()=0
Check if the connection is currently established.
nsapi_error_t disconnect() override=0
Stop the interface.
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:142
virtual void set_sim_pin(const char *sim_pin)=0
Set the PIN code for SIM card.
CellularInterface * cellularInterface() final
Return pointer to a CellularInterface.
nsapi_error_t connect() override=0
Attempt to connect to a cellular network.
void set_default_parameters() override
defined(DOXYGEN_ONLY)
static CellularInterface * get_default_instance()
Get the default cellular interface.
SocketAddress class.
Definition: SocketAddress.h:37
Common interface that is shared between network devices.
Common interface that is shared between cellular interfaces.
virtual void set_plmn(const char *plmn)=0
Set the plmn.
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.