class UDPSocket

Used for sending and receiving UDP datagrams

Description

To send to a remote UDP service, simply create an instance of this class and then call the sendTo() method to send datagrams. Alternatively call the connect() method to set the default destination and then use the send() method to send datagrams without specifying the remote IP and port. Replies from the remote server can be read with the recv() method. To set up a UDP server bound to a particular port, create a UDPSocket object, call the bindToPort() method, then use the recv() method to receive datagrams. Note that UDP is inherently unreliable. There is no guarantee that a packet you send will arrive at the destination, or if you send multiple packets within a short time that they will arrive in the same order as you sent them. Also, when you send a packet with sendTo() it will usually succeed even if there is no server listening on the remote port, but then at some point later on, a recv() or sendTo() will fail with an "ECONNREFUSED" error which was caused by the response to the earlier sendTo(). This unfortunate behaviour is due to the way the icmp "port unreachable" mechanism works. Also note that while a single UDP socket can send to multiple destination addresses, you cannot mix IPV6 and IPV4. After the first call to sendTo(), connect(), or bindToPort(), the address type of the socket is set (you can read it as the af variable) and any calls to send to a different address family will fail unless you close it again (which will cause it to create a new socket).

class attributes [NB. Highlighted attributes are static members] remoteip - After each recv(), this is set to the remote IP address. remoteport - After each recv(), this is set to the remote port. bind() - Binds the socket to the specified IP and port connect() - Sets the default destination of the socket sendTo() - Sends a datagram to the specified UDP host/port. send() - Sends a datagram to the specified UDP host/port. recv() - Receives a datagram close() - Closes the socket associated with this object

Functions

function bind Binds the socket to the specified IP and port Declaration:     native function bind(string host, number port) Description: This function binds the socket to a specific IP and port (although the IP can be Network.ANY which means "listen to every IP address on the machine"). Returns false and sets err.str on failure. If the address family is Network.AF_IPV4, bind will look for an IPV4 address with that name and fail if it doesn't find one. If it is Network.AF_IPV6, it will look for an IPV6 address and fail if it doesn't find one. If it is Network.AF_AUTO, it will try to find an IPV6 address, then try to find an IPV4 address, and only fail if it doesn't find either. Note: you can leave off the af parameter if you wish, and it will default to Network.AF_AUTO. Parameters:     Parameter #1: string host - The hostname or IP to listen on, or Network.ANY     Parameter #2: number port - The port number to listen on     Parameter #3: number af - The address family to use

function connect Sets the default destination of the socket Declaration:     native function connect(string host, number port) Description: This function sets the default destination of the UDP socket, which enables you to use the send() method instead of the sendTo() method. Note that it does not actually connect to the remote server or indeed even communicate with it in any way. Also note that you can still use sendTo() with any destination address and port you like after setting the defaults with connect(). Returns false and sets err.str on failure. If the address family is Network.AF_IPV4, bind will look for an IPV4 address with that name and fail if it doesn't find one. If it is Network.AF_IPV6, it will look for an IPV6 address and fail if it doesn't find one. If it is Network.AF_AUTO, it will try to find an IPV6 address, then try to find an IPV4 address, and only fail if it doesn't find either. Note: you can leave off the af parameter if you wish, and it will default to Network.AF_AUTO. Parameters:     Parameter #1: string host - The hostname or IP of the destination     Parameter #2: number port - The destination port number     Parameter #3: number af - The address family to use

function sendTo Sends a datagram to the specified UDP host/port. Declaration:     native function sendTo(string host, number port, number af, string dgram) Description: This function sends a UDP datagram to the specified port at the specified host. Returns false and sets err.str on failure. If the address family is Network.AF_IPV4, bind will look for an IPV4 address with that name and fail if it doesn't find one. If it is Network.AF_IPV6, it will look for an IPV6 address and fail if it doesn't find one. If it is Network.AF_AUTO, it will try to find an IPV6 address, then try to find an IPV4 address, and only fail if it doesn't find either. Parameters:     Parameter #1: string host - The hostname or IP of the destination     Parameter #2: number port - The destination port number     Parameter #3: number af - The address family to use     Parameter #4: string dgram - The datagram to send

function send Sends a datagram to the specified UDP host/port. Declaration:     native function sendTo(string dgram) Description: This function sends a UDP datagram to the default destination for this socket. You must have previously called connect() to set the default host and port or this will not work. Returns false and sets err.str on failure. Parameters:     Parameter #1: string dgram - The datagram to send

function recv Receives a datagram Declaration:     native function recv(number maxlen) Description: This function receives a UDP datagram sent to the port associated with this socket. You do not need to bind the socket to a known port in order to receive replies from a remote server as the kernel automatically assigns you a source port. You need to specify the maximum length of packet you expect to receive. If you set this too low packets will be truncated, however don't simply set it to a huge number because the memory used to receive the packet is allocated dynamically. If you're unsure, 8192 bytes is probably a good size. Returns an empty string and sets err.str and err.number on failure. If an actual empty packet is received, you can tell the difference because err.number will be 0. After each successful receive, the remoteip and remoteport string variables are set to the source IP and port of the received datagram. Parameters:     Parameter #1: number maxlen - The maximum length of packet to receive

function close Closes the socket associated with this object Declaration:     native function close()

Variables

string remoteip After each recv(), this is set to the remote IP address.

string remoteport After each recv(), this is set to the remote port.

Automatically generated at 8:45pm, Wednesday 08 January 2003 by feritedoc.