tuwien.auto.calimero.knxnetip
Interface KNXnetIPConnection

All Known Implementing Classes:

KNXnetIPDevMgmt, KNXnetIPRouter, KNXnetIPTunnel

public interface KNXnetIPConnection

Interface for working with KNX networks over an IP network connection.

The data exchange (send and receive) is done through CEMI messages. Asynchronous or incoming events are relayed to the registered event listeners.

Point-to-point logical connections:
Implementations with connectionless protocols, like UDP, shall provide heartbeat monitoring as defined by the KNX specification to check the connection state. Connection state messages are sent regularly, every 60 seconds, to the connected server. If the message is not responded to within a timeout of 10 seconds, it is repeated 3 times, and on no response the connection will be terminated.

Log information by this connection is provided using the log service with the name obtained from getName().

See Also:

KNXnetIPTunnel, KNXnetIPDevMgmt, KNXnetIPRouter, KNXListener, CEMI

Nested Class Summary

static class

KNXnetIPConnection.BlockingMode Type for blocking mode used in send(CEMI, tuwien.auto.calimero.knxnetip.KNXnetIPConnection.BlockingMode).

Field Summary

static int	CLOSED State of communication: in closed state, no send possible.
static int	IP_PORT KNXnet/IP port number (3671), used in discovery, routing, and the default port for a communication endpoint.
static int	KNXNETIP_VERSION_10 Identifier for KNXnet/IP protocol version 1.0.
static KNXnetIPConnection.BlockingMode	NONBLOCKING Send mode without any blocking for a response.
static int	OK State of communication: in idle state, no error, ready to send.
static KNXnetIPConnection.BlockingMode	WAIT_FOR_ACK Send mode with waiting for acknowledge response.
static KNXnetIPConnection.BlockingMode	WAIT_FOR_CON Send mode with waiting for cEMI confirmation response.

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.
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.
int	getState() Returns information about the current KNXnet/IP communication state.
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.

Field Detail

CLOSED

static final int CLOSED

State of communication: in closed state, no send possible.

See Also:

Constant Field Values

IP_PORT

static final int IP_PORT

KNXnet/IP port number (3671), used in discovery, routing, and the default port for a communication endpoint.

See Also:

Constant Field Values

KNXNETIP_VERSION_10

static final int KNXNETIP_VERSION_10

Identifier for KNXnet/IP protocol version 1.0.

See Also:

Constant Field Values

NONBLOCKING

static final KNXnetIPConnection.BlockingMode NONBLOCKING

Send mode without any blocking for a response.

OK

static final int OK

State of communication: in idle state, no error, ready to send.

See Also:

Constant Field Values

WAIT_FOR_ACK

static final KNXnetIPConnection.BlockingMode WAIT_FOR_ACK

Send mode with waiting for acknowledge response.

WAIT_FOR_CON

static final KNXnetIPConnection.BlockingMode WAIT_FOR_CON

Send mode with waiting for cEMI confirmation response.

Method Detail

addConnectionListener

void addConnectionListener(KNXListener l)

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.

Parameters:

l - the listener to add

close

void close()

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.

getName

java.lang.String getName()

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

getRemoteAddress

java.net.InetSocketAddress getRemoteAddress()

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.

Returns:

IP address/host and port as InetSocketAddress

getState

int getState()

Returns information about the current KNXnet/IP communication state.

Returns:

state enumeration

removeConnectionListener

void removeConnectionListener(KNXListener l)

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.

Parameters:

l - the listener to remove

send

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

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

The particular subtype of the cEMI frame expected might differ according to the implementation of the KNXnet/IP connection.
In blocking mode, all necessary retransmissions of sent frames will be done automatically according to the protocol specification (e.g. in case of timeout).
If a communication failure occurs on the local socket, close() is called.
In blocking send mode, on successfully receiving a response, all listeners are guaranteed to get notified before this method returns, with the communication state (see getState()) reset to OK after the notifying is done, so to prevent another send call from a listener.

Parameters:

frame - cEMI message to send

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

KNXIllegalStateException - if the send is not permitted by the protocol