L3D
Class L3D_UDP

java.lang.Object
  extended by L3D.L3D_UDP
All Implemented Interfaces:
Runnable

public class L3D_UDP
extends Object
implements Runnable

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:

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 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

Author:
Cousot Stephane - stef@ubaa.net, Douglas Edric Stanley - http://www.abstractmachine.net/

Field Summary
static int BUFFER_SIZE
          The default socket buffer length in bytes.
 
Constructor Summary
L3D_UDP(Object owner)
          Create a new datagram socket and binds it to an available port and every address on the local host machine.
L3D_UDP(Object owner, int port)
          Create a new datagram socket and binds it to the specified port on the local host machine.
L3D_UDP(Object owner, int port, String ip)
          Create a new datagram socket and binds it to the specified port on the specified local address or multicast group address.
 
Method Summary
 String address()
          Return the actual socket's local address, or null if the address correspond to any local address.
 boolean broadcast(boolean on)
          Enables or disables the ability of the current process to send broadcast messages.
 void close()
          Close the actuel datagram socket and all associate resources.
 void dispose()
          Close the socket.
 int getBuffer()
          Return the actual socket buffer length
 int getTimeToLive()
          Return the "Time to Live" value or -1 if an error occurred (or if the current socket is not a multicast socket).
 boolean isBroadcast()
          Returns whether the opened socket send broadcast message socket or not.
 boolean isClosed()
          Returns whether the current socket is closed or not.
 boolean isJoined()
          Returns whether the multicast socket is joined to a group address.
 boolean isListening()
          Returns whether the socket wait for incoming data or not.
 boolean isLoopback()
          Returns whether the multicast socket loopback mode is enable or not.
 boolean isMulticast()
          Returns whether the opened datagram socket is a multicast socket or not.
 void listen()
          Wait for incoming data, and call the appropriate handlers each time a message is received.
 void listen(boolean on)
          Start/stop waiting constantly for incoming data.
 void listen(int millis)
          Set the socket reception timeout and wait one time for incoming data.
 void log(boolean on)
          Enable or disable output process log.
 void loopback(boolean on)
          Enable or disable the multicast socket loopback mode.
 int port()
          Return the actual socket's local port, or -1 if the socket is closed.
 void run()
          Wait for incoming datagram packets.
 boolean send(byte[] buffer)
          Send data to the current socket.
 boolean send(byte[] buffer, String ip)
          Send data to the requested IP address, to the current socket port.
 boolean send(byte[] buffer, String ip, int port)
          Send data to the requested IP address and port.
 boolean send(String message)
          Send message to the current socket.
 boolean send(String message, String ip)
          Send message to the requested IP address, to the current socket port.
 boolean send(String message, String ip, int port)
          Send message to the requested IP address and port.
 boolean setBuffer(int size)
          Set the maximum size of the packet that can be sent or receive on the current socket.
 void setReceiveHandler(String name)
          Register the target's receive handler.
 void setTimeoutHandler(String name)
          Register the target's timeout handler.
 boolean setTimeToLive(int ttl)
          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).
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BUFFER_SIZE

public static final int BUFFER_SIZE
The default socket buffer length in bytes.

See Also:
Constant Field Values
Constructor Detail

L3D_UDP

public L3D_UDP(Object owner)
Create a new datagram socket and binds it to an available port and every address on the local host machine.

Parameters:
owner - the target object to be call by the receive handler

L3D_UDP

public L3D_UDP(Object owner,
               int port)
Create a new datagram socket and binds it to the specified port on the local host machine.

Pass zero as port number, will let the system choose an available port.

Parameters:
owner - the target object to be call by the receive handler
port - local port to bind

L3D_UDP

public L3D_UDP(Object owner,
               int port,
               String ip)
Create a new datagram socket and binds it to the specified port on the specified local address or multicast group address.

Pass zero as port number, will let the system choose an available port. The absence of an address, explicitly null as IP address will assign the socket to the Unspecified Address (Also called anylocal or wildcard address). To set up the socket as multicast socket, pass the group address to be joined. If this address is not a valid multicast address, a broadcast socket will be created by default.

Parameters:
owner - the target object to be call by the receive handler
port - local port to bind
ip - host address or group address
Method Detail

dispose

public void dispose()
Close the socket. This method is automatically called by Processing when the PApplet shuts down.

See Also:
close()

close

public void close()
Close the actuel datagram socket and all associate resources.


isClosed

public boolean isClosed()
Returns whether the current socket is closed or not.

Returns:
boolean

port

