udpsocket.send(address, port, data)

Description

This method sends the provided data via the target UDP socket to the specified address through the indicated port.

The destination address is provided as a dotted quad IPv4 address string, eg. "192.160.0.1", and the destination port is provided as an integer. impOS™ checks that the port number is within a valid range (between 0 and 65535, and not 67 [DHCP] or 68 [BOOTP]), and that the address has been formatted correctly and is not Internet routable (ie. local/private only: 192.168.0.0—192.168.255.255, 10.0.0.0—10.255.255.255 or 172.16.0.0—172.31.255.255). If the settings fail these checks, or the udpsocket object on which send() is called is closed, an exception will be thrown.

You should note that even if the address and port pass impOS’ checks, that does not mean that the destination is able or willing to receive the data.

If the data is not provided as a string or a blob, or is bigger than 65507 bytes, a runtime error will be thrown and the data will not be sent (and the socket, if not yet bound to a port, will remain unbound). Attempting to send data through a closed socket will also generate a runtime error.

Local Port Number

If you did not set a local port number when you created the udpsocket object (with interface.openudp()), a local port number will be set for you when data is first sent through the socket.You will not be able to determine a impOS-assigned local port number; if this is important to you, please ensure you provide a local port number when you call interface.openudp().

Rate Limits

Outgoing UDP packets are rate limited, to protect the local network and impOS connectivity. You can send up to 100 packets simultaneously in burst mode, or 25 packets a second continuously. In other words, an initial allowance of 100 packets is replenished back up to 100 at a rate of 25 per second.

Maximum Data Length

All imps have the same standard Ethernet MTU (1460 bytes), and all support IP fragmentation. Outbound datagrams larger than the MTU will be fragmented. Users should note that a fragmented datagram will be lost if any of its fragments are lost, so for maximum reliability datagrams should be smaller than the MTU.

Send Error Codes

udpsocket.send() returns an integer value which represents the status of the operation. Successful transmissions are signalled by the value 0 — all other values represent a non-throwing error. Possible error values are listed below.

Error Code Constant	Value	Description
SEND_ERROR_NOT_CONNECTED	1	Could not connect to the destination machine
SEND_ERROR_WOULDBLOCK	4	The transmission was rate-limited (see above)