Contents | Prev | Next

Description

The send function sends data through a socket, and can be used on connection-oriented sockets (e.g. stream sockets) or connectionless sockets (e.g. datagram sockets). The behavior of this function may depend 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).

• Non-blocking mode disabled - If the socket has it's non-blocking mode disabled, and there is no buffer space available within the transport system to store the data to be transmitted, then the send function will block, and wait for buffer space to become available, or for the connection to be closed (connection-oriented sockets only), or for the connection to be reset (connection-oriented sockets only).
• Non-blocking mode enabled - If the socket has it's non-blocking mode enabled, then the number of bytes actually sent can be less than the amount you are trying to send, depending the availability of buffer space within the transport system to store the data to be transmitted. If there is no buffer space available within the transport system to store the data to be transmitted, then the send function will fail and 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 WSAEWOULDBLOCK. You can use the select function to find out when some buffer space becomes available. NOTE: The constants WSAEWOULDBLOCK and SOCKET_ERROR are declared in the system include file WinSock2.inc.

When the send function is used on connectionless sockets, care must be taken not to exceed the maximum packet size of the underlying provider, which can be obtained by using getsockopt to retrieve the value of socket option SO_MAX_MSG_SIZE. If the data is too long to pass atomically through the underlying protocol, the error WSAEMSGSIZE is returned, and no data is transmitted.

Declaration

The system include file WinSock2.inc contains the following declaration for the send function:

function send(s : SOCKET; buf : address; len, flags : integer) : integer;
  external dll='ws2_32.dll';

Arguments

The First Argument

The first argument passed to the send function is the socket that you want to send data through.

The Second Argument

The second argument passed to the send function is the operating system address of the buffer containing the data to be sent through 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 send function is the number of bytes of data to be sent through the socket. This argument can be zero, and this case will be treated by implementations as successful, and send will return zero as a valid value. If the socket is connectionless, a zero-length transport datagram is sent.

The Fourth Argument

The fourth argument passed to the send function can specify flags which influence the behavior of the send 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:

• MSG_DONTROUTE - Specifies that the data sent should not be subject to routing. This flag may be ignored.
• MSG_OOB - Sends OOB data through the socket.

Return Values

The send function returns the number of bytes sent through 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.

The number of bytes sent through the socket can be less than the number of bytes you are trying to send. Also the fact that data has been successfully sent does not guarantee that the data was successfully received at the other end.

Example

The following procedure is taken from the sample program wSpamFilter and uses the send function to send data through a socket. The type LineType is a cstring type. A CR/LF pair is appended to the end of the data because the server at the other end expects it, and is not a requirement for using the send function.

 //PURPOSE: Writes and logs a line to the data socket.
 //PARAMETER(s):
 //    1. buffer - Contains the data to write to the socket.
 //NOTES:
 //    A CR/LF pair is appended to the line before writing to the socket.
 procedure WriteDataSocket(var buffer : LineType);
 var
  iRet : integer;
 begin (* WriteDataSocket *)
  writeln('Writing ', buffer);
  LogMessage('OUT ' + buffer);
  buffer := buffer + CR + LF;
  iRet := send(DataSocket, addr(buffer), length(buffer), 0);
 end; (* WriteDataSocket *)

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.

Contents | Prev | Next