org.ka2ddo.ax25
Class AX25Frame

java.lang.Object
  extended by org.ka2ddo.ax25.AX25Frame
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<AX25Frame>, AX25FrameSource

public class AX25Frame
extends java.lang.Object
implements java.io.Serializable, AX25FrameSource, java.lang.Comparable<AX25Frame>

This class defines 1 AX.25 packet, as defined by the AX.25 Link Level Protocol specification, version 2.2. Note that the Comparable interface is simply sorting by rcptTime.

Version:
2.2
See Also:
Serialized Form

Field Summary
 byte[] body
          Byte array containing the higher-level protocol payload for I and UI frames.
 byte ctl
          Bitmask identifying the frame type and subtype, and windowing position for connection-oriented I and S frames.
 byte ctl2
          Extension of ctl when using 128-segment windowing.
 AX25Callsign dest
          Callsign of the destination station, or some broadcast code with an alternate meaning (such as APRS tocalls and Mic-E encoded latitude and status values).
 AX25Callsign[] digipeaters
          Optional array of digipeater callsigns and aliases, if this frame should be digipeated.
static int FRAMETYPE_I
          Numeric code for information (I) frame type.
static int FRAMETYPE_S
          Numeric code for supervisory (S) frame type.
static int FRAMETYPE_U
          Numeric code for unnumbered (U) frame type.
static int MASK_FRAMETYPE
          The bitmask to extract the frametype bits from the ctl byte of the frame.
static int MASK_STYPE
          Bitmask to extract supervisory (S) frame subtype from the ctl byte.
static int MASK_U_P
          Bitmask to extract poll/final bit from unnumbered (U) frame ctl byte.
static int MASK_UTYPE
          Bitmask to extract unnumbered (U) frame subtype from the ctl byte.
 boolean mod128
          Indicates whether 128-segment windowing is used for I frame connections.
 AX25Message parsedAX25Msg
          The decoded APRS (or other protocol) message (if the AX25Frame contains a higher-level protocol).
 byte pid
          The one-byte code identifying how to interpret the body of I and UI frames.
static byte PID_AARP
          Protocol ID for Appletalk Address Resolution Protocol (ARP).
static byte PID_ATALK
          Protocol ID for Appletalk.
static byte PID_ESCAPE
          Protocol ID for escape code indicating second byte of PID (not supported).
static byte PID_FLEXNET
          Protocol ID for FlexNet.
static byte PID_IARP
          Protocol ID for ARPS Internet Address Resolution Protocol (ARP).
static byte PID_IP
          Protocol ID for ARPA Internet Protocol.
static byte PID_LQP
          Protocol ID for Link Quality Protocol.
static byte PID_NETROM
          Protocol ID for NET/ROM.
static byte PID_NOLVL3
          Protocol ID for no level 3 protocol (also used for APRS).
static byte PID_OPENTRAC
          Protocol ID for OpenTRAC.
static byte PID_SEG_FRAG
          Protocol ID for AX.25 segmentation fragment.
static byte PID_TEXNET
          Protocol ID for TEXNET datagram.
static byte PID_VJC_TCPIP
          Protocol ID for Van Jacobson compressed TCP/IP packet, per RFC 1144.
static byte PID_VJUC_TCPIP
          Protocol ID for Van Jacobson uncompressed TCP/IP packet, per RFC 1144.
static byte PID_X25_PLP
          Protocol ID for CCITT X.25 PLP (also used by the ROSE network).
static java.util.Map<java.lang.Byte,java.lang.String> PTYPES_S
          Hashmap of Information (I) or Unnumbered Information (UI) frame protocol ID to protocol name strings.
 long rcptTime
          The time when this message was received in Java milliseconds since midnight, Jan 1 1970 UTC..
 AX25Callsign sender
          Callsign of the transmitting station (not of any intermediate digipeaters).
static int SHIFT_STYPE
          Bit shift to get least significant bit of S frame subtype into least significant bit of integer.
static int SHIFT_UTYPE
          Bit shift to get least significant bit of U frame subtype into least significant bit of integer.
 Connector sourcePort
          Pointer to the I/O port from which this frame was received.
static int STYPE_REJ
          Unshifted S frame subtype for Reject frame.
static int STYPE_RNR
          Unshifted S frame subtype for Receive Not Ready frame.
static int STYPE_RR
          Unshifted S frame subtype for Receive Ready frame.
static int STYPE_SREJ
          Unshifted S frame subtype for Selective Reject frame.
static int UTYPE_DISC
          Unshifted U frame subtype for Disconnect (DISC).
