tuwien.auto.calimero.knxnetip
Class KNXnetIPTunnel

java.lang.Object
  extended by 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