public int port()
Return the actual socket's local port, or -1 if the socket is closed.

Returns:
int

address

public String address()
Return the actual socket's local address, or null if the address correspond to any local address.

Returns:
String

send

public boolean send(String message)
Send message to the current socket. Explicitly, send message to the multicast group/port or to itself.

Parameters:
message - the message to be send
Returns:
boolean
See Also:
send(String message, String ip), send(String message, String ip, int port)

send

public boolean send(byte[] buffer)
Send data to the current socket. Explicitly, send data to the multicast group/port or to itself.

Parameters:
buffer - data to be send
Returns:
boolean
See Also:
send(byte[] data, String ip), send(byte[] data, String ip, int port)

send

public boolean send(String message,
                    String ip)
Send message to the requested IP address, to the current socket port.

Parameters:
message - the message to be send
ip - the destination host's IP address
Returns:
boolean
See Also:
send(String message), send(String message, String ip, int port)

send

public boolean send(byte[] buffer,
                    String ip)
Send data to the requested IP address, to the current socket port.

Parameters:
buffer - data to be send
ip - the destination host's IP address
Returns:
boolean
See Also:
send(byte[] buffer), send(byte[] buffer, String ip, int port)

send

public boolean send(String message,
                    String ip,
                    int port)
Send message 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 message to another application by passing null as the destination address.

Parameters:
message - the message to be send
ip - the destination host's IP address
port - the destination host's port
Returns:
boolean
See Also:
send(String message), send(String message, String ip)

send

public boolean send(byte[] buffer,
                    String ip,
                    int port)
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.

Parameters:
buffer - data to be send
ip - the destination host's IP address
port - the destination host's port
Returns:
boolean
See Also:
send(byte[] buffer, String ip), send(byte[] buffer, String ip, int port)

setBuffer

public boolean setBuffer(int size)
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.

Parameters:
size - the buffer size value in bytes or n<=0
Returns:
boolean
See Also:
getBuffer()

getBuffer

public int getBuffer()
Return the actual socket buffer length

Returns:
int
See Also:
setBuffer(int size)

isListening

public boolean isListening()
Returns whether the socket wait for incoming data or not.

Returns:
boolean

listen

public void listen(boolean on)
Start/stop waiting constantly for incoming data.

Parameters:
on - the required listening status.
See Also:
listen(), listen(int millis), setReceiveHandler(String name)

listen

public void listen(int millis)
Set the socket reception timeout and wait one time for incoming data. If the timeout period occured, the owner timeout() method is automatically called.

Parameters:
millis - the required timeout value in milliseconds.
See Also:
listen(), listen(boolean on)

listen

public void 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 listen(int millis) or listen(boolean on) method instead.

See Also:
listen(), listen(boolean on), setReceiveHandler(String name)

run

public void run()
Wait for incoming datagram packets. This method is called automaticlly, you do not need to call it.

Specified by:
run in interface Runnable

setReceiveHandler

public void setReceiveHandler(String name)
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...
 }
 

Parameters:
name - the receive handler name
See Also:
setTimeoutHandler(String name)

setTimeoutHandler

public void setTimeoutHandler(String name)
Register the target's timeout handler. By default, this method name is "timeout" with no argument.

Parameters:
name - the timeout handler name
See Also:
setReceiveHandler(String name)

isMulticast

public boolean isMulticast()
Returns whether the opened datagram socket is a multicast socket or not.

Returns:
boolean

isJoined

public boolean isJoined()
Returns whether the multicast socket is joined to a group address.

Returns:
boolean

isBroadcast

public boolean isBroadcast()
Returns whether the opened socket send broadcast message socket or not.

Returns:
boolean

broadcast

public boolean broadcast(boolean on)
Enables or disables the ability of the current process to send broadcast messages.

Returns:
boolean

loopback

public void loopback(boolean on)
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.

Parameters:
on - local loopback of multicast datagrams

isLoopback

public boolean isLoopback()
Returns whether the multicast socket loopback mode is enable or not.

Returns:
boolean

setTimeToLive

public boolean setTimeToLive(int ttl)
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.

Parameters:
ttl - the "Time to Live" value
Returns:
boolean
See Also:
getTimeToLive()

getTimeToLive

public int getTimeToLive()
Return the "Time to Live" value or -1 if an error occurred (or if the current socket is not a multicast socket).

Returns:
int
See Also:
setTimeToLive(int ttl)

log

public void log(boolean on)
Enable or disable output process log.



Processing library L3D by Alex Hornstein. (c) 2015