PDU (UnetStack 3.4.0 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<String,Object> tx = new HashMap<>();
 tx.put("type", new Integer(7));
 tx.put("data", new Integer(42));
 byte[] bytes = pdu.encode(tx);
 Map<String,Object> 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
	`void`	`chars(String fieldname, int n)` Adds a string field to the PDU.
	`void`	`chars(String s)` Adds a string literal to the PDU.
	`void`	`charset(String cset)` Specifies the character encoding of text in 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.
	`void`	`filler(int len)` Adds filler bytes to PDU.
	`void`	`format()` Defines the format of the PDU.
	`void`	`int16(String fieldname)` Adds a signed 16-bit integer field to the PDU.
	`void`	`int16(int x)` Adds a signed 16-bit integer literal to the PDU.
	`void`	`int32(String fieldname)` Adds a signed 32-bit integer field to the PDU.
	`void`	`int32(int x)` Adds a signed 32-bit integer literal to the PDU.
	`void`	`int64(String fieldname)` Adds a signed 64-bit integer field to the PDU.
	`void`	`int64(long x)` Adds a signed 64-bit integer literal to the PDU.
	`void`	`int8(String fieldname)` Adds a signed byte field to the PDU.
	`void`	`int8(int x)` Adds a signed byte literal to the PDU.
	`void`	`length(int len)` Specifies the length of the PDU.
	`void`	`order(ByteOrder bo)` Specifies the byte ordering of multi-byte numbers.
	`void`	`padding(int x)` Adds padding bytes at the end of the PDU.
	`void`	`uint16(String fieldname)` Adds an unsigned 16-bit integer field to the PDU.
	`void`	`uint16(int x)` Adds an unsigned 16-bit integer literal to the PDU.
	`void`	`uint32(String fieldname)` Adds an unsigned 32-bit integer field to the PDU.
	`void`	`uint32(long x)` Adds an unsigned 32-bit integer literal to the PDU.
	`void`	`uint8(String fieldname)` Adds an unsigned byte field to the PDU.
	`void`	`uint8(int x)` Adds an unsigned byte literal to the PDU.
	`void`	`varbytes(String fieldname)` Adds a variable length byte byffer using wire encoding to the PDU.
	`void`	`varchars(String fieldname)` Adds a variable length string using wire encoding to the PDU.
	`static PDU`	`withFormat(Closure c)` Groovy builder method.

Inherited Methods Summary

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

- Method Detail
  - 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.
  - void chars(String s)
    
    Adds a string literal to the PDU.
    Parameters:
    s - value of the string literal.
  - void charset(String cset)
    
    Specifies the character encoding of text in the PDU.
    Parameters:
    cset - character set name.
  - 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.
  - 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.
  - void filler(int len)
    
    Adds filler bytes to PDU. Filler bytes are encoded as 0x00.
    Parameters:
    len - number of filler bytes to add.
  - 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
 }
 
```
  - void int16(String fieldname)
    
    Adds a signed 16-bit integer field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - void int16(int x)
    
    Adds a signed 16-bit integer literal to the PDU.
    Parameters:
    x - value of the literal.
  - void int32(String fieldname)
    
    Adds a signed 32-bit integer field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - void int32(int x)
    
    Adds a signed 32-bit integer literal to the PDU.
    Parameters:
    x - value of the literal.
  - void int64(String fieldname)
    
    Adds a signed 64-bit integer field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - void int64(long x)
    
    Adds a signed 64-bit integer literal to the PDU.
    Parameters:
    x - value of the literal.
  - void int8(String fieldname)
    
    Adds a signed byte field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - void int8(int x)
    
    Adds a signed byte literal to the PDU.
    Parameters:
    x - value of the literal.
  - void length(int len)
    
    Specifies the length of the PDU.
    Parameters:
    len - length of the PDU.
  - void order(ByteOrder bo)
    
    Specifies the byte ordering of multi-byte numbers.
    Parameters:
    bo - byte ordering.
  - 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.
  - void uint16(String fieldname)
    
    Adds an unsigned 16-bit integer field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - void uint16(int x)
    
    Adds an unsigned 16-bit integer literal to the PDU.
    Parameters:
    x - value of the literal.
  - void uint32(String fieldname)
    
    Adds an unsigned 32-bit integer field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - void uint32(long x)
    
    Adds an unsigned 32-bit integer literal to the PDU.
    Parameters:
    x - value of the literal.
  - void uint8(String fieldname)
    
    Adds an unsigned byte field to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - void uint8(int x)
    
    Adds an unsigned byte literal to the PDU.
    Parameters:
    x - value of the literal.
  - void varbytes(String fieldname)
    
    Adds a variable length byte byffer using wire encoding to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - void varchars(String fieldname)
    
    Adds a variable length string using wire encoding to the PDU.
    Parameters:
    fieldname - name of the field for encoding/decoding.
  - static PDU withFormat(@DelegatesTo(value=PDU, strategy=Closure.DELEGATE_FIRST) Closure c)
    
    Groovy builder method.

Summary:
Method

| Detail:
Method

[Groovy] Class PDU

Methods Summary

Inherited Methods Summary

Method Detail

void chars(String fieldname, int n)

void chars(String s)

void charset(String cset)

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

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

void filler(int len)

void format()

void int16(String fieldname)

void int16(int x)

void int32(String fieldname)

void int32(int x)

void int64(String fieldname)

void int64(long x)

void int8(String fieldname)

void int8(int x)

void length(int len)

void order(ByteOrder bo)

void padding(int x)

void uint16(String fieldname)

void uint16(int x)

void uint32(String fieldname)

void uint32(long x)

void uint8(String fieldname)

void uint8(int x)

void varbytes(String fieldname)

void varchars(String fieldname)

static PDU withFormat(@DelegatesTo(value=PDU, strategy=Closure.DELEGATE_FIRST) Closure c)