static int UTYPE_DM
          Unshifted U frame subtype for Disconnected Mode (DM).
static int UTYPE_FRMR
          Deprecated. 2.0
static int UTYPE_SABM
          Unshifted U frame subtype for Set Asynchronous Balanced Mode (SABM).
static int UTYPE_SABME
          Unshifted U frame subtype for Set Asynchronous Balanced Mode Extended (SABME).
static int UTYPE_TEST
          Unshifted U frame subtype for Test (TEST).
static int UTYPE_UA
          Unshifted U frame subtype for Unnumbered Acknowledge (UA).
static int UTYPE_UI
          Unshifted U frame subtype for Unnumbered Information (UI).
static int UTYPE_XID
          Unshifted U frame subtype for Exchange Identification (XID).
 
Constructor Summary
AX25Frame()
          Create an empty AX25Frame initialized for a UI frame containing an APRS packet.
 
Method Summary
 int compareTo(AX25Frame o)
          Compares this object with the specified object for order.
static AX25Frame decodeFrame(byte[] buf, int offset, int length)
          Create a AX25Frame from a byte array presumed to contain an AX.25 protocol sequence.
 AX25Frame dup()
          Create a deep copy of this frame.
 AX25Frame dupOnlyHeader()
          Create a deep copy of this frame, excluding the body.
 boolean equals(java.lang.Object obj)
          Indicates whether some other object is "equal to" this one.
 java.lang.String getAsciiFrame()
          Produce an ASCIIfied version of frame body.
 int getChecksum()
          Compute a checksum for this frame to allow efficiently identifying duplicate frames.
 Connector getConnector()
          Specify the Connector this message should be transmitted through.
 int getEstimatedBitCount()
          Estimate the number of bits needed to transmit this frame over RF in AX.25 standard physical layer (HDLC).
static java.lang.String getFirstDigi(AX25Callsign[] digipeaters)
          Get the first actual digipeated digipeater station callsign in the digipeater sequence.
 AX25Frame[] getFrames(boolean incrementXmtCount, byte protocolId, java.lang.String senderCallsign)
          Get the frames associated with this FrameSource (in this case, itself).
 int getFrameType()
          Get the type of this frame, as stored in the ctl byte.
 java.lang.String getFrameTypeString()
          Generate a string describing the type of the frame.
static java.lang.String getLastDigi(AX25Callsign[] digipeaters)
          Find the last callsign through which a frame has been digipeated.
 int getNR()
          Get the reception sequence number.
 int getNS()
          Get the transmission sequence number.
 int getNumTransmitsBeforeDecay()
          Get number of times frame will be retransmitted before inter-packet delay is increased.
 boolean getP()
          Get poll bit.
 int getSType()
          Get the Supervisory frame subtype.
 int getUType()
          Get Unordered frame subtype.
 int hashCode()
          Returns a hash code value for the object.
 boolean isDuplicate(AX25Frame other)
          Test if this frame has the same contents (at least as regards duplicate checking) as the provided older frame.
static boolean isRealCallsign(java.lang.String callsign)
          Test if a callsign looks like a real callsign (at least one digit somewhere other than the last character, all letters uppercase).
 void setCmd(boolean isCmd)
          Set the command bits in the sender and destination fields.
 java.lang.String toString()
          Return a String representing this AX25Frame object.
 void write(java.io.OutputStream os)
          Transmit this AX25Frame to an output byte stream.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

sender

public AX25Callsign sender
Callsign of the transmitting station (not of any intermediate digipeaters).


dest

public AX25Callsign dest
Callsign of the destination station, or some broadcast code with an alternate meaning (such as APRS tocalls and Mic-E encoded latitude and status values).


digipeaters

public AX25Callsign[] digipeaters
Optional array of digipeater callsigns and aliases, if this frame should be digipeated. May have up to 8 elements in the array.


sourcePort

public transient Connector sourcePort
Pointer to the I/O port from which this frame was received.


ctl

public byte ctl
Bitmask identifying the frame type and subtype, and windowing position for connection-oriented I and S frames.

See Also:
getFrameType(), getUType(), getSType()

ctl2

public byte ctl2
Extension of ctl when using 128-segment windowing.

See Also:
ctl, mod128

pid

public byte pid
The one-byte code identifying how to interpret the body of I and UI frames.

See Also:
PID_X25_PLP, PID_VJC_TCPIP, PID_VJUC_TCPIP, PID_SEG_FRAG, PID_OPENTRAC, PID_TEXNET, PID_LQP, PID_ATALK, PID_AARP, PID_IP, PID_IARP, PID_FLEXNET, PID_NETROM, PID_NOLVL3, PID_ESCAPE

