PDU (UnetStack 3.0.2 API)

org.arl.unet.PDU

Base class for easy encoding and decoding of PDUs.

When implementing protocols, we often need to assemble and parse PDUs. To ease this task, we have a PDU utility class to help. We first define a class with our PDU format:

public class MyPDU extends PDU {
    void format() {
      length(16);                    // 16 byte PDU
      order(ByteOrder.BIG_ENDIAN);   // byte ordering is big endian
      uint8("type");                 // 1 byte field "type"
      uint8(0x01);                   // literal byte 0x01
      filler(2);                     // 2 filler bytes
      uint16("data");                // 2 byte field "data" as unsigned short
      padding(0xff);                 // padded with 0xff to make 16 bytes
    }
 }

We can then encode and decode PDUs easily using this class:

Map tx = new HashMap();
 tx.put("type", new Integer(7));
 tx.put("data", new Integer(42));
 byte[] bytes = pdu.encode(tx);
 Map rx = pdu.decode(bytes);

In Groovy, the syntax can be simplified considerably:

def pdu = PDU.withFormat {
   length(16)                     // 16 byte PDU
   order(ByteOrder.BIG_ENDIAN)    // byte ordering is big endian
   uint8('type')                  // 1 byte field 'type'
   uint8(0x01)                    // literal byte 0x01
   filler(2)                      // 2 filler bytes
   uint16('data')                 // 2 byte field 'data' as unsigned short
   padding(0xff)                  // padded with 0xff to make 16 bytes
 }
 bytes = pdu.encode([type: 7, data: 42])
 data = pdu.decode(bytes)

Methods Summary

Methods
Type Params	Return Type	Name and description
	`protected void`	`chars(String fieldname, int n)` Adds a string field to the PDU.
	`protected void`	`chars(String s)` Adds a string literal to the PDU.
	`Map<String, Object>`	`decode(byte[] pdu)` Decodes a PDU into a map of fieldname to field value.
	`byte[]`	`encode(Map<String, Object> fields)` Encodes a PDU from a map of fieldname to field value.
	`protected void`	`filler(int len)` Adds filler bytes to PDU.
	`protected void`	`format()` Defines the format of the PDU.
	`protected void`	`int16(String fieldname)` Adds a signed 16-bit integer field to the PDU.
	`protected void`	`int16(int x)` Adds a signed 16-bit integer literal to the PDU.
	`protected void`	`int32(String fieldname)` Adds a signed 32-bit integer field to the PDU.
	`protected void`	`int32(int x)` Adds a signed 32-bit integer literal to the PDU.
	`protected void`	`int64(String fieldname)` Adds a signed 64-bit integer field to the PDU.
	`protected void`	`int64(long x)` Adds a signed 64-bit integer literal to the PDU.
	`protected void`	`int8(String fieldname)` Adds a signed byte field to the PDU.
	`protected void`	`int8(int x)` Adds a signed byte literal to the PDU.
	`protected void`	`length(int len)` Specifies the length of the PDU.
	`protected void`	`order(ByteOrder bo)` Specifies the byte ordering of multi-byte numbers.
	`protected void`	`padding(int x)` Adds padding bytes at the end of the PDU.
	`protected void`	`uint16(String fieldname)` Adds an unsigned 16-bit integer field to the PDU.
	`protected void`	`uint16(int x)` Adds an unsigned 16-bit integer literal to the PDU.
	`protected void`	`uint32(String fieldname)` Adds an unsigned 32-bit integer field to the PDU.
	`protected void`	`uint32(long x)` Adds an unsigned 32-bit integer literal to the PDU.
	`protected void`	`uint8(String fieldname)` Adds an unsigned byte field to the PDU.
	`protected void`	`uint8(int x)` Adds an unsigned byte literal to the PDU.

Inherited Methods Summary

