ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #9328 from SeppoTakalo/ip-core-doxygen 

Doxygen fixes for IP networking area
pull/9392/head
Martin Kojtal 2019-01-22 10:48:10 +01:00 committed by GitHub
parent bab6e2cb0b 58c2760e3f
commit 31579fe4bb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
25 changed files with 345 additions and 217 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doxyfile_options
View File

@ -859,7 +859,10 @@ EXCLUDE_PATTERNS = */tools/* \
*/ble/pal/* \
*/components/802.15.4_RF/* \
*/components/wifi/* \
*/UNITTESTS/*
*/UNITTESTS/* \
*/features/cellular/framework/AT/* \
*/features/cellular/framework/device/* \
*/features/cellular/framework/common/*
# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
# (namespaces, classes, functions, etc.) that should be excluded from the

71
features/cellular/README.md
View File

@ -2,26 +2,21 @@
This is the Github repo for Mbed cellular connectivity:
easy_cellular/
EasyCellularConnection Simplified cellular usage based on `CellularBase.h`
CellularConnectionUtil A utility class for cellular connection
framework/
API Application Programming Interface for cellular connectivity
AT AT implementation based on 3GPP TS 27.007 specification
common Common and utility sources
device Implementation of cellular device and state machine
targets Vendor specific cellular module adaptations
TESTS Cellular Greentea test
UNITTESTS Cellular unit test
**Note:** Application developers should use only the `API` folder.
## Known limitations
**Please note that this is a first release of Cellular framework and is subject to further development in future.**
Only UDP is supported when using AT commands to control sockets in an IP stack built into the cellular modem. If TCP is required, use the PPP/LWIP stack.
## Supported modules
You can find currently supported cellular modules in the `framework/targets/` folder, where we also add support for new cellular modules.
@ -30,57 +25,41 @@ You can find currently supported cellular modules in the `framework/targets/` fo
You can change cellular defaults in the `mbed_lib.json` configuration file.
You can also override cellular defaults in the `mbed_app.json` configuration file:
"config": {
"cellular_plmn": {
"help": "PLMN selection, 0=auto",
"value": 0
},
"apn": {
"help": "Access point name, e.g. internet",
"value": "\"internet\""
},
"cellular_sim_pin": {
"help": "PIN code",
"value": "\"1234\""
}
}
## Debug traces
You can define the debug tracing level in the `mbed_app.json` configuration file:
"target_overrides": {
"*": {
"mbed-trace.enable": true,
"platform.stdio-convert-newlines": true,
"platform.stdio-baud-rate": 115200,
"platform.default-serial-baud-rate": 115200
}
},
"config": {
"trace-level": {
"help": "Options are TRACE_LEVEL_ERROR,TRACE_LEVEL_WARN,TRACE_LEVEL_INFO,TRACE_LEVEL_DEBUG",
"macro_name": "MBED_TRACE_MAX_LEVEL",
"value": "TRACE_LEVEL_INFO"
}
```
"target_overrides": {
"*": {
"mbed-trace.enable": true,
"platform.stdio-convert-newlines": true,
"platform.stdio-baud-rate": 115200,
"platform.default-serial-baud-rate": 115200
}
},
"config": {
"trace-level": {
"help": "Options are TRACE_LEVEL_ERROR,TRACE_LEVEL_WARN,TRACE_LEVEL_INFO,TRACE_LEVEL_DEBUG",
"macro_name": "MBED_TRACE_MAX_LEVEL",
"value": "TRACE_LEVEL_INFO"
}
}
```
## Greentea tests
The `TESTS` folder contains Greentea tests for cellular specific classes. You need to give relevant configuration file with `--app-config` parameter, e.g.:
The `TESTS` folder contains Greentea tests for cellular specific classes. You need to give relevant configuration file with `--app-config` parameter, such as:
mbed test -n features-cellular-tests-* --app-config features\cellular\TESTS\socket\udp\template_mbed_app.json.txt -v
```
mbed test -n features-cellular-tests-* --app-config features\cellular\TESTS\socket\udp\template_mbed_app.json.txt -v
```
Note that Greentea tests use SIM PIN so you need to change that or your SIM card may get locked.
**Note:** Greentea tests use SIM PIN, so you need to change that or your SIM card may get locked.
## Unit tests
The `UNITTESTS` folder contains unit tests for cellular specific classes. Unit tests are based on the stubbing method.
You can run those tests locally by running `./run_tests` script under the `UNITTESTS/` folder.
Cellular unit tests are in Mbed OS root `UNITTESTS`. Unit tests are based on the stubbing method.
You need the following applications: `cpputest`, `gcov` and `lcov` (genhtml) for running the tests.
After you have run the `run_tests` script, you can find test results under `UNITTESTS/results` folder and line and function coverages under the `UNITTESTS/coverages` folder.
After you run the `run_tests` script, you can find test results in `UNITTESTS/results`, and line and function coverages in `UNITTESTS/coverages`.

12
features/cellular/framework/API/CellularContext.h
View File

@ -22,6 +22,12 @@
namespace mbed {
/**
* @addtogroup cellular
* @{
*/
/// CellularContext is CellularBase/NetworkInterface with extensions for cellular connectivity
class CellularContext : public CellularBase {
public:
@ -50,7 +56,7 @@ public:
Week
};
/* PDP Context information */
/// PDP Context information
struct pdpcontext_params_t {
char apn[MAX_ACCESSPOINT_NAME_LENGTH + 1];
char local_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
@ -255,6 +261,10 @@ protected: // Device specific implementations might need these so protected
const char *_pwd;
};
/**
* @}
*/
} // namespace mbed

