Irie Pascal Programmer's Reference Manual

12.13.2 The sendto function

Description

The sendto 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 sendto 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 sendto function will fail, 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 constant WSAEWOULDBLOCK is declared in the system include file WinSock2.inc.

If no local name has been assigned to the socket, then a unique local name is assigned to the socket by the system. Your program can use the getsockname function to determine the local name assigned to the socket.

Connectionless Sockets

When the sendto 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 the getsockopt function 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 sendto function will fail, and if you then call the WSAGetLastError function to find out the reason for the error WSAEMSGSIZE is returned, and no data is transmitted.

Declaration

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

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

Arguments

The First Argument

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

The Second Argument

The second argument passed to the sendto 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 sendto 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 sendto 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.

If you do not wish to specify any flags then use zero as the value of this argument.

The Fifth Argument

The fifth argument passed to the sendto function usually specifies the name of the destination socket or sockets that should receive the data being sent. If the connect function has been used previously on the socket that you are sending the data through, to specify a default destination socket or default destination sockets then:

this argument can be zero (if you want to send the data to the default destination socket or sockets)
this argument can override the default destination socket or sockets, for the current datagram only, and specify the name of a destination socket, or destination sockets that should receive the data being sent.

The name specified by this argument, can be any valid name in the socket's address family, including a name with broadcast or multicast addresses. To send data to a broadcast address your program must have previously used the setsockopt function with SO_BROADCAST enabled. Otherwise, the sendto function will fail, and if you then call the WSAGetLastError function to find out the reason for the failure, the error code returned will be WSAEACCES. For TCP/IP sockets, your program can send to any multicast address.

The following rules apply when sending broadcast datagrams through sockets from the Internet Address Family:

To send a broadcast (through SOCK_DGRAM sockets only), the address in this argument should be the special IP address INADDR_BROADCAST.
Broadcast datagrams should not exceed the size at which fragmentation can occur, which implies that the data portion of the datagram (excluding headers) should not exceed 512 bytes.

This argument is ignored when sending data through connection-oriented sockets.

The Sixth Argument

The sixth argument passed to the sendto function is the length of the name of the destination socket or sockets, that was specified by the fifth argument. This argument is ignored when sending data through connection-oriented sockets.

Return Values

The sendto 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 constants SOCKET_ERROR, WSAEACCES, SO_BROADCAST, MSG_DONTROUTE, MSG_OOB, WSAEMSGSIZE, and INADDR_BROADCAST are 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.

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