org.jnetpcap.protocol.tcpip
Class Udp

java.lang.Object
  org.jnetpcap.nio.JMemory
      org.jnetpcap.nio.JBuffer
          org.jnetpcap.packet.JHeader
              org.jnetpcap.protocol.tcpip.Udp

All Implemented Interfaces:

JHeaderChecksum, JPayloadAccessor

@Header(length=8)
public class Udp
extends JHeader
implements JHeaderChecksum

User Datagram Protocol (UDP).

The User Datagram Protocol (UDP) is one of the core members of the Internet Protocol Suite, the set of network protocols used for the Internet. With UDP, computer applications can send messages, in this case referred to as datagrams, to other hosts on an Internet Protocol (IP) network without requiring prior communications to set up special transmission channels or data paths. The protocol was designed by David P. Reed in 1980 and formally defined in RFC 768.

UDP uses a simple transmission model without implicit hand-shaking dialogues for providing reliability, ordering, or data integrity. Thus, UDP provides an unreliable service and datagrams may arrive out of order, appear duplicated, or go missing without notice. UDP assumes that error checking and correction is either not necessary or performed in the application, avoiding the overhead of such processing at the network interface level. Time-sensitive applications often use UDP because dropping packets is preferable to waiting for delayed packets, which may not be an option in a real-time system. If error correction facilities are needed at the network interface level, an application may use the Transmission Control Protocol (TCP) or Stream Control Transmission Protocol (SCTP) which are designed for this purpose.

UDP's stateless nature is also useful for servers answering small queries from huge numbers of clients. Unlike TCP, UDP is compatible with packet broadcast (sending to all on local network) and multicasting (send to all subscribers).

Common network applications that use UDP include: the Domain Name System (DNS), streaming media applications such as IPTV, Voice over IP (VoIP), Trivial File Transfer Protocol (TFTP) and many online games.

UDP is a minimal message-oriented Transport Layer protocol that is documented in IETF RFC 768.

UDP provides no guarantees to the upper layer protocol for message delivery and the UDP protocol layer retains no state of UDP messages once sent. For this reason, UDP is sometimes referred to as Unreliable Datagram Protocol.

UDP provides application multiplexing (via port numbers) and integrity verification (via checksum) of the header and payload. If transmission reliability is desired, it must be implemented in the user's application.

The UDP header consists of 4 fields, all of which are 2 bytes (16 bits). The use of two of those is optional in IPv4 (pink background in table). In IPv6 only the source port is optional:

• Source port number - This field identifies the sender's port when meaningful and should be assumed to be the port to reply to if needed. If not used, then it should be zero. If the source host is the client, the port number is likely to be an ephemeral port number. If the source host is the server, the port number is likely to be a well-known port number.
• Destination port number - This field identifies the receiver's port and is required. Similar to source port number, if the client is the destination host then the port number will likely be an ephemeral port number and if the destination host is the server then the port number will likely be a well-known port number.
• Length - A field that specifies the length in bytes of the entire datagram: header and data. The minimum length is 8 bytes since that's the length of the header. The field size sets a theoretical limit of 65,535 bytes (8 byte header + 65,527 bytes of data) for a UDP datagram. The practical limit for the data length which is imposed by the underlying IPv4 protocol is 65,507 bytes (65,535 - 8 byte UDP header - 20 byte IP header).
• Checksum - The checksum field is used for error-checking of the header and data. If the checksum is omitted in IPv4, the field uses the value all-zeros. This field is not optional for IPv6.

Description source: http://wikipedia.org/wiki/User_Datagram_Protocol

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Nested Class Summary

Nested classes/interfaces inherited from class org.jnetpcap.packet.JHeader

JHeader.State

Nested classes/interfaces inherited from class org.jnetpcap.nio.JMemory

JMemory.Type

Field Summary

static int

ID Unique numerical ID of this header.

Fields inherited from class org.jnetpcap.packet.JHeader

annotatedHeader, BYTE, EMPTY_HEADER_ARRAY, isSubHeader, packet, state

Fields inherited from class org.jnetpcap.nio.JMemory

JNETPCAP_LIBRARY_NAME, MAX_DIRECT_MEMORY_DEFAULT, POINTER

Constructor Summary

Udp()

Method Summary

int	calculateChecksum() Calculates a checksum using protocol specification for a header.
int	checksum() The checksum field is used for error-checking of the header and data.
void	checksum(int value) Sets the new value for checksum field in the header.
java.lang.String	checksumDescription() Returns a dynamic description of the checksum field.
int	destination() This field identifies the receiver's port and is required.
void	destination(int value) Sets a new unsigned 16-bit integer value for the udp port number field.
boolean	isChecksumValid() Checks if the checksum is valid, for un-fragmented packets.
int	length() A field that specifies the length in bytes of the entire datagram: header and data.
void	length(int value) Sets a new unsigned 16-bit integer value for the udp field.
int	source() This field identifies the sender's port when meaningful and should be assumed to be the port to reply to if needed.
void	source(int value) Sets a new unsigned 16-bit integer value for the udp port number field.

Methods inherited from class org.jnetpcap.packet.JHeader

decode, decodeHeader, getAnnotatedHeader, getDescription, getFields, getGap, getGapLength, getGapOffset, getHeader, getHeaderLength, getHeaderOffset, getId, getIndex, getLength, getName, getNextHeaderId, getNextHeaderOffset, getNicname, getOffset, getPacket, getParent, getPayload, getPayloadLength, getPayloadOffset, getPostfix, getPostfixLength, getPostfixOffset, getPrefix, getPrefixLength, getPrefixOffset, getPreviousHeaderId, getPreviousHeaderOffset, getState, getSubHeaders, hasDescription, hasGap, hasNextHeader, hasPayload, hasPostfix, hasPrefix, hasPreviousHeader, hasSubHeaders, isFragmented, isGapTruncated, isHeaderTruncated, isPayloadTruncated, isPostfixTruncated, isPrefixTruncated, peer, peer, peerPayloadTo, setPacket, setSubHeaders, sizeof, toString, transferPayloadTo, transferPayloadTo, transferPayloadTo, validateHeader

