tuwien.auto.calimero.knxnetip
Class KNXnetIPTunnel

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

All Implemented Interfaces:

KNXnetIPConnection

public class KNXnetIPTunnel
extends java.lang.Object

KNXnet/IP connection for KNX tunneling.

The tunneling protocol specifies a point-to-point exchange of KNX frames over an IP network connection between two KNXnet/IP devices - client and server.
Up to now, only the client side is implemented.
The communication on OSI layer 4 is done using UDP.

Nested Class Summary

Nested classes/interfaces inherited from interface tuwien.auto.calimero.knxnetip.KNXnetIPConnection

KNXnetIPConnection.BlockingMode

Field Summary

static int	ACK_ERROR Status code of communication: in idle state, received an acknowledge error in response, ready to send.
static int	ACK_PENDING Status code of communication: waiting for acknowledge after send, no error, not ready to send.
static short	BUSMONITOR_LAYER Tunneling on busmonitor layer, establishes a busmonitor tunnel to the KNX network.
static int	CEMI_CON_PENDING Status code of communication: waiting for confirmation after acknowledge, no error, not ready to send.
static short	LINK_LAYER Tunneling on link layer, establishes a link layer tunnel to the KNX network.
static short	RAW_LAYER Tunneling on raw layer, establishes a raw tunnel to the KNX network.
static short	TUNNEL_CONNECTION Connection type used to tunnel between two KNXnet/IP devices (client / server).
static int	UNKNOWN_ERROR Status code of communication: unknown error, no send possible.

Fields inherited from interface tuwien.auto.calimero.knxnetip.KNXnetIPConnection

CLOSED, IP_PORT, KNXNETIP_VERSION_10, NONBLOCKING, OK, WAIT_FOR_ACK, WAIT_FOR_CON

Constructor Summary

KNXnetIPTunnel(short KNXLayer, java.net.InetSocketAddress localEP, java.net.InetSocketAddress serverCtrlEP, boolean useNAT)
Creates a new KNXnet/IP tunneling connection to a remote server.

Method Summary

void	addConnectionListener(KNXListener l) Adds the specified event listener l to receive events from this connection.
void	close() Ends communication with the remote server/client as specified by the used protocol.
protected void	connect(java.net.InetSocketAddress localEP, java.net.InetSocketAddress serverCtrlEP, CRI cri, boolean useNAT) Opens a new IP communication channel to a remote server.
protected void	fireFrameReceived(CEMI frame) Fires a frame received event (KNXListener.frameReceived(FrameEvent)) for the supplied cEMI frame.
java.lang.String	getName() Returns the name of this connection, a brief textual representation to identify a KNXnet/IP connection.
java.net.InetSocketAddress	getRemoteAddress() Returns the address (endpoint) this connection endpoint is communicating to.
protected int	getSeqNoRcv() Returns the protocol's current receive sequence number.
protected int	getSeqNoSend() Returns the protocol's current send sequence number.
int	getState() Returns information about the current KNXnet/IP communication state.
protected void	incSeqNoRcv() Increments the protocol's receive sequence number, with increment on sequence number 255 resulting in 0.
protected void	incSeqNoSend() Increments the protocol's send sequence number, with increment on sequence number 255 resulting in 0.
void	removeConnectionListener(KNXListener l) Removes the specified event listener l, so it does no longer receive events from this connection.
void	send(CEMI frame, KNXnetIPConnection.BlockingMode mode) Sends a cEMI frame to the remote server communicating with this endpoint.

Methods inherited from class java.lang.Object

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

Field Detail

BUSMONITOR_LAYER

public static final short BUSMONITOR_LAYER

Tunneling on busmonitor layer, establishes a busmonitor tunnel to the KNX network.

See Also:

Constant Field Values

LINK_LAYER

public static final short LINK_LAYER

Tunneling on link layer, establishes a link layer tunnel to the KNX network.

See Also:

Constant Field Values

RAW_LAYER

public static final short RAW_LAYER

Tunneling on raw layer, establishes a raw tunnel to the KNX network.

See Also:

Constant Field Values

TUNNEL_CONNECTION

public static final short TUNNEL_CONNECTION

Connection type used to tunnel between two KNXnet/IP devices (client / server).

See Also:

Constant Field Values

ACK_ERROR

public static final int ACK_ERROR

Status code of communication: in idle state, received an acknowledge error in response, ready to send.

See Also:

Constant Field Values

ACK_PENDING

public static final int ACK_PENDING

Status code of communication: waiting for acknowledge after send, no error, not ready to send.

See Also:

Constant Field Values

CEMI_CON_PENDING

public static final int CEMI_CON_PENDING

Status code of communication: waiting for confirmation after acknowledge, no error, not ready to send.

See Also:

Constant Field Values

UNKNOWN_ERROR

public static final int UNKNOWN_ERROR

Status code of communication: unknown error, no send possible.

See Also:

Constant Field Values

Constructor Detail

KNXnetIPTunnel

public KNXnetIPTunnel(short KNXLayer,
                      java.net.InetSocketAddress localEP,
                      java.net.InetSocketAddress serverCtrlEP,
                      boolean useNAT)
               throws KNXException

Creates a new KNXnet/IP tunneling connection to a remote server.

Establishing a raw tunneling layer (RAW_LAYER) is not supported yet.