body

public byte[] body
Byte array containing the higher-level protocol payload for I and UI frames.


mod128

public boolean mod128
Indicates whether 128-segment windowing is used for I frame connections. If this is false, the backwards-compatible 8-segment windowing is used.


rcptTime

public long rcptTime
The time when this message was received in Java milliseconds since midnight, Jan 1 1970 UTC..


parsedAX25Msg

public transient AX25Message parsedAX25Msg
The decoded APRS (or other protocol) message (if the AX25Frame contains a higher-level protocol). May be null.


MASK_FRAMETYPE

public static final int MASK_FRAMETYPE
The bitmask to extract the frametype bits from the ctl byte of the frame.

See Also:
ctl, Constant Field Values

FRAMETYPE_I

public static final int FRAMETYPE_I
Numeric code for information (I) frame type.

See Also:
Constant Field Values

FRAMETYPE_S

public static final int FRAMETYPE_S
Numeric code for supervisory (S) frame type.

See Also:
Constant Field Values

FRAMETYPE_U

public static final int FRAMETYPE_U
Numeric code for unnumbered (U) frame type.

See Also:
Constant Field Values

MASK_STYPE

public static final int MASK_STYPE
Bitmask to extract supervisory (S) frame subtype from the ctl byte.

See Also:
ctl, Constant Field Values

SHIFT_STYPE

public static final int SHIFT_STYPE
Bit shift to get least significant bit of S frame subtype into least significant bit of integer.

See Also:
Constant Field Values

STYPE_RR

public static final int STYPE_RR
Unshifted S frame subtype for Receive Ready frame.

See Also:
MASK_STYPE, Constant Field Values

STYPE_RNR

public static final int STYPE_RNR
Unshifted S frame subtype for Receive Not Ready frame.

See Also:
MASK_STYPE, Constant Field Values

STYPE_REJ

public static final int STYPE_REJ
Unshifted S frame subtype for Reject frame.

See Also:
MASK_STYPE, Constant Field Values

STYPE_SREJ

public static final int STYPE_SREJ
Unshifted S frame subtype for Selective Reject frame.

See Also:
MASK_STYPE, Constant Field Values

MASK_UTYPE

public static final int MASK_UTYPE
Bitmask to extract unnumbered (U) frame subtype from the ctl byte.

See Also:
ctl, Constant Field Values

MASK_U_P

public static final int MASK_U_P
Bitmask to extract poll/final bit from unnumbered (U) frame ctl byte.

See Also:
ctl, Constant Field Values

SHIFT_UTYPE

public static final int SHIFT_UTYPE
Bit shift to get least significant bit of U frame subtype into least significant bit of integer.

See Also:
Constant Field Values

UTYPE_UI

public static final int UTYPE_UI
Unshifted U frame subtype for Unnumbered Information (UI).

See Also:
Constant Field Values

UTYPE_DM

public static final int UTYPE_DM
Unshifted U frame subtype for Disconnected Mode (DM).

See Also:
Constant Field Values

UTYPE_SABM

public static final int UTYPE_SABM
Unshifted U frame subtype for Set Asynchronous Balanced Mode (SABM).

See Also:
Constant Field Values

UTYPE_DISC

public static final int UTYPE_DISC
Unshifted U frame subtype for Disconnect (DISC).

See Also:
Constant Field Values

UTYPE_UA

public static final int UTYPE_UA
Unshifted U frame subtype for Unnumbered Acknowledge (UA).

See Also:
Constant Field Values

UTYPE_SABME

public static final int UTYPE_SABME
Unshifted U frame subtype for Set Asynchronous Balanced Mode Extended (SABME).

See Also:
Constant Field Values

UTYPE_FRMR

public static final int UTYPE_FRMR
Deprecated. 2.0
Unshifted U frame subtype for obsolete Frame Reject (FRMR).

See Also:
Constant Field Values

UTYPE_XID

public static final int UTYPE_XID
Unshifted U frame subtype for Exchange Identification (XID).

See Also:
Constant Field Values

UTYPE_TEST

public static final int UTYPE_TEST
Unshifted U frame subtype for Test (TEST).

See Also:
Constant Field Values

PID_X25_PLP

public static final byte PID_X25_PLP
Protocol ID for CCITT X.25 PLP (also used by the ROSE network).

See Also:
Constant Field Values

PID_VJC_TCPIP

