recvfrom

This function receives a datagram and stores the source address.

int recvfrom (
SOCKET s, 
char *buf, 
int len, 
int flags, 
struct sockaddr *from, 
int *fromlen ); 

Parameters

• s
  [in] Descriptor that identifies a bound socket.
• buf
  [out] Buffer for the incoming data.
• len
  [in] Length of buf.
• flags
  [in] Not supported; set to zero.
• from
  [out] Optional pointer to a buffer that will hold the source address upon return.
• fromlen
  [in/out] Optional pointer to the size of the from buffer.

Return Values

Zero indicates that the connection has been gracefully closed. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The recvfrom function reads incoming data on both connected and unconnected sockets and captures the address from which the data was sent. The socket must not be connected. The local address of the socket must be known. For server applications, this is usually done explicitly through bind. Explicit binding is discouraged for client applications. For client applications using this function, the socket can become bound implicitly to a local address through sendto.

For stream-oriented sockets such as those of type SOCK_STREAM, a call to recvfrom returns as much information as is currently available — up to the size of the buffer supplied. The from and fromlen parameters are ignored for connection-oriented sockets.

For message-oriented sockets, data is extracted from the first queued message, up to the size of the buffer supplied. If the datagram or message is larger than the buffer supplied, the buffer is filled with the first part of the datagram, and recvfrom generates the error WSAEMSGSIZE. For unreliable protocols (for example, UDP) the excess data is lost.

If the from parameter is nonzero and the socket is not connection oriented, (type SOCK_DGRAM for example), the network address of the peer that sent the data is copied to the corresponding SOCKADDR structure. The value pointed to by fromlen is initialized to the size of this structure and is modified, on return, to indicate the actual size of the address stored in the SOCKADDR structure.

If no incoming data is available at the socket, the recvfrom call blocks and waits for data to arrive. When the socket is nonblocking, a value of SOCKET_ERROR is returned with the error value set to WSAEWOULDBLOCK. The select function can be used to determine when more data arrives.

Any data that has already been received and buffered by the transport will be copied into the supplied user buffers. In the case of a blocking socket with no data currently having been received and buffered by the transport, the call will block until data is received. For byte-stream protocols, the stack tries to return as much data as possible, subject to the supplied buffer space and amount of received data available. However, receipt of a single byte is sufficient to unblock the caller. There is no guarantee that more than a single byte will be returned. For message-oriented protocols, a full message is required to unblock the caller.

If the socket is connection oriented and the remote side has shut down the connection gracefully, the call to recvfrom will complete immediately with zero bytes received. If the connection has been reset recvfrom will fail with the error WSAECONNRESET.

Windows CE does not support the MSG_OOB value for processing out-of-band data, and does not support the MSG_PEEK value for copying data into the buffer without removing the date from the input queue.

Requirements

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

bind, recv, select, send, shutdown, socket, WSAStartup

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.