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

Revisited documentation for Socket API

Christopher Haster 2016-04-19 16:52:06 -05:00 committed by Russ Butler
parent eab6d775ac
commit d43f8706d3
5 changed files with 261 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
net/NetworkSocketAPI/NetworkInterface.h
View File

@ -1,4 +1,4 @@
/* Socket
/* NetworkInterface
* Copyright (c) 2015 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
@ -134,8 +134,8 @@ protected:
/** Opens a socket
*
* Creates a socket for communication and stores it in the specified
* handle. The handle must be passed to following calls on the socket.
* Creates a network socket and stores it in the specified handle.
* The handle must be passed to following calls on the socket.
*
* A stack may have a finite number of sockets, in this case
* NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
@ -148,8 +148,8 @@ protected:
/** Close the socket
*
* Closes any open connection and deallocates any memory associated with
* the socket.
* Closes any open connection and deallocates any memory associated
* with the socket.
*
* @param handle Socket handle
* @return 0 on success, negative error code on failure
@ -174,7 +174,7 @@ protected:
*
* @param handle Socket handle
* @param backlog Number of pending connections that can be queued
* simultaneously, defaults to 1
* simultaneously
* @return 0 on success, negative error code on failure
*/
virtual int socket_listen(void *handle, int backlog) = 0;
@ -193,8 +193,9 @@ protected:
/** Accepts a connection on a TCP socket
*
* The server socket must be bound and set to listen for connections.
* On a new connection, creates a socket stores it in the specified
* handle. The handle must be passed to following calls on the socket.
* On a new connection, creates a network socket and stores it in the
* specified handle. The handle must be passed to following calls on
* the socket.
*
* A stack may have a finite number of sockets, in this case
* NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
@ -289,7 +290,7 @@ protected:
*/
virtual void socket_attach(void *handle, void (*callback)(void *), void *data) = 0;
/* Set stack-specific socked options
/* Set stack-specific socket options
*
* The setsockopt allow an application to pass stack-specific hints
* to the underlying stack. For unsupported options,

117
net/NetworkSocketAPI/Socket.h
View File

@ -24,74 +24,135 @@
*/
class Socket {
public:
/** Socket lifetime
/** Destroy a socket
*
* Closes socket if the socket is still open
*/
virtual ~Socket();
/** Open the socket
* @param iface Interface to open socket on
/** Opens a socket
*
* Creates a network socket on the specified network stack.
* Not needed if stack is passed to the socket's constructor.
*
* @param iface Network stack as target for socket
* @return 0 on success, negative error code on failure
*/
virtual int open(NetworkInterface *iface) = 0;
/** Close the socket
*
* Closes any open connection and deallocates any memory associated
* with the socket. Called from destructor if socket is not closed.
*
* @return 0 on success, negative error code on failure
*/
int close();
/** Bind a socket to a specific port
* @param port The port to listen for incoming connections on
* @return 0 on success, negative on failure.
/** Bind a specific address to a socket
*
* Binding a socket specifies the address and port on which to recieve
* data.
*
* @param port Local port to bind
* @return 0 on success, negative error code on failure.
*/
int bind(uint16_t port);
/** Bind a socket to a specific port
* @param address The null-terminated address to listen for incoming connections on
* @param port The port to listen for incoming connections on
* @return 0 on success, negative on failure.
/** Bind a specific address to a socket
*
* Binding a socket specifies the address and port on which to recieve
* data. If the IP address is zeroed, only the port is bound.
*
* @param address Null-terminated local address to bind
* @param port Local port to bind
* @return 0 on success, negative error code on failure.
*/
int bind(const char *address, uint16_t port);
/** Bind a socket to a specific port
* @param address The SocketAddress to listen for incoming connections on
* @return 0 on success, negative on failure.
/** Bind a specific address to a socket
*
* Binding a socket specifies the address and port on which to recieve
* data. If the IP address is zeroed, only the port is bound.
*
* @param address Local address to bind
* @return 0 on success, negative error code on failure.
*/
int bind(const SocketAddress &address);
/** Set blocking or non-blocking mode of the socket
* @param blocking true for blocking mode, false for non-blocking mode.
*
* 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.
*
* @param blocking True for blocking mode, false for non-blocking mode.
*/
void set_blocking(bool blocking);
/** Set timeout on a socket operation if blocking behaviour is enabled
* @param timeout timeout in ms
/** Set timeout on blocking socket operations
*
* 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 a timeout from the socket.
*
* @param timeout Timeout in milliseconds
*/
void set_timeout(unsigned int timeout);
/* Set socket options
* @param level Option level
* @param optname Option identifier
/* Set stack-specific socket options
*
* The setsockopt allow an application to pass stack-specific hints
* to the underlying stack. For unsupported options,
* NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
*
* @param level Stack-specific protocol level
* @param optname Stack-specific option identifier
* @param optval Option value
* @param optlen Length of the option value
* @return 0 on success, negative on failure
* @return 0 on success, negative error code on failure
*/
int setsockopt(int level, int optname, const void *optval, unsigned optlen);
/* Get socket options
* @param level Option level
* @param optname Option identifier
* @param optval Buffer where to write option value
/* Get stack-specific socket options
*
* The getstackopt allow an application to retrieve stack-specific hints
* from the underlying stack. For unsupported options,
* NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
*
* @param level Stack-specific protocol level
* @param optname Stack-specific option identifier
* @param optval Destination for option value
* @param optlen Length of the option value
* @return 0 on success, negative on failure
* @return 0 on success, negative error code on failure
*/
int getsockopt(int level, int optname, void *optval, unsigned *optlen);
/** 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
* 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.
*
* @param callback Function to call on state change
* @note Callback may be called in an interrupt context.
* The callback should not perform long operations
* such as recv or send calls.
*/
void attach(FunctionPointer callback);
/** 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
* 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.
*
* @param tptr Pointer to object to call method on
* @param mptr Method to call on state change
*/
template <typename T, typename M>
void attach(T *tptr, M mptr) {
attach(FunctionPointer(tptr, mptr));

54
net/NetworkSocketAPI/TCPServer.h
View File

@ -21,31 +21,57 @@
#include "TCPSocket.h"
#include "NetworkInterface.h"
/** TCP Server.
/** TCP socket server
*/
class TCPServer : public Socket {
public:
/** TCP Server lifetime
/** Create an uninitialized socket
*
* Must call open to initialize the socket on a network stack.
*/
TCPServer();
TCPServer(NetworkInterface *iface);
virtual ~TCPServer();
/** Open the socket
* @param iface Interface to open socket on
/** Create a socket on a network stack
*
* Creates and opens a socket on the specified network stack.
*
* @param iface Network stack as target for socket
*/
TCPServer(NetworkInterface *iface);
/** Opens a socket
*
* Creates a network socket on the specified network stack.
* Not needed if stack is passed to the socket's constructor.
*
* @param iface Network stack as target for socket
* @return 0 on success, negative error code on failure
*/
virtual int open(NetworkInterface *iface);
/** Start listening for incoming connections
* @param backlog Number of pending connections that can be queued up at any
* one time [Default: 1]
* @return 0 on success, negative on failure
/** Listen for connections on a TCP socket
*
* Marks the socket as a passive socket that can be used to accept
* incoming connections.
*
* @param backlog Number of pending connections that can be queued
* simultaneously, defaults to 1
* @return 0 on success, negative error code on failure
*/
int listen(int backlog=1);
int listen(int backlog = 1);
/** Accept a new connection.
* @param socket A TCPSocket instance that will handle the incoming connection.
* @return 0 on success, negative on failure.
/** Accepts a connection on a TCP socket
*
* The server socket must be bound and set to listen for connections.
* On a new connection, creates a network socket using the specified
* socket instance.
*
* By default, accept blocks until data is sent. If socket is set to
* non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
* immediately.
*
* @param socket TCPSocket instance that will handle the incoming connection.
* @return 0 on success, negative error code on failure
*/
int accept(TCPSocket *connection);
};

79
net/NetworkSocketAPI/TCPSocket.h
View File

@ -24,41 +24,80 @@
*/
class TCPSocket : public Socket {
public:
/** TCP socket lifetime
/** Create an uninitialized socket
*
* Must call open to initialize the socket on a network stack.
*/
TCPSocket();
/** Create a socket on a network stack
*
* Creates and opens a socket on the specified network stack.
*
* @param iface Network stack as target for socket
*/
TCPSocket(NetworkInterface *iface);
/** Open the socket
* @param iface Interface to open socket on
/** Opens a socket
*
* Creates a network socket on the specified network stack.
* Not needed if stack is passed to the socket's constructor.
*
* @param iface Network stack as target for socket
* @return 0 on success, negative error code on failure
*/
virtual int open(NetworkInterface *iface);
/** Connects this TCP socket to the server
* @param host The host to connect to. It can either be an IP Address
* or a hostname that will be resolved with DNS
* @param port The host's port to connect to
* @return 0 on success, negative on failure
/** 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 Host name of the remote host
* @param port Port of the remote host
* @return 0 on success, negative error code on failure
*/
int connect(const char *host, uint16_t port);
/** Connects this TCP socket to the server
* @param address SocketAddress to connect to
* @return 0 on success, negative on failure
/** Connects TCP socket to a remote host
*
* Initiates a connection to a remote server specified by the
* indicated address.
*
* @param address The SocketAddress of the remote host
* @return 0 on success, negative error code on failure
*/
int connect(const SocketAddress &address);
/** Send data to the remote host
* @param data The buffer to send to the host
* @param size The length of the buffer to send
* @return Number of written bytes on success, negative on failure
/** Send data over a TCP socket
*
* The socket must be connected to a remote host. Returns the number of
* bytes sent from the buffer.
*
* By default, send blocks until data is sent. If socket is set to
* non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
* immediately.
*
* @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
*/
int send(const void *data, unsigned size);
/** Receive data from the remote host
* @param data The buffer in which to store the data received from the host
* @param size The maximum length of the buffer
* @return Number of received bytes on success, negative on failure
/** Receive data over a TCP socket
*
* The socket must be connected to a remote host. Returns the number of
* bytes received into the buffer.
*
* By default, recv blocks until data is sent. If socket is set to
* non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
* immediately.
*
* @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
*/
int recv(void *data, unsigned size);

87
net/NetworkSocketAPI/UDPSocket.h
View File

@ -20,47 +20,86 @@
#include "Socket.h"
#include "NetworkInterface.h"
/** UDP Socket
/** UDP socket
*/
class UDPSocket : public Socket {
public:
/** UDPSocket lifetime
/** Create an uninitialized socket
*
* Must call open to initialize the socket on a network stack.
*/
UDPSocket();
/** Create a socket on a network stack
*
* Creates and opens a socket on the specified network stack.
*
* @param iface Network stack as target for socket
*/
UDPSocket(NetworkInterface *iface);
/** Open the socket
* @param iface Interface to open socket on
/** Opens a socket
*
* Creates a network socket on the specified network stack.
* Not needed if stack is passed to the socket's constructor.
*
* @param iface Network stack as target for socket
* @return 0 on success, negative error code on failure
*/
virtual int open(NetworkInterface *iface);
/** Send a packet to a remote endpoint
* @param host The host to connect to. It can either be an IP Address
* or a hostname that will be resolved with DNS
* @param port The remote port
* @param data The packet to be sent
* @param size The length of the packet to be sent
* @return The number of written bytes on success, negative on failure
/** Send a packet over a UDP socket
*
* Sends data to the specified address specified by either a domain name
* or an IP address and port. Returns the number of bytes sent from the
* buffer.
*
* By default, sendto blocks until data is sent. If socket is set to
* non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
* immediately.
*
* @param host Host name of the remote host
* @param port Port of the remote host
* @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
*/
int sendto(const char *host, uint16_t port, const void *data, unsigned size);
/** Send a packet to a remote endpoint
* @param address The remote SocketAddress
* @param data The packet to be sent
* @param size The length of the packet to be sent
* @return The number of written bytes on success, negative on failure
/** Send a packet over a UDP socket
*
* Sends data to the specified address. Returns the number of bytes
* sent from the buffer.
*
* By default, sendto blocks until data is sent. If socket is set to
* non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
* immediately.
*
* @param address The SocketAddress of the remote host
* @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
*/
int sendto(const SocketAddress &address, const void *data, unsigned size);
/** Receive a packet from a remote endpoint
* @param address Destination for the remote SocketAddress or null
* @param buffer The buffer for storing the incoming packet data
* If a packet is too long to fit in the supplied buffer,
* excess bytes are discarded
* @param size The length of the buffer
* @return The number of received bytes on success, negative on failure
/** Receive a packet over a UDP socket
*
* Receives data and stores the source address in address if address
* is not NULL. Returns the number of bytes received into the buffer.
*
* By default, recvfrom blocks until data is sent. If socket is set to
* non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
* immediately.
*
* @param address Destination for the source address or NULL
* @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
*/
int recvfrom(SocketAddress *address, void *buffer, unsigned size);
int recvfrom(SocketAddress *address, void *data, unsigned size);
};
#endif