SOSendToMulti

Syntax

#include <cafe.h>
#include <cafe/network.h>

int SOSendToMulti(
                  int                    fd, 
                  const void            *buffer, 
                  int                    len, 
                  int                    flags,
                  const struct sockaddr *dest_addrs, 
                  int                    dest_count
                 );

Parameters

fd Descriptor of the sending socket. Only UDP sockets are supported.
buffer The message to send.
len Length of the message, in bytes. If len is greater than 1478 then it will cause an SO_EMSGSIZE error.
flags This argument supports the following value:
  • MSG_DONTROUTE: Do not use a gateway to send the packet.
dest_addrs Pointer to the array of destination addresses.
dest_count The number of destinations inside dest_addrs. The valid range is between 1 and 32.

Return Values

Upon success, returned int value will be the number of characters sent (this number must be same as len; otherwise -1 will be returned to indicate an error, since this function supports only UDP). If one of the send request fails for some reason (SO_ENOBUFS, etc.), even if requests for other destinations succeed, this function will return -1 and set errno accordingly.

Errors

These are errors generated by the socket layer; additional errors may be generated by the underlying protocol modules. For information, see SOLastError.

SO_EBUSY The socket resource manager is busy and cannot process requests. Try again later.
SO_EINVAL One of the specified arguments is invalid (e.g., dest_addrs is NULL, len is a negative value, dest_count is not in the valid range, etc.).
SO_EABORTED The operation was aborted. When a socket is closed, operations that are blocked on the socket are aborted.
SO_EUNKNOWN An unknown error occurred for some reason. Should be treated as a serious error and the corresponding socket should be closed.
SO_ELIBNOTREADY Socket library is not initialized.
SO_ENOMEM Indicates insufficient memory in the network stack. Usually a transient condition and the operation can be retried after a few seconds. If it occurs repeatedly should be treated as a serious error and the corresponding socket should be closed.
SO_ENOTSOCK The argument fd does not refer to a socket.
SO_EMSGSIZE Specified len is invalid. The valid range is between 0 and 1478.
SO_EWOULDBLOCK The socket is marked non-blocking and the requested operation would block.
SO_EPIPE The socket is unable to send any more data. This typically indicates that the socket is not connected.
SO_ENOTCONN The socket is associated with a connection-oriented protocol and has not been connected (see SOConnect and SOAccept ).
SO_EDESTADDRREQ Indicates destination address has not been specified for the send on UDP sockets.
SO_ENOBUFS Indicates insufficient packet buffers in the network stack. Usually a transient condition and the operation can be retried after a few seconds. If it occurs repeatedly should be treated as a serious error and the corresponding socket should be closed.
SO_ECONNREFUSED The socket received an ICMP destination unreachable message from other side.
SO_EADDRNOTAVAIL Returned only for UDP sends to broadcast address when network interface is not UP. Should be treated as a serious error and the corresponding socket should be closed.
SO_ENETUNREACH The specified destination is unreachable.
SO_EFAULT An abnormal operation occurred in the stack. Should be treated as a serious error and the corresponding socket should be closed.
SO_EIEIO An error occurred in the network card driver while sending out the packet. Returned only for UDP sockets. Usually a transient condition and the operation can be retried after a few seconds. If it occurs repeatedly should be treated as a serious error and the corresponding socket should be closed.
SO_EPROTOTYPE The specified socket is not UDP socket.
SO_ERANGEINVALID An unknown error occurred for some reason in the stack. Should be treated as a serious error and the corresponding socket should be closed.
SO_EAPIERROR An error occurred when processing the request in the stack. Should be treated as a serious error and the corresponding socket should be closed.

Description

This function is an extended version of the SOSendTo function. This function can send the same UDP packet to different destinations with one function call instead of needing to call the SOSendTo function several times.

No indication of failure to deliver is implicit in SOSendToMulti. Only locally detected errors are indicated by a return value of -1. When this occurs, errno is set to the error code for the error.

Below is sample code that illustrates how to use the SOSendToMulti function.

#define DESTINATION_NUM 16
#define SEND_BUFF_LEN   1024

int main()
{
    struct sockaddr_in  server_addrs[DESTINATION_NUM];
    char                send_buffer[SEND_BUFF_LEN] = {0};
    int                 fd = -1;
    int                 sent_bytes = 0;
    int                 i = 0;
    
    memset(server_addrs, 0x00, sizeof(struct sockaddr_in)*DESTINATION_NUM);

    /* Send data to Loopback on port 8080-8095 */
    for (i=0; i<DESTINATION_NUM; i++) {
        server_addrs[i].sin_family      = AF_INET;
        server_addrs[i].sin_port        = 8080+i;
        SOInetAtoN("127.0.0.1", &server_addrs[i].sin_addr);
    }

    fd = SOSocket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
    sent_bytes = SOSendToMulti(fd, (void*)send_buffer, SEND_BUFF_LEN, 0,
                               (struct sockaddr*)&server_addrs, DESTINATION_NUM);
                                  :
                                  :
                                  :
}

Do Not Call From

Callbacks Do not call this function from any callback function.
Interrupt handler Do not call this function from any interrupt handler.
Exception handler Do not call this function from any exception handler.

See Also

SOSendTo

Revision History

2013/05/09 Updated Errors (SO_EUNKNOWN, SO_EDESTADDRREQ, SO_EADDRNOTAVAIL, SO_EIEIO, SO_ERANGEINVALID and SO_EAPIERROR were added).
2012/11/15 Initial version.


CONFIDENTIAL