hypermedia.net : : UDP

hypermedia.net index

Name UDP

Examples

None available

Description

Create and manage unicast, broadcast or multicast socket to send and receive datagram packets over the network.

The socket type is define at his initialyzation by the passed IP address. To reach a host (interface) within a network, you need to specified the kind of address:

An unicast address refer to a unique host within a subnet.
A broadcast address allow you to call every host within a subnet.
A multicast address allows to call a specific group of hosts within the subnet. A multicast group is specified by a IP address in the range 224.0.0.0 (reserved, should not be used) to 239.255.255.255 inclusive, and by a standard UDP port number.
notes: the complete reference of special multicast addresses should be found in the latest available version of the "Assigned Numbers RFC"

A packet sent to a unicast or broadcast address is only delivered to the host identified by that address. To the contrary, when packet is send to a multicast address, all interfaces identified by that address receive the data .

To perform actions on receive and/or timeout events, you must implement specific method(s) in your code. This method will be automatically called when the socket receive incoming data or a timeout event. By default, the "receive handler" is typically receive(byte[] data) but you can retrieve more informations about the datagram packet, see {@link UDP#setReceiveHandler(String name)} for more informations. In the same logic, the default "timeout handler" is explicitly timeout().

note: currently applets are not allowed to use multicast sockets

Constructors

UDP(owner);
UDP(owner, port);
UDP(owner, port, ip);

Parameters

owner		the target object to be call by the receive handler
port		local port to bind
ip		host address or group address

Fields

BUFFER_SIZE

The default socket buffer length in bytes.

Methods

address ( )		Return the actual socket's local address, or `null` if the address correspond to any local address.
broadcast ( )		Enables or disables the ability of the current process to send broadcast messages.
close ( )		Close the actuel datagram socket and all associate resources.
dispose ( )		Close the socket. This method is automatically called by Processing when the PApplet shuts down.
getBuffer ( )		Return the actual socket buffer length
getTimeToLive ( )		Return the "Time to Live" value or -1 if an error occurred (or if the current socket is not a multicast socket).
isBroadcast ( )		Returns whether the opened socket send broadcast message socket or not.
isClosed ( )		Returns whether the current socket is closed or not.
isJoined ( )		Returns whether the multicast socket is joined to a group address.
isListening ( )		Returns whether the socket wait for incoming data or not.
isLoopback ( )		Returns whether the multicast socket loopback mode is enable or not.
isMulticast ( )		Returns whether the opened datagram socket is a multicast socket or not.
listen ( )		Wait for incoming data, and call the appropriate handlers each time a message is received. If the owner's class own the appropriate target handler, this method send it the receive message as byte[], the sender IP address and port. This method force the current `Thread` to be ceased for a temporary period. If you prefer listening without blocking the current thread, use the {@link UDP#listen(int millis)} or {@link UDP#listen(boolean on)} method instead.
log ( )		Enable or disable output process log.
loopback ( )		Enable or disable the multicast socket loopback mode. By default loopback is enable. Setting loopback to false means this multicast socket does not want to receive the data that it sends to the multicast group.
port ( )		Return the actual socket's local port, or -1 if the socket is closed.
run ( )		Wait for incoming datagram packets. This method is called automaticlly, you do not need to call it.
send ( )		Send data to the requested IP address and port. A `null` IP address will assign the packet address to the local host. Use this method to send data to another application by passing `null` as the destination address.
setBuffer ( )		Set the maximum size of the packet that can be sent or receive on the current socket. This value must be greater than 0, otherwise the buffer size is set to the his default value. return `true` if the new buffer value have been correctly set, `false` otherwise. note : this method has no effect if the socket is listening. To define a new buffer size, call this method before implementing a new buffer in memory. Explicitly before calling a receive methods.
setReceiveHandler ( )		Register the target's receive handler. By default, this method name is "receive" with one argument representing the received data as `byte[]`. For more flexibility, you can change this method with another useful method by passing his name. You could get more informations by implementing two additional arguments, a `String` representing the sender IP address and a `int` representing the sender port : void myCustomReceiveHandler(byte[] message, String ip, int port) { // do something here... }
setTimeToLive ( )		Control the life-time of a datagram in the network for multicast packets in order to indicates the scope of the multicasts (ie how far the packet will travel). The TTL value must be in range of 0 to 255 inclusive. The larger the number, the farther the multicast packets will travel (by convention): 0 -> restricted to the same host 1 -> restricted to the same subnet (default) <32 -> restricted to the same site <64 -> restricted to the same region <128 -> restricted to the same continent <255 -> no restriction The default value is 1, meaning that the datagram will not go beyond the local subnet. return `true` if no error occured.
setTimeoutHandler ( )		Register the target's timeout handler. By default, this method name is "timeout" with no argument.

Usage Web & Application