Parameters:

KNXLayer - KNX tunneling layer (e.g. LINK_LAYER)

localEP - specifies the local endpoint with the socket address to be used by the tunnel

serverCtrlEP - control endpoint of the server to establish connection to

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

Throws:

KNXException - on socket communication error

KNXTimeoutException - on no connect response before connect timeout

KNXRemoteException - if response indicates an error condition at the server concerning the request

KNXInvalidResponseException - if connect response is in wrong format

Method Detail

getName

public java.lang.String getName()

Description copied from interface: KNXnetIPConnection

Returns the name of this connection, a brief textual representation to identify a KNXnet/IP connection.

The name has to be unique at least for connections with different IP addresses for the remote control endpoint.
The returned name is used by this connection for the name of its log service.

Returns:

name for this connection as string

send

public void send(CEMI frame,
                 KNXnetIPConnection.BlockingMode mode)
          throws KNXTimeoutException,
                 KNXConnectionClosedException

Sends a cEMI frame to the remote server communicating with this endpoint.

Sending in busmonitor mode is not permitted.

Specified by:

send in interface KNXnetIPConnection

Parameters:

frame - cEMI message to send, the expected cEMI type is according to the used tunneling layer

mode - specifies the behavior in regard to response messages, this parameter will be ignored by protocols in case no response is expected at all;
supply one of the KNXnetIPConnection.BlockingMode constants, with following blocking behavior in increasing order
KNXnetIPConnection.NONBLOCKING
KNXnetIPConnection.WAIT_FOR_ACK
KNXnetIPConnection.WAIT_FOR_CON

Throws:

KNXTimeoutException - in a blocking mode if a timeout regarding a response message was encountered

KNXConnectionClosedException - if no communication was established in the first place or communication was closed

addConnectionListener

public void addConnectionListener(KNXListener l)

Description copied from interface: KNXnetIPConnection

Adds the specified event listener l to receive events from this connection.

If l was already added as listener, no action is performed.

Note: the method KNXListener.frameReceived(tuwien.auto.calimero.FrameEvent) of an added listener will be invoked by the KNXnet/IP receiver, and not in the context of the calling thread. Lengthy tasks have to be avoided during the notification, and should be relayed into their own worker thread. Otherwise subsequent listener invocations will suffer from time delays since the receiver can not move on.

Specified by:

addConnectionListener in interface KNXnetIPConnection

Parameters:

l - the listener to add

close

public final void close()

Description copied from interface: KNXnetIPConnection

Ends communication with the remote server/client as specified by the used protocol.

All registered event listeners get notified. The close event is the last event the listeners receive.
If this connection endpoint is already closed, no action is performed.

Specified by:

close in interface KNXnetIPConnection

connect

protected void connect(java.net.InetSocketAddress localEP,
                       java.net.InetSocketAddress serverCtrlEP,
                       CRI cri,
                       boolean useNAT)
                throws KNXException

Opens a new IP communication channel to a remote server.

The communication state of this object is assumed to be closed state. This method is designed to be called only once during the objects lifetime!

Parameters:

localEP - the local endpoint to use for communication channel

serverCtrlEP - the remote server control endpoint used for connect request

cri - connect request information used to configure the communication attributes

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

Throws:

KNXException - on socket communication error

KNXTimeoutException - on no connect response before connect timeout

KNXRemoteException - if response indicates an error condition at the server concerning the request

KNXInvalidResponseException - if connect response is in wrong format

fireFrameReceived

protected void fireFrameReceived(CEMI frame)

Fires a frame received event (KNXListener.frameReceived(FrameEvent)) for the supplied cEMI frame.

Parameters:

frame - the cEMI to generate the event for

getRemoteAddress

public final java.net.InetSocketAddress getRemoteAddress()

Description copied from interface: KNXnetIPConnection

Returns the address (endpoint) this connection endpoint is communicating to.

The address returned is equal to the one used to establish the communication (e.g. control endpoint), although internal there might be used different addresses.
If no communication is established, the unspecified (wildcard) address with port number 0 is returned.

Specified by:

getRemoteAddress in interface KNXnetIPConnection

Returns:

IP address/host and port as InetSocketAddress

getSeqNoRcv

protected int getSeqNoRcv()

Returns the protocol's current receive sequence number.

Returns:

receive sequence number as int

getSeqNoSend

protected int getSeqNoSend()

Returns the protocol's current send sequence number.

Returns:

send sequence number as int

getState

public final int getState()

Description copied from interface: KNXnetIPConnection

Returns information about the current KNXnet/IP communication state.

Specified by:

getState in interface KNXnetIPConnection

Returns:

state enumeration

incSeqNoRcv

protected void incSeqNoRcv()

Increments the protocol's receive sequence number, with increment on sequence number 255 resulting in 0.

incSeqNoSend

protected void incSeqNoSend()

Increments the protocol's send sequence number, with increment on sequence number 255 resulting in 0.

removeConnectionListener

public void removeConnectionListener(KNXListener l)

Description copied from interface: KNXnetIPConnection

Removes the specified event listener l, so it does no longer receive events from this connection.

If l was not added in the first place, no action is performed.

Specified by:

removeConnectionListener in interface KNXnetIPConnection

Parameters:

l - the listener to remove