AT_CellularStack.h

00001 /*
00002  * Copyright (c) 2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef AT_CELLULAR_STACK_H_
00019 #define AT_CELLULAR_STACK_H_
00020 
00021 #include "ATHandler.h"
00022 #include "NetworkStack.h"
00023 #include "PlatformMutex.h"
00024 #include "AT_CellularDevice.h"
00025 
00026 namespace mbed {
00027 
00028 // <PDP_addr_1> and <PDP_addr_2>: each is a string type that identifies the MT in the address space applicable to the PDP.
00029 // The string is given as dot-separated numeric (0-255) parameter of the form:
00030 // a1.a2.a3.a4 for IPv4 and
00031 // a1.a2.a3.a4.a5.a6.a7.a8.a9.a10.a11.a12.a13.a14.a15.a16 for IPv6.
00032 #define PDP_IPV6_SIZE 63+1
00033 
00034 /**
00035  * Class AT_CellularStack.
00036  *
00037  * Implements NetworkStack and introduces interface for modem specific stack implementations.
00038  */
00039 class AT_CellularStack : public NetworkStack {
00040 
00041 public:
00042     AT_CellularStack(ATHandler &at, int cid, nsapi_ip_stack_t stack_type, AT_CellularDevice &device);
00043     virtual ~AT_CellularStack();
00044 
00045 public: // NetworkStack
00046 
00047     virtual nsapi_error_t get_ip_address(SocketAddress *address);
00048 
00049     MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
00050     virtual const char *get_ip_address();
00051 
00052     /**
00053      * Set PDP context ID for this stack
00054      *
00055      *  @param cid value from AT+CGDCONT, where -1 is undefined
00056      */
00057     void set_cid(int cid);
00058 
00059 protected: // NetworkStack
00060 
00061     /**
00062      * Modem specific socket stack initialization
00063      *
00064      *  @return 0 on success
00065      */
00066     virtual nsapi_error_t socket_stack_init();
00067 
00068     /**
00069       * Note: Socket_open does not actually open socket on all drivers, but that's deferred until calling `sendto`.
00070       * The reason is that IP stack implementations are very much modem specific and it's quite common that when a
00071       * socket is created (via AT commands) it must also be given remote IP address, and that is usually known
00072       * only when calling `sendto`.
00073       */
00074     virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto);
00075 
00076     virtual nsapi_error_t socket_close(nsapi_socket_t handle);
00077 
00078     virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address);
00079 
00080     virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog);
00081 
00082     virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address);
00083 
00084     virtual nsapi_error_t socket_accept(nsapi_socket_t server,
00085                                         nsapi_socket_t *handle, SocketAddress *address = 0);
00086 
00087     virtual nsapi_size_or_error_t socket_send(nsapi_socket_t handle,
00088                                               const void *data, nsapi_size_t size);
00089 
00090     virtual nsapi_size_or_error_t socket_recv(nsapi_socket_t handle,
00091                                               void *data, nsapi_size_t size);
00092 
00093     virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle, const SocketAddress &address,
00094                                                 const void *data, nsapi_size_t size);
00095 
00096     virtual nsapi_size_or_error_t socket_recvfrom(nsapi_socket_t handle, SocketAddress *address,
00097                                                   void *buffer, nsapi_size_t size);
00098 
00099     virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data);
00100 
00101 protected:
00102 
00103     class CellularSocket {
00104     public:
00105         CellularSocket() :
00106             id(-1),
00107             connected(false),
00108             proto(NSAPI_UDP ),
00109             remoteAddress("", 0),
00110             localAddress("", 0),
00111             _cb(NULL),
00112             _data(NULL),
00113             closed(false),
00114             started(false),
00115             tx_ready(false),
00116             tls_socket(false),
00117             pending_bytes(0),
00118             txfull_event(false)
00119         {
00120         }
00121         // Socket identifier, generally it will be the socket ID assigned by the
00122         // modem. In a few special cases, modems may take that as an input argument.
00123         int id;
00124         // Being connected means remote ip address and port are set
00125         bool connected;
00126         nsapi_protocol_t proto;
00127         SocketAddress remoteAddress;
00128         SocketAddress localAddress;
00129         void (*_cb)(void *);
00130         void *_data;
00131         bool closed; // socket has been closed by a peer
00132         bool started; // socket has been opened on modem stack
00133         bool tx_ready; // socket is ready for sending on modem stack
00134         bool tls_socket; // socket uses modem's internal TLS socket functionality
00135         nsapi_size_t pending_bytes; // The number of received bytes pending
00136         bool txfull_event; // socket event after wouldblock
00137     };
00138 
00139     /**
00140     * Gets maximum number of sockets modem supports
00141     */
00142     virtual int get_max_socket_count() = 0;
00143 
00144     /**
00145     * Checks if modem supports the given protocol
00146     *
00147     * @param protocol   Protocol type
00148     */
00149     virtual bool is_protocol_supported(nsapi_protocol_t protocol) = 0;
00150 
00151     /**
00152     * Implements modem specific AT command set for socket closing
00153     *
00154     * @param sock_id   Socket id
00155     */
00156     virtual nsapi_error_t socket_close_impl(int sock_id) = 0;
00157 
00158     /**
00159     * Implements modem specific AT command set for creating socket
00160     *
00161     * @param socket   Cellular socket handle
00162     */
00163     virtual nsapi_error_t create_socket_impl(CellularSocket *socket) = 0;
00164 
00165     /**
00166     * Implements modem specific AT command set for sending data
00167     *
00168     * @param socket   Cellular socket handle
00169     * @param address  The SocketAddress of the remote host
00170     * @param data     Buffer of data to send to the host
00171     * @param size     Size of the buffer in bytes
00172     * @return         Number of sent bytes on success, negative error
00173     *                 code on failure
00174     */
00175     virtual nsapi_size_or_error_t socket_sendto_impl(CellularSocket *socket, const SocketAddress &address,
00176                                                      const void *data, nsapi_size_t size) = 0;
00177 
00178     /**
00179      *  Implements modem specific AT command set for receiving data
00180      *
00181      *  @param socket   Socket handle
00182      *  @param address  Destination for the source address or NULL
00183      *  @param buffer   Destination buffer for data received from the host
00184      *  @param size     Size of the buffer in bytes
00185      *  @return         Number of received bytes on success, negative error
00186      *                  code on failure
00187      */
00188     virtual nsapi_size_or_error_t socket_recvfrom_impl(CellularSocket *socket, SocketAddress *address,
00189                                                        void *buffer, nsapi_size_t size) = 0;
00190 
00191     /**
00192      *  Find the socket handle based on the index of the socket construct
00193      *  in the socket container. Please note that this index may or may not be
00194      *  the socket id. The actual meaning of this index depends upon the modem
00195      *  being used.
00196      *
00197      *  @param index    Index of the socket construct in the container
00198      *  @return         Socket handle, NULL on error
00199      */
00200     CellularSocket *find_socket(int index);
00201 
00202     /**
00203      *  Find the index of the given CellularSocket handle. This index may or may
00204      *  not be the socket id. The actual meaning of this index depends upon the modem
00205      *  being used.
00206      */
00207     int find_socket_index(nsapi_socket_t handle);
00208 
00209     /**
00210      *  Checks if send to address is valid and if current stack type supports sending to that address type
00211      */
00212     bool is_addr_stack_compatible(const SocketAddress &addr);
00213 
00214     // socket container
00215     CellularSocket **_socket;
00216 
00217     // number of socket slots allocated in socket container
00218     int _socket_count;
00219 
00220     // IP address
00221     char _ip[PDP_IPV6_SIZE];
00222 
00223     // PDP context id
00224     int _cid;
00225 
00226     // stack type - initialised as PDP type and set accordingly after CGPADDR checked
00227     nsapi_ip_stack_t _stack_type;
00228 
00229     // IP version of send to address
00230     nsapi_version_t _ip_ver_sendto;
00231 
00232 private:
00233 
00234     int get_socket_index_by_port(uint16_t port);
00235 
00236 protected:
00237     // mutex for write/read to a _socket array, needed when multiple threads may use sockets simultaneously
00238     PlatformMutex _socket_mutex;
00239 
00240     ATHandler &_at;
00241 
00242     AT_CellularDevice &_device;
00243 };
00244 
00245 } // namespace mbed
00246 
00247 #endif // AT_CELLULAR_STACK_H_