Package org.ka2ddo.ax25

Class AX25Stack

java.lang.Object
org.ka2ddo.ax25.AX25Stack
All Implemented Interfaces:
Runnable, FrameListener, DebugCtl.DbgListener
public class AX25Stack extends Object implements FrameListener, Runnable, DebugCtl.DbgListener
This class implements the internal AX.25 (v2.2) protocol stack for a TNC (layer 2), as defined in the AX.25 Link Access Protocol for Amateur Packet Radio specification. It does not implement the level 7 applications or any layer 3 protocols.
Author:
Andrew Pavlin, KA2DDO

  • Field Details

    • WAIT_FOR_ACK_T1_TIMER

      public static final int WAIT_FOR_ACK_T1_TIMER
      Time interval (in milliseconds) to wait for an acknowledgement from the other end of a AX.25 connection.
      See Also:

  • Method Details

    • getInstance

      public static AX25Stack getInstance()
      Get a handle to the AX25Stack singleton.
      Returns:
      AX25Stack instance

    • getDigipeaters

      public static String[] getDigipeaters()
      Get the default list of digipeaters for this stack.
      Returns:
      array of String digipeater aliases supported by this stack

    • setDigipeaters

      public static void setDigipeaters(String[] digipeaters)
      Set the default list of digipeaters for this stack.
      Parameters:
      digipeaters - array of String digipeater aliases

    • getToCall

      public static String getToCall()
      Get the destination callsign (tocall) that should be used for messages originated by this station.
      Returns:
      destination callsign (tocall)

    • setToCall

      public static void setToCall(String toCall)
      Set the destination callsign (tocall) that should be used for messages originated by this station.
      Parameters:
      toCall - destination callsign (tocall)

    • setDebug

      public void setDebug(String categoryName, boolean setting)
      Specify if a specific category of debug messages should be printed out.
      Specified by:
      setDebug in interface DebugCtl.DbgListener
      Parameters:
      categoryName - String name of category to enable debug logging for
      setting - boolean true or false to enable or disable debugging this category

    • getTransmitting

      public static Transmitting getTransmitting()
      Get the Transmitting object that this AX25Stack will use for implicit but unrouted transmissions.
      Returns:
      Transmitting object

    • setTransmitting

      public static void setTransmitting(Transmitting transmitting)
      Set the Transmitting object that this AX25Stack will use for implicit but unrouted transmissions.
      Parameters:
      transmitting - Transmitting object

    • getRetransTimer

      public static ReschedulableTimer getRetransTimer()
      Get the retransmit timer for outbound AX.25 frames.
      Returns:
      ReschedulableTimer

    • isAllowInboundConnectedMode

      public static boolean isAllowInboundConnectedMode()
      Indicate whether this system accepts inbound connected-mode connection requests.
      Returns:
      boolean true if inbound connection requests should be accepted

    • setAllowInboundConnectedMode

      public static void setAllowInboundConnectedMode(boolean allowInboundConnects)
      Specify whether this system accepts inbound connected-mode connection requests.
      Parameters:
      allowInboundConnects - boolean true if inbound connection requests should be accepted

    • addAX25FrameListener

      public void addAX25FrameListener(AX25FrameListener l)
      Add a listener for incoming AX.25 frames.
      Parameters:
      l - AX25FrameListener to register

    • removeAX25FrameListener

      public void removeAX25FrameListener(AX25FrameListener l)
      Remove a listener for incoming AX.25 frames.
      Parameters:
      l - AX25FrameListener to unregister

    • setConnectionRequestListener

      public void setConnectionRequestListener(ConnectionRequestListener l)
      Set the handler for inbound connection requests.
      Parameters:
      l - ConnectionRequestListener to register

    • registerProtocolParser

      public void registerProtocolParser(byte pid, AX25Parser parser)
      Register another protocol parsing handler for a particular AX.25 UI/I message PID.
      Parameters:
      pid - pid byte code for this protocol
      parser - AX25Parser to handle receiving this protocol

    • getParser

      public AX25Parser getParser(byte pid)
      Get the protocol parsing handler for the specified protocol.
      Parameters:
      pid - level 3 protocol ID byte (as defined by the AX.25 protocol specification)
      Returns:
      AX25Parser object, or null if no parser registered for the specified protocol

    • fireConsumeAX25Frame

      public void fireConsumeAX25Frame(AX25Frame frame, Connector connector)
      Send the specified incoming frame to all registered AX25FrameListeners.
      Parameters:
      frame - AX25Frame to dispatch
      connector - Connector that received the frame

    • consumeFrame

      public void consumeFrame(AX25Frame frame)
      Queue one AX.25 frame (containing some sort of message) for parsing and processing.
      Specified by:
      consumeFrame in interface FrameListener
      Parameters:
      frame - the AX25Frame to be processed

    • getCurrentBacklog

      public int getCurrentBacklog()
      Return the current number of backlogged frames to be processed by the AX25Stack thread.
      Returns:
      current queue size

    • getMaxBacklog

      public int getMaxBacklog()
      Return the maximum backlog ever incurred by the AX25Stack parser thread.
      Returns:
      maximum queue backlog

    • getMaxQueueCapacity

      public int getMaxQueueCapacity()
      Return the maximum allowed size of the queue.
      Returns:
      total capacity of the backlog queue

    • getNumConsumedMsgs

      public int getNumConsumedMsgs()
      Return the number of AX.25 messages consumed by the AX25Stack.
      Returns:
      count of messages consumed

    • run

      public void run()
      Private method to asynchronously consume AX25Frame objects for parsing. This tries to prevent back-pressuring any sources (particularly fast-moving TCP connections to APRS-IS servers). Can only be executed from the singleton thread created by this class.
      Specified by:
      run in interface Runnable

    • isFrozen

      public boolean isFrozen()
      Report if parser thread is frozen.
      Returns:
      boolean true if parser thread is stopped

    • setFrozen

      public void setFrozen(boolean frozen)
      Specify whether the AX.25 parser thread should be paused (frozen) to allow the user to view the output without it moving constantly
      Parameters:
      frozen - boolean true to freeze the parser thread, or false to resume execution

    • consumeFrameNow

      public void consumeFrameNow(Connector connector, AX25Frame frame)
      Process an incoming AX.25 frame.
      Parameters:
      connector - Connector that received the frame
      frame - AX25Frame to process

    • getConnectionMap

      public Map<AX25Callsign,Map<AX25Callsign,ConnState>> getConnectionMap()
      Get the map of all outstanding I-frame connected sessions observed by or end-pointed at this station.
      Returns:
      Map by initiating callsign of Maps by destination callsign of connection states

    • getStateOf

      public static ConnState.ConnType getStateOf(AX25Callsign src, AX25Callsign dst)
      Get the connection state of an I-frame connection session between the specified two callsigns.
      Parameters:
      src - AX25Callsign of originating end of session
      dst - AX25Callsign of receiving end of session
      Returns:
      ConnType of the session, or ConnType.NONE if there is no such connection session known to this protocol stack

    • getConnState

      public static ConnState getConnState(AX25Callsign src, AX25Callsign dst, boolean createIfNotPresent)
      Get the connection state of an I-frame connection session between the specified two callsigns, optionally creating the state object if it did not previously exist.
      Parameters:
      src - AX25Callsign of originating end of session
      dst - AX25Callsign of receiving end of session
      createIfNotPresent - boolean true if a new ConnState object should be created and registered if it does not already exist
      Returns:
      ConnState object for the requested session, or null if no such session exists and the caller did not request creating one

    • removeConnState

      public static void removeConnState(ConnState connState)
      Remove the specified ConnState object from the map of ConnState maps. Usually done when a connection is closed.
      Parameters:
      connState - ConnState object to remove from map

    • dupUnuseDigipeaters

      public static AX25Callsign[] dupUnuseDigipeaters(AX25Callsign[] srcRelays)
      Create a duplicate digipeater list from a source packet, but ensure all the has-been-repeated flags are cleared.
      Parameters:
      srcRelays - array of digipeater callsign-SSID's to clone, or null if none
      Returns:
      array of duplicated AX25Callsigns with all has-been-repeated flags cleared, or null if the source array was null or empty

    • reverseDigipeaters

      public static AX25Callsign[] reverseDigipeaters(AX25Callsign[] srcRelays)
      Reverse the order of a sequence of digipeaters (explicit and APRS aliases).
      Parameters:
      srcRelays - array of AX25Callsign indicating the path used to get from sender to recipient
      Returns:
      array of AX25Callsigns needed to go from recipient back to sender

    • processIBody

      public boolean processIBody(AX25Frame frame, boolean isUI, Connector connector, long rcvTimestamp)
      This method consumes one information frame. The caller handles any flow control issues for I (versus UI) frames.
      Parameters:
      frame - AX25Frame to be decoded
      isUI - where frame was received in a UI AX.25 frame instead of an I frame
      connector - PortConnector over which message arrived, or null for file playback
      rcvTimestamp - time (in Java-standard milliseconds since Jan 1 1970 UTC) that message was received
      Returns:
      boolean true if message has already been reported to listeners

    • processParsedAX25Message

      public void processParsedAX25Message(AX25Frame frame, AX25Message parsedMsg)
      Dispatch an AX.25 frame that was parsed into a higher-level protocol to all registered listeners.
      Parameters:
      frame - AX25Frame of incoming message
      parsedMsg - AX25Message subclass containing protocol decoding of message

    • addParsedAX25MessageListener

      public void addParsedAX25MessageListener(ParsedAX25MessageListener listener)
      Register an ParsedAX25MessageListener to be notified of incoming parsed level 3 protocol messages (other than APRS).
      Parameters:
      listener - ParsedAX25MessageListener to register

    • removeParsedAX25MessageListener

      public void removeParsedAX25MessageListener(ParsedAX25MessageListener listener)
      Unregister an ParsedAX25MessageListener to be notified of incoming parsed level 3 protocol messages (other than APRS).
      Parameters:
      listener - ParsedAX25MessageListener to unregister

    • isLocalDest

      public static boolean isLocalDest(AX25Callsign dest)
      Test if this callsign is addressed to the local station.
      Parameters:
      dest - AX25Callsign to test as a destination
      Returns:
      boolean true if this callsign is for the local station

    • isLocalDest

      public static boolean isLocalDest(String destCallsign)
      Test if this callsign is addressed to the local station.
      Parameters:
      destCallsign - String of AX.25 callsign-SSID to test as a destination
      Returns:
      boolean true if this callsign is for the local station

    • addConnStateChangeListener

      public static void addConnStateChangeListener(ConnStateChangeListener l)
      Register a listener to be informed when AX.25 connected-mode session state changes.
      Parameters:
      l - ConnStateChangeListener to register

    • removeConnStateChangeListener

      public static void removeConnStateChangeListener(ConnStateChangeListener l)
      Unregister a listener to be informed when AX.25 connected-mode session state changes.
      Parameters:
      l - ConnStateChangeListener to unregister