Description
The recvfrom function reads data from a socket and optionally retrieves the name of the socket that sent the data. The recvfrom function can be used on connection-oriented sockets (e.g. stream sockets) or connectionless sockets (e.g. datagram sockets). Before calling the recvfrom function to read data from a socket, a local name must have been assigned to the socket, this can be done explicitly with the bind function or implicitly with the sendto function.
If there is no data available to be read from the socket then what happens next depends on whether the socket has it's non-blocking mode enabled or disabled (see dealing with blocking for more information about the non-blocking mode of sockets).
When the recvfrom function is used on connection-oriented sockets, it will read all of the data waiting to be read, up to the size of the buffer you supply. If the recvfrom function is used on a socket that has been configured for in-line reception of OOB data and there is OOB data waiting to be read then only the OOB data will be read. Your program can use the ioctlsocket to determine whether there is OOB data waiting to be read.
If the socket at the other end of the connection has shut down the connection gracefully, and all of the data sent has been received, the recvfrom function will return immediately with zero bytes received. If the connection has been reset, the recvfrom function will return SOCKET_ERROR, and if you then call the WSAGetLastError function to find out the reason for the failure, the error code returned will be WSAECONNRESET. NOTE: The constants WSAECONNRESET and SOCKET_ERROR are declared in the system include file WinSock2.inc.
Connectionless Sockets
When the recvfrom function is used on connectionless sockets, it will read the first datagram waiting to be read. If the first datagram waiting to be read is larger than the buffer you supply, then only the first part of the datagram will be read (enough to fill the buffer), and the recvfrom function call will return SOCKET_ERROR as if the call failed, and if you then call the WSAGetLastError function the error code returned will be WSAEMSGSIZE. For unreliable protocols (for example, UDP) the unread part of the datagram will be lost. For reliable protocols, the entire datagram is retained until it is successfully read by calling the recvfrom function with a large enough buffer.
The name of the socket that sent the data is retrieved if you supply a buffer to store the name (see the fifth and sixth arguments below).
Declaration
The system include file WinSock2.inc contains the following declaration for the recvfrom function:
function recvfrom(s : SOCKET; buf : address; len, flags : integer;
from : address; var fromlen : integer) : integer;
external dll='ws2_32.dll';Arguments
The First Argument
The first argument passed to the recvfrom function is the socket that you want to read data from.
The Second Argument
The second argument passed to the recvfrom function is the operating system address of the buffer that you have supplied to store the data read from the socket. The type of this argument is address which means that you must use the built-in function addr to pass the operating system address of the buffer.
The Third Argument
The third argument passed to the recvfrom function is the length of the buffer you have supplied to store the data read from the socket.
The Fourth Argument
The fourth argument passed to the recvfrom function can specify flags which influence the behavior of the recvfrom function. The flags can be OR'd or added together if more than one flag is being specified. The flags which can be used are:
The Fifth Argument
The fifth argument passed to the recvfrom function is optional and should either be zero or the operating system address of a buffer to store the name of the socket that sent the data. If you are passing the operating address of a buffer then you should use the built-in function addr to get this address. This argument is ignored when reading from connection-oriented sockets.
The Sixth Argument
The sixth argument passed to the recvfrom function is the length of the buffer you supplied to store the name of the socket that sent the data. If you supply a buffer to store the name then after the recvfrom function returns successfully this argument will contain the actual length of the name stored in the buffer. This argument is ignored when reading from connection-oriented sockets.
Return Values
The recvfrom function returns the number of bytes read from the socket, if the call is successful. If the call fails the value SOCKET_ERROR is returned, and in this case you can use the WSAGetLastError function to retrieve a code that identifies the error that caused the call to fail. NOTE: The constant SOCKET_ERROR is declared in the system include file WinSock2.inc.
If the socket on the other end of the connection has gracefully closed the connection then zero is returned (connection-oriented sockets only).
Reference Information
The authoritative source of information about the WinSock2 library is the Microsoft Developers Network (MSDN). You can access the MSDN on the Microsoft website at msdn.microsoft.com.