Methods inherited from class org.jnetpcap.nio.JBuffer

findUTF8String, getByte, getByteArray, getByteArray, getByteArray, getDouble, getFloat, getInt, getLong, getShort, getUByte, getUInt, getUShort, getUTF8Char, getUTF8String, getUTF8String, getUTF8String, getUTF8String, isReadonly, order, order, peer, peer, peer, peer, setByte, setByteArray, setByteBuffer, setDouble, setFloat, setInt, setLong, setShort, setShort0, setUByte, setUInt, setUShort, transferFrom, transferFrom, transferFrom, transferTo, transferTo, transferTo

Methods inherited from class org.jnetpcap.nio.JMemory

availableDirectMemory, check, cleanup, createReference, isInitialized, isJMemoryBasedOwner, isOwner, maxDirectMemory, peer, reservedDirectMemory, setSize, size, softDirectMemory, toDebugString, toHexdump, toHexdump, totalActiveAllocated, totalAllocateCalls, totalAllocated, totalAllocatedSegments0To255Bytes, totalAllocatedSegments256OrAbove, totalDeAllocateCalls, totalDeAllocated, transferFrom, transferFrom, transferFromDirect, transferOwnership, transferTo, transferTo, transferTo, transferTo, transferTo, transferTo0

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ID

public static final int ID

Unique numerical ID of this header.

See Also:

Constant Field Values

Constructor Detail

Udp

public Udp()

Method Detail

calculateChecksum

public int calculateChecksum()

Calculates a checksum using protocol specification for a header. Checksums for partial headers or fragmented packets (unless the protocol alows it) are not calculated.

The method used to compute the checksum is defined in RFC 768:

 Checksum is the 16-bit one's complement of the one's complement sum of 
 a pseudo header of information from the IP header, the UDP header, 
 and the data, padded with zero octets at the end (if necessary) to make 
 a multiple of two octets.
 

In other words, all 16-bit words are summed using one's complement arithmetic. The sum is then one's complemented to yield the value of the UDP checksum field. If the checksum calculation results in the value zero (all 16 bits 0) it should be sent as the one's complement (all 1's). The difference between IPv4 and IPv6 is in the data used to compute the checksum.

Specified by:

calculateChecksum in interface JHeaderChecksum

Returns:

header's calculated checksum

checksum

@Field(offset=48,
       length=16,
       format="%x")
public int checksum()

The checksum field is used for error-checking of the header and data. If the checksum is omitted in IPv4, the field uses the value all-zeros. This field is not optional for IPv6.

Specified by:

checksum in interface JHeaderChecksum

Returns:

value of checksum field as 16-bit unsigned integer

checksum

public void checksum(int value)

Sets the new value for checksum field in the header. Typical usage is

 Udp udp = ...; // Acquire a udp header from somewhere
 udp.destination(123);
 udp.source(321);
 udp.checksum(udp.cacluateChecksum());
 

Parameters:

value - new unsigned 16-bit integer value for checksum

checksumDescription

@Dynamic(value=DESCRIPTION)
public java.lang.String checksumDescription()

Returns a dynamic description of the checksum field. Specifically it checks and displays, as description, the state of the checksum field, if it matches the calculated checksum or not.

Returns:

additional information about the state of the checksum field

destination

@Field(offset=16,
       length=16)
@FlowKey(index=2,
         reversable=true)
public int destination()

This field identifies the receiver's port and is required. Similar to source port number, if the client is the destination host then the port number will likely be an ephemeral port number and if the destination host is the server then the port number will likely be a well-known port number.

Returns:

value of destination port as 16-bit unsigned integer

destination

public void destination(int value)

Sets a new unsigned 16-bit integer value for the udp port number field.

Parameters:

value - new value to be stored in the destination field

isChecksumValid

public boolean isChecksumValid()

Checks if the checksum is valid, for un-fragmented packets. If a packet is fragmented, the checksum is not verified as data to is incomplete, but the method returns true none the less.

Specified by:

isChecksumValid in interface JHeaderChecksum

Returns:

true if checksum checks out or if this is a fragment, otherwise if the computed checksum does not match the stored checksum false is returned

length

@Field(offset=32,
       length=16)
public int length()

A field that specifies the length in bytes of the entire datagram: header and data. The minimum length is 8 bytes since that's the length of the header. The field size sets a theoretical limit of 65,535 bytes (8 byte header + 65,527 bytes of data) for a UDP datagram. The practical limit for the data length which is imposed by the underlying Ip4 protocol is 65,507 bytes (65,535 - 8 byte UDP header - 20 byte IP header).

Returns:

value of length field as 16-bit unsigned integer

length

public void length(int value)

Sets a new unsigned 16-bit integer value for the udp field.

Parameters:

value - new value to be stored in the length field

source

@Field(offset=0,
       length=16)
@FlowKey(index=2,
         reversable=true)
public int source()

This field identifies the sender's port when meaningful and should be assumed to be the port to reply to if needed. If not used, then it should be zero. If the source host is the client, the port number is likely to be an ephemeral port number. If the source host is the server, the port number is likely to be a well-known port number.

Returns:

value of source port as 16-bit unsigned integer

source

public void source(int value)

Sets a new unsigned 16-bit integer value for the udp port number field.

Parameters:

value - new value to be stored in the source field