tuwien.auto.calimero.knxnetip
Class Discoverer

java.lang.Object
  tuwien.auto.calimero.knxnetip.Discoverer

public class Discoverer
extends java.lang.Object

Does KNXnet/IP discovery and retrieval of self description from other devices.

Discovery searches and description requests can be run in blocking mode or asynchronous in the background.
Supports networks with routers doing network address translation.
Requests for self description are sent using the UDP transport protocol.
Due to protocol limitations, only IPv4 addresses are supported when network address translation is not used. With NAT enabled, IPv6 addresses can be used as well.

A note on (not) using network address translation (NAT):
If discovery or description attempts fail indicating a timeout limit, it might be possible that NAT is used on routers while traversing the network, so the solution would be to enable the use of NAT.
On the other hand, if NAT is used but not supported by the answering device, no response is received and a timeout will occur nevertheless. That's life.

Field Summary

static java.lang.String	LOG_SERVICE Name of the log service used by a discoverer.
static java.lang.String	SEARCH_MULTICAST Multicast IP address used for discovery, multicast group is "224.0.23.12".
static int	SEARCH_PORT Port number used for discovery, port is 3671.

Constructor Summary

Discoverer(java.net.InetAddress localHost, int localPort, boolean useNAT)
Creates a new Discoverer and allows to specify a local host.

Discoverer(int localPort, boolean useNAT)
Creates a new Discoverer.

Method Summary

void	clearSearchResponses() Removes all search responses collected so far.
DescriptionResponse	getDescription(java.net.InetSocketAddress server, int timeout) Sends a description request to server and waits at most timeout seconds for the answer message to arrive.
SearchResponse[]	getSearchResponses() Returns all collected search responses received by searches so far.
boolean	isSearching() Returns true if a search is currently running.
void	startSearch(int timeout, boolean wait) Starts a new discovery from all found network interfaces.
void	startSearch(int localPort, java.net.NetworkInterface ni, int timeout, boolean wait) Starts a new discovery, the localPort and network interface can be specified.
void	stopSearch() Stops every search currently running within this Discoverer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOG_SERVICE

public static final java.lang.String LOG_SERVICE

Name of the log service used by a discoverer.

See Also:

Constant Field Values

SEARCH_MULTICAST

public static final java.lang.String SEARCH_MULTICAST

Multicast IP address used for discovery, multicast group is "224.0.23.12".

See Also:

Constant Field Values

SEARCH_PORT

public static final int SEARCH_PORT

Port number used for discovery, port is 3671.

See Also:

Constant Field Values

Constructor Detail

Discoverer

public Discoverer(java.net.InetAddress localHost,
                  int localPort,
                  boolean useNAT)
           throws KNXException

Creates a new Discoverer and allows to specify a local host.

See Discoverer(int, boolean) for additional description.
The localHost is used to specify a particular local host address, used as response destination address when doing discovery / description. By default, the local host is used as obtained by InetAddress.getLocalHost(). The returned address is quite system dependent and might not always be useful in some situations. So it can be overruled specifying a local host address using this constructor.

Parameters:

localHost - local host address used for discovery / description responses

localPort - the port number used to bind a socket, a valid port is in the range of 1 to 65535, or use 0 to pick an arbitrary unused (ephemeral) port. Note that a specified valid port does not ensure a successful bind in subsequent discoverer operations due to operating system dependencies.

useNAT - true to use a NAT (network address translation) aware discovery/description mechanism, false to use the default way

Throws:

KNXException - if local host can't be used

Discoverer

public Discoverer(int localPort,
                  boolean useNAT)
           throws KNXException

Creates a new Discoverer.

Network address translation:
If subsequent discovery or description attempts fail indicating a timeout limit, it might be possible that network address translation (NAT) is used on routers while traversing the network (besides the other reason that timeouts are too short). This would effectively stop any communication done in the standard way, due to the way the HPAI structure is used by default.
Setting the parameter for indicating use of NAT to true takes account of such routers, leading to the desired behavior.

Parameters:

localPort - the port number used to bind a socket, a valid port is in the range of 1 to 65535, or use 0 to pick an arbitrary unused (ephemeral) port. Note that a specified valid port does not ensure a successful bind in subsequent discoverer operations due to operating system dependencies.

useNAT - true to use a NAT (network address translation) aware discovery/description mechanism, false to use the default way

Throws:

KNXException - on error getting usable local host

Method Detail

clearSearchResponses

public final void clearSearchResponses()

Removes all search responses collected so far.

getDescription

public DescriptionResponse getDescription(java.net.InetSocketAddress server,
                                          int timeout)
                                   throws KNXException

Sends a description request to server and waits at most timeout seconds for the answer message to arrive.

Parameters:

server - the InetSocketAddress of the server the description is requested from

timeout - time window in seconds to wait for answer message, 0 < timeout < (Integer.MAX_VALUE / 1000)

Returns:

the description response message

Throws:

KNXException - on network I/O error

KNXTimeoutException - if the timeout was reached before the description response arrived

KNXInvalidResponseException - if a received message from server does not match the expected response

getSearchResponses

public final SearchResponse[] getSearchResponses()

Returns all collected search responses received by searches so far.

As long as searches are running, new responses might be added to the list of responses.

Returns:

array of SearchResponses

See Also:

stopSearch()

isSearching

public final boolean isSearching()

Returns true if a search is currently running.

Returns:

a boolean showing the search state

startSearch

public void startSearch(int timeout,
                        boolean wait)
                 throws KNXException

Starts a new discovery from all found network interfaces.

The search will continue for timeout seconds, or infinite if timeout value is zero. During this time, search responses will get collected asynchronous in the background by this Discoverer.
With wait you can force this method into blocking mode to wait until the search finished, otherwise the method returns with the search running in the background.
A search has finished if either the timeout was reached, all background receiver stopped (all responses received) or stopSearch() was invoked.

Parameters:

timeout - time window in seconds during which search response messages will get collected, timeout >= 0. If timeout is 0, no timeout is set, the search has to be stopped with stopSearch.

wait - true to block until end of search before return

Throws:

KNXException - on network I/O error

startSearch

public void startSearch(int localPort,
                        java.net.NetworkInterface ni,
                        int timeout,
                        boolean wait)
                 throws KNXException

Starts a new discovery, the localPort and network interface can be specified.

The search will continue for timeout seconds, or infinite if timeout value is zero. During this time, search responses will get collected asynchronous in the background by this Discoverer.
With wait you can force this method into blocking mode to wait until the search finished, otherwise the method returns with the search running in the background.
A search is finished if either the timeout was reached or the background receiver stopped.
The reason the localPort parameter is specified here, in addition to the port queried at Discoverer(int, boolean), is to distinguish between search responses if more searches are running concurrently.

Parameters:

localPort - the port used to bind the socket, a valid port is 0 to 65535, if localPort is zero an arbitrary unused (ephemeral) port is picked

ni - the NetworkInterface used for sending outgoing multicast messages, or null to use the default multicast interface

timeout - time window in seconds during which search response messages will get collected, timeout >= 0. If timeout is zero, no timeout is set, the search has to be stopped with stopSearch().

wait - true to block until end of search before return

Throws:

KNXException - on network I/O error

See Also:

MulticastSocket, NetworkInterface

stopSearch

public final void stopSearch()

Stops every search currently running within this Discoverer.

Already gathered search responses from a search will not be removed.