Skip to content

Document Socket API functions return values. #11808

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 5, 2019
Merged

Document Socket API functions return values. #11808

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions features/netsocket/DTLSSocket.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,8 @@ class DTLSSocket : public DTLSSocketWrapper {
* socket's constructor.
*
* @param stack Network stack as target for socket.
* @return 0 on success, negative error code on failure.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
* See @ref UDPSocket::open.
*/
virtual nsapi_error_t open(NetworkStack *stack)
{
Expand All @@ -93,7 +94,8 @@ class DTLSSocket : public DTLSSocketWrapper {
*
* @param host Hostname of the remote host.
* @param port Port of the remote host.
* @return 0 on success, negative error code on failure.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
* See @ref TLSSocketWrapper::connect.
*/
nsapi_error_t connect(const char *host, uint16_t port);

Expand Down
43 changes: 32 additions & 11 deletions features/netsocket/InternetDatagramSocket.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,12 @@ class InternetDatagramSocket : public InternetSocket {
* @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.
* @retval int Number of sent bytes on success.
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
* and send cannot be performed immediately.
* @retval int Other negative error codes for stack-related failures.
* See @ref NetworkStack::socket_send.
*/
virtual nsapi_size_or_error_t sendto(const char *host, uint16_t port,
const void *data, nsapi_size_t size);
Expand All @@ -55,8 +59,13 @@ class InternetDatagramSocket : public InternetSocket {
* @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.
* @retval NSAPI_ERROR_DNS_FAILURE in case the address parameter cannot
* be resolved.
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
* and send cannot be performed immediately.
* @retval int Other negative error codes for stack-related failures.
* See \ref NetworkStack::socket_send.
*/
virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
const void *data, nsapi_size_t size);
Expand All @@ -77,8 +86,12 @@ class InternetDatagramSocket : public InternetSocket {
* @param address Destination for the source address or NULL.
* @param data Destination buffer for RAW data to be received from the host.
* @param size Size of the buffer in bytes.
* @return Number of received bytes on success, negative error
* code on failure.
* @retval int Number of received bytes on success.
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
* and send cannot be performed immediately.
* @retval int Other negative error codes for stack-related failures.
* See \ref NetworkStack::socket_recv.
*/
virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
void *data, nsapi_size_t size);
Expand All @@ -88,7 +101,7 @@ class InternetDatagramSocket : public InternetSocket {
* SocketAddress must be in the address parameter.
*
* @param address The SocketAddress of the remote host.
* @return 0 on success, negative error code on failure.
* @return NSAPI_ERROR_OK on success.
*/
virtual nsapi_error_t connect(const SocketAddress &address);

Expand All @@ -102,8 +115,12 @@ class InternetDatagramSocket : public InternetSocket {
*
* @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.
* @retval int Number of sent bytes on success.
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
* and send cannot be performed immediately.
* @retval int Other negative error codes for stack-related failures.
* See \ref NetworkStack::socket_send.
*/
virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size);

Expand All @@ -119,8 +136,12 @@ class InternetDatagramSocket : public InternetSocket {
*
* @param data Pointer to 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.
* @retval int Number of received bytes on success.
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
* and send cannot be performed immediately.
* @retval int Other negative error codes for stack-related failures.
* See \ref NetworkStack::socket_recv.
*/
virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size);

Expand Down
25 changes: 19 additions & 6 deletions features/netsocket/InternetSocket.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,11 @@ class InternetSocket : public Socket {
* @note 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 (@see nsapi_types.h).
* @retval NSAPI_ERROR_OK on success.
* @retval NSAPI_ERROR_PARAMETER in case the provided stack was invalid
* or a stack was already created and socket opened successfully.
* @retval int negative error codes for stack-related failures.
* See @ref NetworkStack::socket_open.
*/
nsapi_error_t open(NetworkStack *stack);

Expand All @@ -61,28 +65,34 @@ class InternetSocket : public Socket {
/** Close any open connection, and deallocate any memory associated
* with the socket. Called from destructor if socket is not closed.
*
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
* @retval NSAPI_ERROR_OK on success.
* @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
* @retval int negative error codes for stack-related failures.
* See @ref NetworkStack::socket_close.
*/
virtual nsapi_error_t close();

/** Subscribe to an IP multicast group.
*
* @param address Multicast group IP address.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
* @return NSAPI_ERROR_OK on success, negative error code on failure (@see InternetSocket::setsockopt).
*/
int join_multicast_group(const SocketAddress &address);

/** Leave an IP multicast group.
*
* @param address Multicast group IP address.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
* @return NSAPI_ERROR_OK on success, negative error code on failure (@see InternetSocket::setsockopt).
*/
int leave_multicast_group(const SocketAddress &address);

/** Bind the socket to a port on which to receive data.
*
* @param port Local port to bind.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
* @retval NSAPI_ERROR_OK on success.
* @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
* @retval int negative error codes for stack-related failures.
* See @ref NetworkStack::socket_bind.
*/
nsapi_error_t bind(uint16_t port);

Expand All @@ -91,7 +101,10 @@ class InternetSocket : public Socket {
*
* @param address Null-terminated local address to bind.
* @param port Local port to bind.
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
* @retval NSAPI_ERROR_OK on success.
* @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
* @retval int negative error codes for stack-related failures.
* See @ref NetworkStack::socket_bind.
*/
nsapi_error_t bind(const char *address, uint16_t port);

Expand Down
35 changes: 22 additions & 13 deletions features/netsocket/Socket.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,8 @@ class Socket {
* Closes any open connection and deallocates any memory associated
* with the socket. Called from destructor if socket is not closed.
*
* @return NSAPI_ERROR_OK on success, negative error code on failure
* @return NSAPI_ERROR_OK on success.
* Negative subclass-dependent error code on failure.
*/
virtual nsapi_error_t close() = 0;

Expand All @@ -68,7 +69,8 @@ class Socket {
* a new one before attempting to reconnect.
*
* @param address The SocketAddress of the remote peer.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
* @return NSAPI_ERROR_OK on success.
* Negative subclass-dependent error code on failure.
*/
virtual nsapi_error_t connect(const SocketAddress &address) = 0;

Expand All @@ -84,8 +86,8 @@ class Socket {
*
* @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.
* @return NSAPI_ERROR_OK on success.
* Negative subclass-dependent error code on failure.
*/
virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size) = 0;

Expand All @@ -105,8 +107,8 @@ class Socket {
*
* @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
* @return Number of received bytes on success, negative, subclass-dependent
* error code on failure. If no data is available to be received
* and the peer has performed an orderly shutdown,
* recv() returns 0.
*/
Expand All @@ -125,7 +127,7 @@ class Socket {
* @param address Remote address
* @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
* @return Number of sent bytes on success, negative subclass-dependent error
* code on failure
*/
virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
Expand All @@ -148,8 +150,8 @@ class Socket {
* @param address Destination for the source address or NULL
* @param data Destination buffer for datagram received from the host
* @param size Size of the buffer in bytes
* @return Number of received bytes on success, negative error
* code on failure
* @return Number of received bytes on success, negative subclass-dependent
* error code on failure
*/
virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
void *data, nsapi_size_t size) = 0;
Expand All @@ -160,7 +162,8 @@ class Socket {
* data. If the IP address is zeroed, only the port is bound.
*
* @param address Local address to bind.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
* @return NSAPI_ERROR_OK on success, negative subclass-dependent error
* code on failure.
*/
virtual nsapi_error_t bind(const SocketAddress &address) = 0;

Expand Down Expand Up @@ -222,7 +225,9 @@ class Socket {
* @param optname Level-specific option name.
* @param optval Option value.
* @param optlen Length of the option value.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
* @retval NSAPI_ERROR_OK on success.
* @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
* @retval int Negative error code on failure, see @ref NetworkStack::setsockopt.
*/
virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0;

Expand All @@ -239,7 +244,9 @@ class Socket {
* @param optname Level-specific option name.
* @param optval Destination for option value.
* @param optlen Length of the option value.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
* @retval NSAPI_ERROR_OK on success.
* @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
* @retval int Negative error code on failure, see @ref NetworkStack::getsockopt.
*/
virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0;

Expand Down Expand Up @@ -276,7 +283,9 @@ class Socket {
* associated.
*
* @param address Pointer to SocketAddress structure.
* @return NSAPI_ERROR_OK on success, negative error code on failure.
* @retval NSAPI_ERROR_OK on success.
* @retval NSAPI_ERROR_NO_SOCKET if socket is not connected.
* @retval NSAPI_ERROR_NO_CONNECTION if the remote peer was not set.
*/
virtual nsapi_error_t getpeername(SocketAddress *address) = 0;
};
Expand Down
Loading