9
features/cellular/framework/API/CellularDevice.h
View File

@ -36,6 +36,11 @@ class FileHandle;
const int MAX_PIN_SIZE = 8;
const int MAX_PLMN_SIZE = 16;
/**
* @addtogroup cellular
* @{
*/
/**
* Class CellularDevice
*
@ -294,6 +299,10 @@ private:
Callback<void(nsapi_event_t, intptr_t)> _status_cb;
};
/**
* @}
*/
} // namespace mbed
#endif // CELLULAR_DEVICE_H_

9
features/cellular/framework/API/CellularInformation.h
View File

@ -23,6 +23,11 @@
namespace mbed {
/**
* @addtogroup cellular
* @{
*/
/**
* Class CellularInformation
*
@ -83,6 +88,10 @@ public:
virtual nsapi_error_t get_serial_number(char *buf, size_t buf_size, SerialNumberType type = SN) = 0;
};
/**
* @}
*/
} // namespace mbed
#endif // CELLULAR_INFORMATION_H_

24
features/cellular/framework/API/CellularNetwork.h
View File

@ -1,5 +1,4 @@
/*
* Copyright (c) 2017, Arm Limited and affiliates.
/* Copyright (c) 2017,2018 Arm Limited and affiliates.
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License");
@ -32,18 +31,16 @@ const int MAX_OPERATOR_NAME_LONG = 16;
const int MAX_OPERATOR_NAME_SHORT = 8;
/**
* Class CellularNetwork
*
* An abstract interface for connecting to a network and getting information from it.
* @addtogroup cellular
* @{
*/
/// An abstract interface for connecting to a network and getting information from it.
class CellularNetwork {
protected:
// friend of CellularDevice so that it's the only way to close/delete this class.
friend class CellularDevice;
/**
* virtual Destructor
*/
virtual ~CellularNetwork() {}
public:
@ -112,7 +109,7 @@ public:
RAT_MAX = 11 // to reserve string array
};
// 3GPP TS 27.007 - 7.3 PLMN selection +COPS
/// 3GPP TS 27.007 - 7.3 PLMN selection +COPS
struct operator_t {
enum Status {
Unknown,
@ -141,6 +138,7 @@ public:
typedef CellularList<operator_t> operList_t;
/// Cellular operator names in numeric and alpha format
struct operator_names_t {
char numeric[MAX_OPERATOR_NAME_SHORT + 1];
char alpha[MAX_OPERATOR_NAME_LONG + 1];
@ -154,7 +152,7 @@ public:
};
typedef CellularList<operator_names_t> operator_names_list;
/* Network registering mode */
/// Network registering mode
enum NWRegisteringMode {
NWModeAutomatic = 0, // automatic registering
NWModeManual, // manual registering with plmn
@ -163,7 +161,7 @@ public:
NWModeManualAutomatic // if manual fails, fallback to automatic
};
/* Network registration information */
/// Network registration information
struct registration_params_t {
RegistrationType _type;
RegistrationStatus _status;
@ -365,6 +363,10 @@ public:
virtual nsapi_error_t get_registration_params(RegistrationType type, registration_params_t &reg_params) = 0;
};
/**
* @}
*/
} // namespace mbed
#endif // CELLULAR_NETWORK_H_

9
features/cellular/framework/API/CellularSMS.h
View File

@ -35,6 +35,11 @@ const uint16_t SMS_SIM_WAIT_TIME_MILLISECONDS = 200;
const int SMS_ERROR_MULTIPART_ALL_PARTS_NOT_READ = -5001;
/**
* @addtogroup cellular
* @{
*/
/**
* Class CellularSMS
*
@ -162,6 +167,10 @@ public:
virtual void set_extra_sim_wait_time(int sim_wait_time) = 0;
};
/**
* @}
*/
} // namespace mbed
#endif // CELLULAR_SMS_H_

7
features/cellular/framework/AT/ATHandler.h
View File

