tuwien.auto.calimero.link
Interface KNXNetworkLink

All Known Implementing Classes:

KNXNetworkLinkFT12, KNXNetworkLinkIP

public interface KNXNetworkLink

KNX network link interface to communicate with destinations in a KNX network.

A network link enables transparency of the type of connection protocol used to access a KNX network, as well as an abstraction of the particular physical KNX medium used for communication in the KNX network (e.g. TP1).

The link provides two forms of information exchange for KNX messages, one is to directly supply necessary information like KNX address, message priority and NSDU, the other to use cEMI as container format.
On send, message parts not present or supplied which are necessary for communication will be added using the information provided by setKNXMedium(KNXMediumSettings).

A KNX network link relies on an underlying intermediate connection technology and protocol (e.g. IP and KNXnet/IP, KNXnetIPConnection) to access KNX networks, the necessary access options are specified at creation of a dedicated network link.

The name returned by getName() is used by a link as name of its log service.

Method Summary

void	addLinkListener(NetworkLinkListener l) Adds the specified event listener l to receive events from this link.
void	close() Ends communication with the KNX network and closes the network link.
byte	getHopCount() Returns the hop count used as default for KNX messages.
KNXMediumSettings	getKNXMedium() Returns the KNX medium settings used by this network link.
java.lang.String	getName() Returns the name of the link, a short textual representation to identify a link.
boolean	isOpen() Checks for open network link.
void	removeLinkListener(NetworkLinkListener l) Removes the specified event listener l, so it does no longer receive events from this link.
void	send(CEMILData msg, boolean waitForCon) Sends a KNX link layer message supplied as type cEMI L-data.
void	sendRequest(KNXAddress dst, Priority p, byte[] nsdu) Sends a link layer request message to the given destination.
void	sendRequestWait(KNXAddress dst, Priority p, byte[] nsdu) Sends a link layer request message to the given destination, and waits for the corresponding link layer confirmation.
void	setHopCount(int count) Sets the hop count used as default in KNX messages.
void	setKNXMedium(KNXMediumSettings settings) Supplies medium information necessary for KNX communication.

Method Detail

addLinkListener

void addLinkListener(NetworkLinkListener l)

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

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

Parameters:

l - the listener to add

close

void close()

Ends communication with the KNX network and closes the network link.

All registered link listeners get notified.
If no communication access was established in the first place, no action is performed.

getHopCount

byte getHopCount()

Returns the hop count used as default for KNX messages.

Returns:

hop count as 3 Bit unsigned value with the range 0 to 7

See Also:

setHopCount(int)

getKNXMedium

KNXMediumSettings getKNXMedium()

Returns the KNX medium settings used by this network link.

The returned object is a reference to the one used by this link (not a copy).

Returns:

medium settings for KNX network

getName

java.lang.String getName()

Returns the name of the link, a short textual representation to identify a link.

The name is unique for links with different remote endpoints.
The returned name is used by this link for the name of its log service. Supply getName() for LogManager.getLogService(String) for example to get the log service of this link.

By default, "link " + address/ID of the remote endpoint is returned (e.g. "Link 192.168.0.10:3671" for an IP link).
After closing the link, the returned name might differ, e.g. get reset to some arbitrary default name.

Returns:

link name as string

isOpen

boolean isOpen()

Checks for open network link.

After a call to close() or after the underlying protocol initiated the end of the communication, this method always returns false.

Returns:

true if this network link is open, false on closed

removeLinkListener

void removeLinkListener(NetworkLinkListener l)

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

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

Parameters:

l - the listener to remove

send

void send(CEMILData msg,
          boolean waitForCon)
          throws KNXTimeoutException,
                 KNXLinkClosedException

Sends a KNX link layer message supplied as type cEMI L-data.

If the source address of msg is 0.0.0, the device address supplied in the medium settings is used as message source address.

Parameters:

msg - cEMI L-data message to send

waitForCon - true to wait for link layer confirmation response, false to not wait for the confirmation

Throws:

KNXTimeoutException - on a timeout during send (for example when waiting on acknowledge using a reliable sending protocol)

KNXLinkClosedException - if the link is closed

sendRequest

void sendRequest(KNXAddress dst,
                 Priority p,
                 byte[] nsdu)
                 throws KNXTimeoutException,
                        KNXLinkClosedException

Sends a link layer request message to the given destination.

Depending on the address, the request is either point-to-point, multicast or broadcast. A network link implementation is allowed to interpret a dst parameter of null as system broadcast, or otherwise uses its default broadcast behavior.

Parameters:

dst - KNX destination address, or null

p - priority this KNX message is assigned to

nsdu - network layer service data unit

Throws:

KNXTimeoutException - on a timeout during send (for example when waiting on acknowledge using a reliable sending protocol)

KNXLinkClosedException - if the link is closed

sendRequestWait

void sendRequestWait(KNXAddress dst,
                     Priority p,
                     byte[] nsdu)
                     throws KNXTimeoutException,
                            KNXLinkClosedException

Sends a link layer request message to the given destination, and waits for the corresponding link layer confirmation.

Depending on the address, the request is either point-to-point, multicast or broadcast. A network link implementation is allowed to interpret a dst parameter of null as system broadcast, or otherwise uses its default broadcast behavior.

Parameters:

dst - KNX destination address, or null

p - priority this message is assigned to

nsdu - network layer service data unit

Throws:

KNXTimeoutException - on a timeout during send or while waiting for the confirmation

KNXLinkClosedException - if the link is closed

setHopCount

void setHopCount(int count)

Sets the hop count used as default in KNX messages.

It denotes how many sub networks a message is allowed to travel.
A message its hop count is decremented by KNX routers to limit distance and avoid looping. On hop count value 0, the message is discarded from the network. A hop count of 7 never gets decremented.
By default, a hop count of 6 is specified.

Parameters:

count - hop count value, 0 <= value <= 7

setKNXMedium

void setKNXMedium(KNXMediumSettings settings)

Supplies medium information necessary for KNX communication.

These informations are differing between KNX media and depend on the KNX network this link is communicating with.
The settings medium type has to match the medium type supplied to the link in the first place.
The settings object is not copied internally to allow subsequent changes to medium settings by the user which should take effect immediately.

Parameters:

settings - medium settings to use, the expected subtype is according to the KNX network medium