Description
The recv function reads data from a socket, and can be used on connection-oriented sockets (e.g. stream sockets) or connectionless sockets (e.g. datagram sockets).
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 recv 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 recv 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 recv function will return immediately with zero bytes received. If the connection has been reset, the recv 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 recv 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 recv 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 recv function with a large enough buffer.
Before using the recv function on connectionless sockets the connect function must be called to specify the name of the source socket or sockets from which datagrams will be read. The recv function will silently discard datagrams from all sockets except the source socket or sockets.
Declaration
The system include file WinSock2.inc contains the following declaration for the recv function:
function recv(s : SOCKET; buf : address; len, flags : integer) : integer;
external dll='ws2_32.dll';Arguments
The First Argument
The first argument passed to the recv function is the socket that you want to read data from.
The Second Argument
The second argument passed to the recv 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 recv 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 recv function can specify flags which influence the behavior of the recv 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 recv 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).
Example
The following function is taken from the sample program wSpamFilter and uses the recv function to read data from a socket. The function SocketReadyForReading is defined by the sample program and checks whether there is data waiting to be read from a socket. The type LineType is a cstring type.
//PURPOSE: Reads data from a socket
//PARAMETER(S):
// 1. buffer - used to store the data read
// 2. wMaxWait - maximum number of ms to wait for the socket to become ready.
//GLOBAL(s):
// 1. DataSocket - The socket to read from.
//NOTES:
// The socket is checked to make sure it is ready for reading
// before attempting to read. This makes it unlikely that the application
// will become blocked waiting for data to come in.
procedure ReadDataSocket(var buffer : LineType; wMaxWait : word);
var
iDataRead : integer;
begin (* ReadDataSocket *)
buffer := '';
if SocketReadyForReading(DataSocket, wMaxWait) then
begin
writeln('Reading...');
LogMessage('Reading...');
iDataRead := recv(DataSocket, addr(buffer), sizeof(buffer)-2, 0);
if iDataRead=SOCKET_ERROR then
FatalSocketError('Call to recv failed')
else if iDataRead > 0 then
buffer[iDataRead+1] := chr(0);
end
end; (* ReadDataSocket *)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.