@ -53,16 +53,13 @@ enum DeviceErrorType {
DeviceErrorTypeErrorCME // AT ERROR CME
};
/* struct used when getting at response error. Defines error code and type */
/** AT response error with error code and type */
struct device_err_t {
DeviceErrorType errType;
int errCode;
};
/** Class ATHandler
*
* Class for sending AT commands and parsing AT responses.
*/
/// Class for sending AT commands and parsing AT responses.
class ATHandler {
public:

7
features/netsocket/CellularBase.h
View File

@ -13,13 +13,18 @@
* limitations under the License.
*/
/* @file CellularBase.h CellularBase */
/** @addtogroup netinterface
* @{
*/
#ifndef CELLULAR_BASE_H
#define CELLULAR_BASE_H
#include "netsocket/NetworkInterface.h"
/** Common interface that is shared between cellular interfaces.
* @addtogroup netsocket
*/
class CellularBase: public NetworkInterface {

7
features/netsocket/DNS.h
View File

@ -14,9 +14,14 @@
* limitations under the License.
*/
/** @file DNS.h Domain Name Service */
/** @addtogroup netsocket
* @{ */
#ifndef DNS_H
#define DNS_H
/** Base class for DNS provider */
class DNS {
public:
@ -95,3 +100,5 @@ public:
};
#endif
/** @} */

34
features/netsocket/DTLSSocket.h
View File

@ -1,3 +1,4 @@
/** @file DTLSSocket.h DTLSSocket */
/*
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
@ -14,6 +15,9 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** @addtogroup netsocket
* @{
*/
#ifndef DTLSSOCKET_H
#define DTLSSOCKET_H
@ -25,9 +29,16 @@
// This class requires Mbed TLS SSL/TLS client code
#if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
/**
* \brief DTLSSocket implement DTLS stream over UDP Socket.
*
* This is a helper class that uses DTLSSocketWrapper with
* internal UDPSocket.
*/
class DTLSSocket : public DTLSSocketWrapper {
public:
/** Create an uninitialized DTLS socket
/** Create an uninitialized DTLS socket.
*
* Must call open to initialize the socket on a network stack.
*/
@ -37,14 +48,14 @@ public:
*/
virtual ~DTLSSocket();
/** Create a socket on a network interface
/** Create a socket on a network interface.
*
* Creates and opens a socket on the network stack of the given
* network interface.
* If hostname is also given, user is not required to call set_hostname() later.
*
* @param stack Network stack as target for socket
* @param hostname Hostname used for certificate verification
* @param stack Network stack as target for socket.
* @param hostname Hostname used for certificate verification.
*/
template <typename S>
DTLSSocket(S *stack, const char *hostname = NULL) : DTLSSocketWrapper(&_udp_socket, hostname)
@ -53,14 +64,14 @@ public:
MBED_ASSERT(ret == NSAPI_ERROR_OK);
}
/** Opens a socket
/** Opens a socket.
*
* Creates a network socket on the network stack of the given
* network interface. Not needed if stack is passed to the
* socket's constructor.
*
* @param stack Network stack as target for socket
* @return 0 on success, negative error code on failure
* @param stack Network stack as target for socket.
* @return 0 on success, negative error code on failure.
*/
virtual nsapi_error_t open(NetworkStack *stack)
{
@ -75,14 +86,14 @@ public:
using DTLSSocketWrapper::connect;
/** Connects TCP socket to a remote host
/** Connects TCP socket to a remote host.
*
* Initiates a connection to a remote server specified by either
* a domain name or an IP address and a port.
*
* @param host Hostname of the remote host
* @param port Port of the remote host
* @return 0 on success, negative error code on failure
* @param host Hostname of the remote host.
* @param port Port of the remote host.
* @return 0 on success, negative error code on failure.
*/
nsapi_error_t connect(const char *host, uint16_t port);
@ -92,3 +103,4 @@ private:
#endif
#endif
/** @} */

14
features/netsocket/DTLSSocketWrapper.h
View File

@ -1,3 +1,4 @@
/** @file DTLSSocketWrapper.h DTLSSocketWrapper */
/*
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
@ -14,6 +15,9 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** @addtogroup netsocket
* @{
*/
#ifndef DTLSSOCKETWRAPPER_H
#define DTLSSOCKETWRAPPER_H
@ -23,8 +27,17 @@
// This class requires Mbed TLS SSL/TLS client code
#if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
/**
* \brief DTLSSocketWrapper implement DTLS stream over the existing Socket transport.
*/
class DTLSSocketWrapper : public TLSSocketWrapper {
public:
/** Create a DTLSSocketWrapper.
*
* @param transport Underlying transport socket to wrap.
* @param hostname Hostname of the remote host, used for certificate checking.
* @param control Transport control mode. See @ref control_transport.
*/
DTLSSocketWrapper(Socket *transport, const char *hostname = NULL, control_transport control = TRANSPORT_CONNECT_AND_CLOSE);
private:
static void timing_set_delay(void *ctx, uint32_t int_ms, uint32_t fin_ms);
@ -37,3 +50,4 @@ private:
#endif
#endif
/** @} */

17
features/netsocket/EthInterface.h
View File

@ -1,7 +1,4 @@
/** \addtogroup netsocket */
/** @{*/
/* EthInterface
/*
* Copyright (c) 2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
@ -17,13 +14,17 @@
* limitations under the License.
*/
/* @file EthInterface.h Common interface between Ethernet hardware */
/** \addtogroup netinterface */
/** @{*/
#ifndef ETH_INTERFACE_H
#define ETH_INTERFACE_H
#include "netsocket/NetworkInterface.h"
/** Common interface that is shared between Ethernet hardware.
/** Common interface between Ethernet hardware.
*/
class EthInterface : public virtual NetworkInterface {
public:
@ -37,7 +38,7 @@ public:
/** Get the default Ethernet interface.
*
* This is provided as a weak method so applications can override.
* This is provided as a weak method so applications can override it.
* Default behavior is to get the target's default interface, if
* any.
*
@ -50,8 +51,8 @@ protected:
/** Get the target's default Ethernet interface.
*
* This is provided as a weak method so targets can override. The
* default implementation will invoke EthernetInterface with the
* This is provided as a weak method so targets can override it. The
* default implementation invokes EthernetInterface with the
* default EMAC and default network stack, if DEVICE_EMAC is set.
*
* @return Pointer to interface, if one exists.

9
features/netsocket/MeshInterface.h
View File

@ -1,7 +1,4 @@
/** \addtogroup netsocket */
/** @{*/
/* MeshInterface
/*
* Copyright (c) 2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
@ -17,6 +14,10 @@
* limitations under the License.
*/
/* @file MeshInterface.h Mesh network interface */
/** \addtogroup netinterface */
/** @{*/
#ifndef MESH_INTERFACE_H
#define MESH_INTERFACE_H

13
features/netsocket/NetworkInterface.h
View File

@ -1,4 +1,4 @@
/* NetworkStack
/*
* Copyright (c) 2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
@ -14,6 +14,12 @@
* limitations under the License.
*/
/** @file NetworkInterface.h Network Interface base class */
/** @addtogroup netinterface
* Network Interface classes
* @{ */
#ifndef NETWORK_INTERFACE_H
#define NETWORK_INTERFACE_H
@ -33,8 +39,6 @@ class EMACInterface;
/** Common interface that is shared between network devices.
*
* @\addtogroup netsocket
* @{
*/
class NetworkInterface: public DNS {
public:
@ -346,5 +350,6 @@ protected:
#endif //!defined(DOXYGEN_ONLY)
};
/** @}*/
#endif
/** @}*/

7
features/netsocket/NetworkStack.h
View File

@ -23,6 +23,10 @@
#include "netsocket/NetworkInterface.h"
#include "DNS.h"
/** @file NetworkStack.h NetworkStack class */
/** @addtogroup netsocket
* @{ */
// Predeclared classes
class OnboardNetworkStack;
@ -32,7 +36,6 @@ class OnboardNetworkStack;
* can connect to a network over IP. By implementing the
* NetworkStack, a network stack can be used as a target
* for instantiating network sockets.
* @addtogroup netsocket
*/
class NetworkStack: public DNS {
public:
@ -421,3 +424,5 @@ NetworkStack *nsapi_create_stack(IF *iface)
#endif
/** @} */

89
features/netsocket/Socket.h
View File

@ -1,7 +1,4 @@
/** \addtogroup netsocket */
/** @{*/
/* Socket
/*
* Copyright (c) 2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
@ -17,23 +14,37 @@
* limitations under the License.
*/
/** @file Socket.h Abstract Socket interface */
/** @addtogroup netsocket
* Mbed OS Socket API
* @{ */
#ifndef SOCKET_H
#define SOCKET_H
#include "netsocket/SocketAddress.h"
#include "Callback.h"
/** Abstract socket class
/** Socket interface.
*
* This class defines the Mbed OS Socket API.
* Socket is an abstract interface for communicating with remote endpoints.
*
* This API is intended for applications and libraries instead of
* protocol-specific implementations. For example, TCPSocket
* and UDPSocket are implementations of the Socket interface.
* Socket API is intentionally not protocol-specific, and allows all protocol
* to provide the same API regardless of the underlying transport mechanism.
*/
class Socket {
public:
/** Destroy a socket.
*
* Closes socket if the socket is still open
* Closes socket if the socket is still open.
*/
virtual ~Socket() {}
/** Close the socket.
/** Closes the socket.
*
* Closes any open connection and deallocates any memory associated
* with the socket. Called from destructor if socket is not closed.
@ -44,17 +55,17 @@ public:
/** Connects socket to a remote address.
*
* Attempt to make connection on connection-mode protocol or set or reset
* Attempts to make connection on connection-mode protocol or set or reset
* the peer address on connectionless protocol.
*
* Also connectionless protocols use the connected address to filter
* Connectionless protocols also use the connected address to filter
* incoming packets for recv() and recvfrom() calls.
*
* To reset the peer address, zero initialized(default constructor) SocketAddress
* object have to be in the address parameter.
* To reset the peer address, there must be zero initialized(default constructor) SocketAddress
* objects in the address parameter.
*
* @param address The SocketAddress of the remote peer
* @return NSAPI_ERROR_OK on success, negative error code on failure
* @param address The SocketAddress of the remote peer.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t connect(const SocketAddress &address) = 0;
@ -62,14 +73,14 @@ public:
*
* The socket must be connected to a remote host before send() call.
* Returns the number of bytes sent from the buffer.
* In case of connectionless socket, send data to pre-specified remote.
* In case of connectionless socket, sends data to pre-specified remote.
*
* By default, send blocks until all data is sent. If socket is set to
* non-blocking or times out, a partial amount can be written.
* NSAPI_ERROR_WOULD_BLOCK is returned if no data was written.
*
* @param data Buffer of data to send to the host
* @param size Size of the buffer in bytes
* @param data Buffer of data to send to the host.
* @param size Size of the buffer in bytes.
* @return Number of sent bytes on success, negative error
* code on failure.
*/
@ -77,20 +88,20 @@ public:
/** Receive data from a socket.
*
* Receive data from connected socket or in case of connectionless socket
* this is equivalent of calling recvfrom(NULL, data, size).
* Receive data from connected socket, or in the case of connectionless socket,
* equivalent to calling recvfrom(NULL, data, size).
*
* If socket is connected, only packets coming from connected peer address
* are accepted.
*
* @note recv() is allowed write to data buffer even if error occurs.
* @note recv() is allowed write to data buffer even if an error occurs.
*
* By default, recv blocks until some data is received. If socket is set to
* non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK can be returned to
* indicate no data.
*
* @param data Destination buffer for data received from the host
* @param size Size of the buffer in bytes
* @param data Destination buffer for data received from the host.
* @param size Size of the buffer in bytes.
* @return Number of received bytes on success, negative error
* code on failure. If no data is available to be received
* and the peer has performed an orderly shutdown,
@ -100,9 +111,9 @@ public:
/** Send a message on a socket.
*
* The sendto() function shall send a message through a connection-mode or connectionless-mode socket.
* If the socket is connectionless-mode, the message shall be sent to the address specified.
* If the socket is connection-mode, address shall be ignored.
* The sendto() function sends a message through a connection-mode or connectionless-mode socket.
* If the socket is a connectionless-mode socket, the message is sent to the address specified.
* If the socket is a connected-mode socket, address is ignored.
*
* By default, sendto blocks until data is sent. If socket is set to
* non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
@ -145,7 +156,7 @@ public:
* Binding a socket specifies the address and port on which to receive
* data. If the IP address is zeroed, only the port is bound.
*
* @param address Local address to bind
* @param address Local address to bind.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t bind(const SocketAddress &address) = 0;
@ -154,7 +165,7 @@ public:
*
* Initially all sockets are in blocking mode. In non-blocking mode
* blocking operations such as send/recv/accept return
* NSAPI_ERROR_WOULD_BLOCK if they can not continue.
* NSAPI_ERROR_WOULD_BLOCK if they cannot continue.
*
* set_blocking(false) is equivalent to set_timeout(0)
* set_blocking(true) is equivalent to set_timeout(-1)
@ -168,7 +179,7 @@ public:
* Initially all sockets have unbounded timeouts. NSAPI_ERROR_WOULD_BLOCK
* is returned if a blocking operation takes longer than the specified
* timeout. A timeout of 0 removes the timeout from the socket. A negative
* value give the socket an unbounded timeout.
* value gives the socket an unbounded timeout.
*
* set_timeout(0) is equivalent to set_blocking(false)
* set_timeout(-1) is equivalent to set_blocking(true)
@ -179,17 +190,17 @@ public:
/** Register a callback on state change of the socket.
*
* The specified callback will be called on state changes such as when
* the socket can recv/send/accept successfully and on when an error
* The specified callback is called on state changes, such as when
* the socket can receive/send/accept successfully and when an error
* occurs. The callback may also be called spuriously without reason.
*
* The callback may be called in an interrupt context and should not
* perform expensive operations such as recv/send calls.
* perform expensive operations such as receive/send calls.
*
* Note! This is not intended as a replacement for a poll or attach-like
* asynchronous api, but rather as a building block for constructing
* such functionality. The exact timing of when the registered function
* is called is not guaranteed and susceptible to change.
* asynchronous API, but rather as a building block for constructing
* such functionality. The exact timing of the registered function
* is not guaranteed and susceptible to change.
*
* @param func Function to call on state change.
*/
@ -232,15 +243,15 @@ public:
/** Accepts a connection on a socket.
*
* The server socket must be bound and set to listen for connections.
* On a new connection, returns connected network socket which user is expected to call close()
* and that deallocates the resources. Referencing a returned pointer after a close()
* On a new connection, returns connected network socket to call close()
* that deallocates the resources. Referencing a returned pointer after a close()
* call is not allowed and leads to undefined behavior.
*
* By default, accept blocks until incoming connection occurs. If socket is set to
* non-blocking or times out, error is set to NSAPI_ERROR_WOULD_BLOCK.
*
* @param error pointer to storage of the error value or NULL
* @return pointer to a socket
* @param error Pointer to storage of the error value or NULL.
* @return Pointer to a socket.
*/
virtual Socket *accept(nsapi_error_t *error = NULL) = 0;
@ -250,8 +261,8 @@ public:
* incoming connections.
*
* @param backlog Number of pending connections that can be queued
* simultaneously, defaults to 1
* @return NSAPI_ERROR_OK on success, negative error code on failure
* simultaneously, defaults to 1.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
*/
virtual nsapi_error_t listen(int backlog = 1) = 0;

14
features/netsocket/SocketAddress.h
View File

@ -1,5 +1,4 @@
/* SocketAddress
/*
* Copyright (c) 2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
@ -15,6 +14,10 @@
* limitations under the License.
*/
/** @file SocketAddress.h SocketAddress class */
/** \addtogroup netsocket
* @{*/
#ifndef SOCKET_ADDRESS_H
#define SOCKET_ADDRESS_H
@ -25,11 +28,9 @@
class NetworkStack;
class NetworkInterface;
/** SocketAddress class
*
* Representation of an IP address and port pair.
* @addtogroup netsocket
*/
class SocketAddress {
public:
@ -40,6 +41,7 @@ public:
*
* On failure, the IP address and port will be set to zero
*
* @tparam S Type of the Network stack
* @param stack Network stack to use for DNS resolution
* @param host Hostname to resolve
* @param port Optional 16-bit port, defaults to 0
@ -58,7 +60,7 @@ public:
/** Create a SocketAddress from a raw IP address and port
*
* To construct from a host name, use NetworkInterface::gethostbyname
* @note To construct from a host name, use NetworkInterface::gethostbyname
*
* @param addr Raw IP address
* @param port Optional 16-bit port, defaults to 0
@ -125,7 +127,7 @@ public:
*/
const char *get_ip_address() const;
/* Get the raw IP bytes
/** Get the raw IP bytes
*
* @return Raw IP address in big-endian order
*/

10
features/netsocket/TCPServer.h
View File

@ -1,5 +1,4 @@
/* TCPServer
/*
* Copyright (c) 2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
@ -15,6 +14,10 @@
* limitations under the License.
*/
/** @file TCPServer.h Deprecated TCPServer class */
/** \addtogroup netsocket
* @{*/
#ifndef TCPSERVER_H
#define TCPSERVER_H
@ -26,7 +29,6 @@
/** TCP socket server
* @addtogroup netsocket
*/
class TCPServer : public TCPSocket {
public:
@ -82,3 +84,5 @@ public:
};
#endif
/** @} */

9
features/netsocket/TCPSocket.h
View File

@ -1,7 +1,4 @@
/** \addtogroup netsocket */
/** @{*/
/* TCPSocket
/*
* Copyright (c) 2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
@ -17,6 +14,10 @@
* limitations under the License.
*/
/** @file TCPSocket.h TCPSocket class */
/** \addtogroup netsocket
* @{*/
#ifndef TCPSOCKET_H
#define TCPSOCKET_H

33
features/netsocket/TLSSocket.h
View File

@ -1,3 +1,4 @@
/** @file TLSSocket.h TLSSocket */
/*
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
@ -14,6 +15,9 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** @addtogroup netsocket
* @{
*/
#ifndef _MBED_HTTPS_TLS_TCP_SOCKET_H_
#define _MBED_HTTPS_TLS_TCP_SOCKET_H_
@ -31,11 +35,15 @@
#if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
/**
* \brief TLSSocket a wrapper around TCPSocket for interacting with TLS servers
* \brief TLSSocket is a wrapper around TCPSocket for interacting with TLS servers.
*
* TLSSocket uses the TLSSocketWrapper with internal TCP socket.
* This is a helper for creating commonly used TLS connections over TCP.
*
*/
class TLSSocket : public TLSSocketWrapper {
public:
/** Create an uninitialized socket
/** Create an uninitialized socket.
*
* Must call open to initialize the socket on a network stack.
*/
@ -45,17 +53,16 @@ public:
*/
virtual ~TLSSocket();
/** Opens a socket
/** Opens a socket.
*
* Creates a network socket on the network stack of the given
* network interface. Not needed if stack is passed to the
* socket's constructor.
* network interface.
*
* @note TLSSocket cannot be reopened after closing. It should be destructed to
* clear internal TLS memory structures.
*
* @param stack Network stack as target for socket
* @return 0 on success, negative error code on failure
* @param stack Network stack as target for socket.
* @return 0 on success, negative error code on failure.
*/
virtual nsapi_error_t open(NetworkStack *stack)
{
@ -70,14 +77,14 @@ public:
using TLSSocketWrapper::connect;
/** Connects TCP socket to a remote host
/** Connects TCP socket to a remote host.
*
* Initiates a connection to a remote server specified by either
* a domain name or an IP address and a port.
* a domain name or an IP address and port.
*
* @param host Hostname of the remote host
* @param port Port of the remote host
* @return 0 on success, negative error code on failure
* @param host Hostname of the remote host.
* @param port Port of the remote host.
* @return 0 on success, negative error code on failure.
*/
nsapi_error_t connect(const char *host, uint16_t port);
@ -87,3 +94,5 @@ private:
#endif // MBEDTLS_SSL_CLI_C
#endif // _MBED_HTTPS_TLS_TCP_SOCKET_H_
/** @} */

111
features/netsocket/TLSSocketWrapper.h
View File

@ -1,3 +1,4 @@
/** @file TLSSocketWrapper.h TLSSocketWrapper */
/*
* Copyright (c) 2018 ARM Limited
* SPDX-License-Identifier: Apache-2.0
@ -14,6 +15,9 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** @addtogroup netsocket
* @{
*/
#ifndef _MBED_HTTPS_TLS_SOCKET_WRAPPER_H_
#define _MBED_HTTPS_TLS_SOCKET_WRAPPER_H_
@ -31,57 +35,68 @@
#if defined(MBEDTLS_SSL_CLI_C) || defined(DOXYGEN_ONLY)
/**
* \brief TLSSocket a wrapper around Socket for interacting with TLS servers
* TLSSocket is a wrapper around Socket for interacting with TLS servers.
*
* TLSSocketWrapper can use any Socket as a transport. After
* completing the TLS handshake, it can be used as any Socket would be used.
*
*/
class TLSSocketWrapper : public Socket {
public:
/** Transport modes */
enum control_transport {
TRANSPORT_KEEP,
TRANSPORT_CONNECT_AND_CLOSE,
TRANSPORT_CONNECT,
TRANSPORT_CLOSE,
TRANSPORT_KEEP, /**< Doesn't call connect() or close() on transport socket */
TRANSPORT_CONNECT_AND_CLOSE, /**< Does call connect() and close() on transport socket */
TRANSPORT_CONNECT, /**< Does call only connect() on transport socket */
TRANSPORT_CLOSE, /**< Does call close() on transport socket */
};
/* Create a TLSSocketWrapper
/** Create a TLSSocketWrapper.
*
* @param transport Underlying transport socket to wrap
* @param hostname Hostname of the remote host, used for certificate checking
* @param transport Underlying transport socket to wrap.
* @param hostname Hostname of the remote host, used for certificate checking.
* @param control Transport control mode. See @ref control_transport.
*/
TLSSocketWrapper(Socket *transport, const char *hostname = NULL, control_transport control = TRANSPORT_CONNECT_AND_CLOSE);
/** Destroy a socket wrapper
/** Destroy a socket wrapper.
*
* Closes socket wrapper if the socket wrapper is still open
* Closes socket wrapper if the socket wrapper is still open.
*/
virtual ~TLSSocketWrapper();
/** Set hostname.
*
* TLSSocket requires hostname that is used to verify the certificate.
* TLSSocket requires hostname used to verify the certificate.
* If hostname is not given in constructor, this function must be used before
* starting the TLS handshake.
*
* @param hostname Hostname of the remote host, used for certificate checking.
*/
void set_hostname(const char *hostname);
/** Sets the certification of Root CA.
*
* @param root_ca Root CA Certificate in any mbed-TLS supported format.
* @param root_ca Root CA Certificate in any Mbed TLS-supported format.
* @param len Length of certificate (including terminating 0 for PEM).
* @return 0 on success, negative error code on failure.
*/
nsapi_error_t set_root_ca_cert(const void *root_ca, size_t len);
/** Sets the certification of Root CA.
*
* @param root_ca_pem Root CA Certificate in PEM format
* @param root_ca_pem Root CA Certificate in PEM format.
* @return 0 on success, negative error code on failure.
*/
nsapi_error_t set_root_ca_cert(const char *root_ca_pem);
/** Sets client certificate, and client private key.
*
* @param client_cert client certification in PEM or DER format.
* @param client_cert_len certificate size including the terminating null byte for PEM data.
* @param client_private_key_pem client private key in PEM or DER format
* @param client_private_key_len key size including the terminating null byte for PEM data
* @param client_cert Client certification in PEM or DER format.
* @param client_cert_len Certificate size including the terminating null byte for PEM data.
* @param client_private_key_pem Client private key in PEM or DER format.
* @param client_private_key_len Key size including the terminating null byte for PEM data
* @return 0 on success, negative error code on failure.
*/
nsapi_error_t set_client_cert_key(const void *client_cert, size_t client_cert_len,
const void *client_private_key_pem, size_t client_private_key_len);
@ -90,28 +105,28 @@ public:
*
* @param client_cert_pem Client certification in PEM format.
* @param client_private_key_pem Client private key in PEM format.
* @return 0 on success, negative error code on failure.
*/
nsapi_error_t set_client_cert_key(const char *client_cert_pem, const char *client_private_key_pem);
/** Send data over a TLS socket
/** Send data over a TLS socket.
*
* The socket must be connected to a remote host. Returns the number of
* bytes sent from the buffer.
*
* @param data Buffer of data to send to the host
* @param size Size of the buffer in bytes
* @return Number of sent bytes on success, negative error
* code on failure
* @param data Buffer of data to send to the host.
* @param size Size of the buffer in bytes.
* @return Number of sent bytes on success, negative error code on failure.
*/
virtual nsapi_error_t send(const void *data, nsapi_size_t size);
/** Receive data over a TLS socket
/** Receive data over a TLS socket.
*
* The socket must be connected to a remote host. Returns the number of
* bytes received into the buffer.
*
* @param data Destination buffer for data received from the host
* @param size Size of the buffer in bytes
* @param data Destination buffer for data received from the host.
* @param size Size of the buffer in bytes.
* @return Number of received bytes on success, negative error
* code on failure. If no data is available to be received
* and the peer has performed an orderly shutdown,
@ -136,64 +151,73 @@ public:
virtual nsapi_error_t getpeername(SocketAddress *address);
#if defined(MBEDTLS_X509_CRT_PARSE_C) || defined(DOXYGEN_ONLY)
/** Get own certificate directly from Mbed TLS
* @return internal Mbed TLS X509 structure
/** Get own certificate directly from Mbed TLS.
*
* @return Internal Mbed TLS X509 structure.
*/
mbedtls_x509_crt *get_own_cert();
/** Set own certificate directly to Mbed TLS
/** Set own certificate directly to Mbed TLS.
*
* @param crt Mbed TLS X509 certificate chain.
* @return error code from mbedtls_ssl_conf_own_cert()
* @return error code from mbedtls_ssl_conf_own_cert().
*/
int set_own_cert(mbedtls_x509_crt *crt);
/** Get CA chain structure.
*
* @return Mbed TLS X509 certificate chain.
*/
mbedtls_x509_crt *get_ca_chain();
/** Set CA chain directly to Mbed TLS
/** Set CA chain directly to Mbed TLS.
*
* @param crt Mbed TLS X509 certificate chain.
*/
void set_ca_chain(mbedtls_x509_crt *crt);
#endif
/** Get internal Mbed TLS configuration structure
* @return Mbed TLS SSL config
/** Get internal Mbed TLS configuration structure.
*
* @return Mbed TLS SSL config.
*/
mbedtls_ssl_config *get_ssl_config();
/** Override Mbed TLS configuration.
* @param conf Mbed TLS SSL configuration structure
*
* @param conf Mbed TLS SSL configuration structure.
*/
void set_ssl_config(mbedtls_ssl_config *conf);
/** Get internal Mbed TLS context structure.
* @return SSL context
*
* @return SSL context.
*/
mbedtls_ssl_context *get_ssl_context();
protected:
/** Initiates TLS Handshake
#ifndef DOXYGEN_ONLY
/** Initiates TLS Handshake.
*
* Initiates a TLS handshake to a remote peer
* Underlying transport socket should already be connected
* Initiates a TLS handshake to a remote peer.
* Underlying transport socket should already be connected.
*
* Root CA certification must be set by set_ssl_ca_pem() before
* call this function.
* calling this function.
*
* For non-blocking purposes, this functions needs to know whether this
* was a first call to Socket::connect() API so that NSAPI_ERROR_INPROGRESS
* does not happen twice.
*
* @parameter first_call is this a first call to Socket::connect() API.
* @return 0 on success, negative error code on failure
* @param first_call is this a first call to Socket::connect() API.
* @return 0 on success, negative error code on failure
*/
nsapi_error_t start_handshake(bool first_call);
bool is_handshake_started() const;
void event();
#endif
@ -201,20 +225,20 @@ private:
/** Continue already initialized handshake */
nsapi_error_t continue_handshake();
/**
* Helper for pretty-printing mbed TLS error codes
* Helper for pretty-printing Mbed TLS error codes
*/
static void print_mbedtls_error(const char *name, int err);
#if MBED_CONF_TLS_SOCKET_DEBUG_LEVEL > 0
/**
* Debug callback for mbed TLS
* Debug callback for Mbed TLS
* Just prints on the USB serial port
*/
static void my_debug(void *ctx, int level, const char *file, int line,
const char *str);
/**
* Certificate verification callback for mbed TLS
* Certificate verification callback for Mbed TLS
* Here we only use it to display information on each cert in the chain
*/
static int my_verify(void *data, mbedtls_x509_crt *crt, int depth, uint32_t *flags);
@ -261,3 +285,4 @@ private:
#endif /* MBEDTLS_SSL_CLI_C */
#endif // _MBED_HTTPS_TLS_SOCKET_WRAPPER_H_
/** @} */

30
features/netsocket/WiFiInterface.h
View File

@ -1,5 +1,4 @@
/* WiFiInterface
/*
* Copyright (c) 2015 - 2016 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
@ -15,6 +14,11 @@
* limitations under the License.
*/
/** @file WifiInterface.h Common interface between Wi-Fi devices */
/** @addtogroup netinterface
* @{
*/
#ifndef WIFI_INTERFACE_H
#define WIFI_INTERFACE_H
@ -22,15 +26,13 @@
#include "netsocket/NetworkInterface.h"
#include "netsocket/WiFiAccessPoint.h"
/** Common interface that is shared between Wi-Fi devices.
*
* @addtogroup netsocket
/** Common interface between Wi-Fi devices.
*/
class WiFiInterface: public virtual NetworkInterface {
public:
/** Get the default Wi-Fi interface.
*
* This is provided as a weak method so applications can override.
* This is provided as a weak method so applications can override it.
* Default behavior is to get the target's default interface, if
* any.
*
@ -51,7 +53,7 @@ public:
/** Set the Wi-Fi network channel.
*
* @param channel Channel on which the connection is to be made, or 0 for any (Default: 0).
* @param channel Channel to make the connection, or 0 for any (Default: 0).
* @return NSAPI_ERROR_OK on success, or error code on failure.
*/
virtual nsapi_error_t set_channel(uint8_t channel) = 0;
@ -68,7 +70,7 @@ public:
* @param ssid Name of the network to connect to.
* @param pass Security passphrase to connect to the network.
* @param security Type of encryption for connection (Default: NSAPI_SECURITY_NONE).
* @param channel Channel on which the connection is to be made, or 0 for any (Default: 0).
* @param channel Channel to make the connection, or 0 for any (Default: 0).
* @return NSAPI_ERROR_OK on success, or error code on failure.
*/
virtual nsapi_error_t connect(const char *ssid, const char *pass,
@ -89,13 +91,15 @@ public:
/** Scan for available networks.
*
* This function will block. If the count is 0, function will only return count of available networks, so that
* user can allocated necessary memory. If the count is grater than 0 and the a \p res is not NULL it'll be populated
* with discovered networks up to value of count.
* @note This is a blocking function.
*
* If the \p count is 0, the function only returns the number of available networks.
* If the \p count is greater than 0 and the \p res is not NULL, the array of discovered APs is populated
* with discovered networks up to the value of the \p count.
*
* @param res Pointer to allocated array to store discovered APs.
* @param count Size of allocated res array, or 0 to only count available APs.
* @return Number of entries in res, or if count was 0 number of available networks.
* @return Number of entries in res, or if count was 0, number of available networks.
* Negative on error (@see nsapi_types.h for nsapi_error).
*/
virtual nsapi_size_or_error_t scan(WiFiAccessPoint *res, nsapi_size_t count) = 0;
@ -112,7 +116,7 @@ protected:
/** Get the target's default Wi-Fi interface.
*
* This is provided as a weak method so targets can override. The
* This is provided as a weak method so targets can override it. The
* default implementation returns NULL.
*
* @return pointer to interface, if any.

9
features/netsocket/nsapi_dns.h
View File

@ -1,7 +1,4 @@
/** \addtogroup netsocket */
/** @{*/
/* nsapi_dns.h
/*
* Original work Copyright (c) 2013 Henry Leinen (henry[dot]leinen [at] online [dot] de)
* Modified work Copyright (c) 2015 ARM Limited
*
@ -17,6 +14,10 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** \addtogroup netsocket */
/** @{*/
#ifndef NSAPI_DNS_H
#define NSAPI_DNS_H

3
tools/test/travis-ci/doxy-spellchecker/ignore.en.pws
View File

@ -92,3 +92,6 @@ _doxy_
sa
tparam
retarget
TCPSocket
UDPSocket
Socket