From 6bf0611748e1f49ff343ebea56b33d72c5a2b022 Mon Sep 17 00:00:00 2001 From: Seppo Takalo Date: Thu, 30 Nov 2017 10:03:20 -0600 Subject: [PATCH] Clarify TCPSocket::recv() and UDPSocket::recvfrom() documentation. --- features/netsocket/TCPSocket.h | 4 +++- features/netsocket/UDPSocket.h | 15 ++++++++------- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/features/netsocket/TCPSocket.h b/features/netsocket/TCPSocket.h index 7b12ba3a9e..39c547d7af 100644 --- a/features/netsocket/TCPSocket.h +++ b/features/netsocket/TCPSocket.h @@ -111,7 +111,9 @@ public: * @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 + * code on failure. If no data is available to be received + * and the peer has performed an orderly shutdown, + * recv() returns 0. */ nsapi_size_or_error_t recv(void *data, nsapi_size_t size); diff --git a/features/netsocket/UDPSocket.h b/features/netsocket/UDPSocket.h index 02f39e9ed6..a4570fa80e 100644 --- a/features/netsocket/UDPSocket.h +++ b/features/netsocket/UDPSocket.h @@ -94,17 +94,18 @@ public: nsapi_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size); - /** Receive a packet over a UDP socket + /** Receive a datagram 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. + * Receives a datagram and stores the source address in address if address + * is not NULL. Returns the number of bytes written into the buffer. If the + * datagram is larger than the buffer, the excess data is silently discarded. * - * 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. + * By default, recvfrom blocks until a datagram is received. If socket is set to + * non-blocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK + * is returned. * * @param address Destination for the source address or NULL - * @param data Destination buffer for data received from the host + * @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