public static final byte PID_VJC_TCPIP
Protocol ID for Van Jacobson compressed TCP/IP packet, per RFC 1144.

See Also:
Constant Field Values

PID_VJUC_TCPIP

public static final byte PID_VJUC_TCPIP
Protocol ID for Van Jacobson uncompressed TCP/IP packet, per RFC 1144.

See Also:
Constant Field Values

PID_SEG_FRAG

public static final byte PID_SEG_FRAG
Protocol ID for AX.25 segmentation fragment.

See Also:
Constant Field Values

PID_OPENTRAC

public static final byte PID_OPENTRAC
Protocol ID for OpenTRAC.

See Also:
Constant Field Values

PID_TEXNET

public static final byte PID_TEXNET
Protocol ID for TEXNET datagram.

See Also:
Constant Field Values

PID_LQP

public static final byte PID_LQP
Protocol ID for Link Quality Protocol.

See Also:
Constant Field Values

PID_ATALK

public static final byte PID_ATALK
Protocol ID for Appletalk.

See Also:
Constant Field Values

PID_AARP

public static final byte PID_AARP
Protocol ID for Appletalk Address Resolution Protocol (ARP).

See Also:
Constant Field Values

PID_IP

public static final byte PID_IP
Protocol ID for ARPA Internet Protocol.

See Also:
Constant Field Values

PID_IARP

public static final byte PID_IARP
Protocol ID for ARPS Internet Address Resolution Protocol (ARP).

See Also:
Constant Field Values

PID_FLEXNET

public static final byte PID_FLEXNET
Protocol ID for FlexNet.

See Also:
Constant Field Values

PID_NETROM

public static final byte PID_NETROM
Protocol ID for NET/ROM.

See Also:
Constant Field Values

PID_NOLVL3

public static final byte PID_NOLVL3
Protocol ID for no level 3 protocol (also used for APRS).

See Also:
Constant Field Values

PID_ESCAPE

public static final byte PID_ESCAPE
Protocol ID for escape code indicating second byte of PID (not supported).

See Also:
Constant Field Values

PTYPES_S

public static final java.util.Map<java.lang.Byte,java.lang.String> PTYPES_S
Hashmap of Information (I) or Unnumbered Information (UI) frame protocol ID to protocol name strings.

See Also:
pid
Constructor Detail

AX25Frame

public AX25Frame()
Create an empty AX25Frame initialized for a UI frame containing an APRS packet.

Method Detail

decodeFrame

public static AX25Frame decodeFrame(byte[] buf,
                                    int offset,
                                    int length)
Create a AX25Frame from a byte array presumed to contain an AX.25 protocol sequence.

Parameters:
buf - byte array to read frame from
offset - zero-based index into the array where the frame starts
length - number of bytes making up the frame
Returns:
structured AX25Frame object, or null if byte array doesn't have enough bytes for a frame

getFrameTypeString

public java.lang.String getFrameTypeString()
Generate a string describing the type of the frame.

Returns:
descriptive String

getFrameType

public int getFrameType()
Get the type of this frame, as stored in the ctl byte.

Returns:
frame type code
See Also:
FRAMETYPE_I, FRAMETYPE_S, FRAMETYPE_U

getNS

public int getNS()
Get the transmission sequence number.

Returns:
sequence number
Throws:
java.lang.IllegalStateException - if this is not an I frame

getNR

public int getNR()
Get the reception sequence number.

Returns:
sequence number
Throws:
java.lang.IllegalStateException - if this is not an I frame

getSType

public int getSType()
Get the Supervisory frame subtype.

Returns:
S frame subtype (masked but not bit-shifted from its position in ctl bitmask)
See Also:
STYPE_RR, STYPE_RNR, STYPE_REJ, STYPE_SREJ

getP

public boolean getP()
Get poll bit.

Returns:
boolean state of poll bit

getUType

public int getUType()
Get Unordered frame subtype.

Returns:
U frame subtype (masked but not bit-shifted from its position in ctl bitmask)
See Also:
UTYPE_UI, UTYPE_DM, UTYPE_SABM, UTYPE_DISC, UTYPE_UA, UTYPE_SABME, UTYPE_FRMR, UTYPE_XID, UTYPE_TEST

write

public void write(java.io.OutputStream os)
           throws java.io.IOException
Transmit this AX25Frame to an output byte stream.

Parameters:
os - OutputStream to write the frame to
Throws:
java.io.IOException - if writing fails

dup

public AX25Frame dup()
Create a deep copy of this frame.

Returns:
duplicate AX25Frame instance

dupOnlyHeader

