SOC_Read
SOC_Recv
SOC_RecvFrom

C Specification

#include <nitroWiFi/soc.h>
int SOC_Read     ( int s, void* buf, int len );
int SOC_Recv     ( int s, void* buf, int len, int flags );
int SOC_RecvFrom ( int s, void* buf, int len, int flags, void* sockFrom );

Arguments

s Socket descriptor.
buf Pointer to the receive buffer.
len Length of the receive buffer (bytes).
flags Specifies the receive status of the message. flags is 0 or the logical sum of the following values.
SOC_MSG_PEEK Peeks at the arrived message. The data is treated as unread, and the next call of SOC_Recv() or a similar function will return this data.
SOC_MSG_DONTWAIT Performs non-blocking processing. If there is no data, returns SOC_EWOULDBLOCK.
sockFrom The pointer to the socket address structures (SOCSockAddr and SOCSockAddrIn) used to obtain the name (the address) of the network communications partner.
It is important to properly initialize the len field of the socket address. (Example: sizeof(SOCSockAddrIn))

Return Values

0 or higher Number of bytes in received message.
SOC_EINVAL Invalid processing. (SSL only supports blocking calls. Blocking calls cannot be used from inside an interrupt handler, etc.)
SOC_ENETRESET Socket library is not initialized.
SOC_ENOTCONN Not connected.
SOC_EWOULDBLOCK Cannot execute until the requested operation is blocked. (There is no data or out-of-band data waiting to be received, even when SOC_O_NONBLOCK is set in the socket descriptor (or when the SOC_MSG_DONTWAIT flag is set).

Note: Additional errors may be generated and returned in future library releases. Treat all negative return values as general errors.

Description

SOC_Read(), SOC_Recv() and SOC_RecvFrom() try to read len bytes from the socket's communication partner.

SOC_Read() is the same as SOC_Recv(), except that flags is not set.

If no message is in the socket's receive buffer, SOC_Read(), SOC_Recv() and SOC_RecvFrom() will block until a message is received, unless non-blocking mode has been set in the socket descriptor with SOC_Fcntl() (or the SOC_MSG_DONTWAIT flag has not been enabled).

With SOC_SOCK_DGRAM sockets, the entire message is read in a single processs. If the message does not fit in the given buffer, the excess bytes are truncated. With SOC_SOCK_STREAM sockets, the message boundary is ignored. In this case data is returned to the user as it becomes usable.

Note: The return value becomes 0 even after the TCP connection is closed. This complies with POSIX specifications.

See Also

SOCSockAddr, SOC_Fcntl

Revision History

12/12/2005 Modified Description.
9/13/2005 Initial version.