Inherited Methods
Methods inherited from class	Name
`class Object`	`wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- Method Detail
  - protected void chars(String fieldname, int n)
    
    Adds a string field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
    n - number of bytes in the string.
  - protected void chars(String s)
    
    Adds a string literal to the PDU.
    Parameters:
    s - value of the string literal.
  - public Map<String, Object> decode(byte[] pdu)
    
    Decodes a PDU into a map of fieldname to field value.
    Parameters:
    pdu - byte array representing the PDU.
    Returns:
    map of fieldname to field value.
  - public byte[] encode(Map<String, Object> fields)
    
    Encodes a PDU from a map of fieldname to field value.
    Parameters:
    fields - map of fieldname to field value.
    Returns:
    byte array representing the PDU.
  - protected void filler(int len)
    
    Adds filler bytes to PDU. Filler bytes are encoded as 0x00.
    Parameters:
    len - number of filler bytes to add.
  - protected void format()
    
    Defines the format of the PDU. This method should be overridden by a derived class and used to specify the format of the PDU. Example:
```
 void format() {
   length(16);                    // 16 byte PDU
   order(ByteOrder.BIG_ENDIAN);   // byte ordering
   uint8("type");                 // 1 byte field "type"
   uint8(0x01)                    // literal byte 0x01
   filler(2)                      // 2 filler bytes
   uint16("data");                // 2 byte field "data" as unsigned short
   padding(0xff);                 // padded with 0xff to make 16 bytes
 }
 
```
  - protected void int16(String fieldname)
    
    Adds a signed 16-bit integer field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - protected void int16(int x)
    
    Adds a signed 16-bit integer literal to the PDU.
    Parameters:
    x - value of the literal.
  - protected void int32(String fieldname)
    
    Adds a signed 32-bit integer field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - protected void int32(int x)
    
    Adds a signed 32-bit integer literal to the PDU.
    Parameters:
    x - value of the literal.
  - protected void int64(String fieldname)
    
    Adds a signed 64-bit integer field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - protected void int64(long x)
    
    Adds a signed 64-bit integer literal to the PDU.
    Parameters:
    x - value of the literal.
  - protected void int8(String fieldname)
    
    Adds a signed byte field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - protected void int8(int x)
    
    Adds a signed byte literal to the PDU.
    Parameters:
    x - value of the literal.
  - protected void length(int len)
    
    Specifies the length of the PDU.
    Parameters:
    len - length of the PDU.
  - protected void order(ByteOrder bo)
    
    Specifies the byte ordering of multi-byte numbers.
    Parameters:
    bo - byte ordering.
  - protected void padding(int x)
    
    Adds padding bytes at the end of the PDU. The number of padding bytes is automatically determined based on the specified length of the PDU.
    Parameters:
    x - value to use for padding.
  - protected void uint16(String fieldname)
    
    Adds an unsigned 16-bit integer field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - protected void uint16(int x)
    
    Adds an unsigned 16-bit integer literal to the PDU.
    Parameters:
    x - value of the literal.
  - protected void uint32(String fieldname)
    
    Adds an unsigned 32-bit integer field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - protected void uint32(long x)
    
    Adds an unsigned 32-bit integer literal to the PDU.
    Parameters:
    x - value of the literal.
  - protected void uint8(String fieldname)
    
    Adds an unsigned byte field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - protected void uint8(int x)
    
    Adds an unsigned byte literal to the PDU.
    Parameters:
    x - value of the literal.

Summary:
Method

| Detail:
Method

[Java] Class PDU

Methods Summary

Inherited Methods Summary

Method Detail

protected void chars(String fieldname, int n)

protected void chars(String s)

public Map<String, Object> decode(byte[] pdu)

public byte[] encode(Map<String, Object> fields)

protected void filler(int len)

protected void format()

protected void int16(String fieldname)

protected void int16(int x)

protected void int32(String fieldname)

protected void int32(int x)

protected void int64(String fieldname)

protected void int64(long x)

protected void int8(String fieldname)

protected void int8(int x)

protected void length(int len)

protected void order(ByteOrder bo)

protected void padding(int x)

protected void uint16(String fieldname)

protected void uint16(int x)

protected void uint32(String fieldname)

protected void uint32(long x)

protected void uint8(String fieldname)

protected void uint8(int x)