public AX25Frame dupOnlyHeader()
Create a deep copy of this frame, excluding the body. This is useful for digipeating messages received from APRS-IS, because it skips making a copy of the message body that will immediately be discarded as part of the 3rd-party re-packaging.

Returns:
almost-duplicate AX25Frame instance

getFrames

public AX25Frame[] getFrames(boolean incrementXmtCount,
                             byte protocolId,
                             java.lang.String senderCallsign)
Get the frames associated with this FrameSource (in this case, itself).

Specified by:
getFrames in interface AX25FrameSource
Parameters:
incrementXmtCount - indicate whether the transmit counter (used to cycle through proportional pathing) should be incremented
protocolId - indicate the protocol to generate this frame for (not relevant for digipeated frames); zero to indicate current protocol
senderCallsign - local sending callsign (ignored if frame already has the callsign filled in)
Returns:
one-element array point at this frame

getNumTransmitsBeforeDecay

public int getNumTransmitsBeforeDecay()
Get number of times frame will be retransmitted before inter-packet delay is increased.

Specified by:
getNumTransmitsBeforeDecay in interface AX25FrameSource
Returns:
transmission count before interval increase

getConnector

public Connector getConnector()
Specify the Connector this message should be transmitted through.

Specified by:
getConnector in interface AX25FrameSource
Returns:
a specific Connector instance to transmit through, or null for all applicable ports (Connector.CAP_XMT_PACKET_DATA and not rejecting this specific packet [such as IGateConnectors shouldn't re-transmit something received from the IGate])
See Also:
Connector.CAP_XMT_PACKET_DATA

isRealCallsign

public static boolean isRealCallsign(java.lang.String callsign)
Test if a callsign looks like a real callsign (at least one digit somewhere other than the last character, all letters uppercase). Note this will automatically strip off the SSID (if any) before testing. Note this is safe for empty strings, and will properly report them as not being a valid real-station callsign,

Parameters:
callsign - String callsign to test
Returns:
boolean true if callsign looks like real

getFirstDigi

public static java.lang.String getFirstDigi(AX25Callsign[] digipeaters)
Get the first actual digipeated digipeater station callsign in the digipeater sequence.

Parameters:
digipeaters - array of AX25Callsigns for digipeating a message
Returns:
String of first real callsign in sequence, or empty String if no actual digipeater callsign

getLastDigi

public static java.lang.String getLastDigi(AX25Callsign[] digipeaters)
Find the last callsign through which a frame has been digipeated.

Parameters:
digipeaters - array of digipeater callsigns
Returns:
String callsign of last digipeater entry that is marked as used, or empty String if none used

setCmd

public void setCmd(boolean isCmd)
Set the command bits in the sender and destination fields.

Parameters:
isCmd - boolean true if this is a command frame, false if a response

toString

public java.lang.String toString()
Return a String representing this AX25Frame object.

Overrides:
toString in class java.lang.Object
Returns:
descriptive String

getAsciiFrame

public java.lang.String getAsciiFrame()
Produce an ASCIIfied version of frame body.

Returns:
String version of frame body

getChecksum

public int getChecksum()
Compute a checksum for this frame to allow efficiently identifying duplicate frames. The checksum only covers the sender callsign and the body, as its purpose is to prevent duplicate digipeating. Alas, it won't work with duplicate transmit IGates, since they change the the sending callsign to that of the IGate and inject a third-party header into the body.

Returns:
int checksum of the current contents of this AX25Frame object

compareTo

public int compareTo(AX25Frame o)
Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Specified by:
compareTo in interface java.lang.Comparable<AX25Frame>
Parameters:
o - the object to be compared.
Returns:
a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
Throws:
java.lang.ClassCastException - if the specified object's type prevents it from being compared to this object.

equals

public boolean equals(java.lang.Object obj)
Indicates whether some other object is "equal to" this one.

Overrides:
equals in class java.lang.Object
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.

hashCode

public int hashCode()
Returns a hash code value for the object.

Overrides:
hashCode in class java.lang.Object
Returns:
a hash code value for this object.
See Also:
equals(Object)

isDuplicate

public boolean isDuplicate(AX25Frame other)
Test if this frame has the same contents (at least as regards duplicate checking) as the provided older frame.

Parameters:
other - AX25Frame to compare payloads with
Returns:
boolean true if this frame should be treated as a duplicate for digipeating purposes

getEstimatedBitCount

public int getEstimatedBitCount()
Estimate the number of bits needed to transmit this frame over RF in AX.25 standard physical layer (HDLC).

Returns:
bit count estimate