com.limegroup.gnutella.messages
Class GGEP

java.lang.Object
  extended bycom.limegroup.gnutella.messages.GGEP

public class GGEP
extends java.lang.Object

A mutable GGEP extension block. A GGEP block can be thought of as a collection of key/value pairs. A key (extension header) cannot be greater than 15 bytes. The value (extension data) can be 0 to 2^24-1 bytes. Values can be formatted as a number, boolean, or generic blob of binary data. If necessary (e.g., for query replies), GGEP will COBS-encode values to remove null bytes. The order of the extensions is immaterial. Extensions supported by LimeWire have keys specified in this class (prefixed by GGEP_HEADER...)


Field Summary
static java.lang.String GGEP_HEADER_ALTS
          The extension header (key) for AlternateLocation support
static java.lang.String GGEP_HEADER_BROWSE_HOST
          The extension header (key) for Browse Host.
static java.lang.String GGEP_HEADER_DAILY_AVERAGE_UPTIME
          The extension header (key) for average daily uptime.
static java.lang.String GGEP_HEADER_MULTICAST_RESPONSE
          The extension header (key) for QueryKey support.
static java.lang.String GGEP_HEADER_PUSH_PROXY
          The extension header (key) for PushProxy support.
static java.lang.String GGEP_HEADER_QUERY_KEY_SUPPORT
          The extension header (key) for QueryKey support.
static java.lang.String GGEP_HEADER_UNICAST_SUPPORT
          The extension header (key) for unicast protocol support.
static java.lang.String GGEP_HEADER_UP_SUPPORT
          The extension header (key) for Ultrapeer support.
static java.lang.String GGEP_HEADER_VENDOR_INFO
          The extension header (key) for vendor info.
static byte GGEP_PREFIX_MAGIC_NUMBER
          The GGEP prefix.
static int MAX_KEY_SIZE_IN_BYTES
          The maximum size of a extension header (key).
static int MAX_VALUE_SIZE_IN_BYTES
          The maximum size of a extension data (value).
 boolean notNeedCOBS
          False iff this should COBS encode values to prevent null bytes.
 
Constructor Summary
GGEP()
          Creates a new empty GGEP block.
GGEP(boolean notNeedCOBS)
          Creates a new empty GGEP block.
GGEP(byte[] messageBytes, int beginOffset, int[] endOffset)
          Constructs a GGEP instance based on the GGEP block beginning at messageBytes[beginOffset].
 
Method Summary
 boolean equals(java.lang.Object o)
           
 byte[] getBytes(java.lang.String key)
          Returns the value for a key, as raw bytes.
 java.util.Set getHeaders()
          Returns the set of keys.
 int getInt(java.lang.String key)
          Returns the value for a key, as an integer
 java.lang.String getString(java.lang.String key)
          Returns the value for a key, as a string.
 int hashCode()
           
 boolean hasKey(java.lang.String key)
          Returns whether this has the given key.
 void put(java.lang.String key)
          Adds a key without any value.
 void put(java.lang.String key, byte[] value)
          Adds a key with raw byte value.
 void put(java.lang.String key, int value)
          Adds a key with integer value.
 void put(java.lang.String key, java.lang.String value)
          Adds a key with string value, using the default character encoding.
static GGEP[] read(byte[] messageBytes, int beginOffset)
          Utility method for calling read(messageBytes, beginOffset, null).
static GGEP[] read(byte[] messageBytes, int beginOffset, int[] endOffset)
          Constructs an array of all GGEP blocks starting at messageBytes[beginOffset].
 void write(java.io.OutputStream out)
          Writes this GGEP instance as a properly formatted GGEP Block.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

GGEP_HEADER_BROWSE_HOST

public static final java.lang.String GGEP_HEADER_BROWSE_HOST
The extension header (key) for Browse Host.

See Also:
Constant Field Values

GGEP_HEADER_DAILY_AVERAGE_UPTIME

public static final java.lang.String GGEP_HEADER_DAILY_AVERAGE_UPTIME
The extension header (key) for average daily uptime.

See Also:
Constant Field Values

GGEP_HEADER_UNICAST_SUPPORT

public static final java.lang.String GGEP_HEADER_UNICAST_SUPPORT
The extension header (key) for unicast protocol support.

See Also:
Constant Field Values

GGEP_HEADER_VENDOR_INFO

public static final java.lang.String GGEP_HEADER_VENDOR_INFO
The extension header (key) for vendor info.

See Also:
Constant Field Values

GGEP_HEADER_UP_SUPPORT

public static final java.lang.String GGEP_HEADER_UP_SUPPORT
The extension header (key) for Ultrapeer support.

See Also:
Constant Field Values

GGEP_HEADER_QUERY_KEY_SUPPORT

public static final java.lang.String GGEP_HEADER_QUERY_KEY_SUPPORT
The extension header (key) for QueryKey support.

See Also:
Constant Field Values

GGEP_HEADER_MULTICAST_RESPONSE

public static final java.lang.String GGEP_HEADER_MULTICAST_RESPONSE
The extension header (key) for QueryKey support.

See Also:
Constant Field Values

GGEP_HEADER_PUSH_PROXY

public static final java.lang.String GGEP_HEADER_PUSH_PROXY
The extension header (key) for PushProxy support.

See Also:
Constant Field Values

GGEP_HEADER_ALTS

public static final java.lang.String GGEP_HEADER_ALTS
The extension header (key) for AlternateLocation support

See Also:
Constant Field Values

MAX_KEY_SIZE_IN_BYTES

public static final int MAX_KEY_SIZE_IN_BYTES
The maximum size of a extension header (key).

See Also:
Constant Field Values

MAX_VALUE_SIZE_IN_BYTES

public static final int MAX_VALUE_SIZE_IN_BYTES
The maximum size of a extension data (value).

See Also:
Constant Field Values

GGEP_PREFIX_MAGIC_NUMBER

public static final byte GGEP_PREFIX_MAGIC_NUMBER
The GGEP prefix. A GGEP block will start with this byte value.

See Also:
Constant Field Values

notNeedCOBS

public boolean notNeedCOBS
False iff this should COBS encode values to prevent null bytes. Default is false, to be conservative.

Constructor Detail

GGEP

public GGEP(boolean notNeedCOBS)
Creates a new empty GGEP block. Typically this is used for outgoing messages and mutated before encoding.

Parameters:
notNeedCOBS - true if nulls are allowed in extension values;false if this should activate COBS encoding if necessary to remove null bytes.

GGEP

public GGEP()
Creates a new empty GGEP block. Typically this is used for outgoing messages and mutated before encoding. This does do COBS encoding.


GGEP

public GGEP(byte[] messageBytes,
            int beginOffset,
            int[] endOffset)
     throws BadGGEPBlockException
Constructs a GGEP instance based on the GGEP block beginning at messageBytes[beginOffset]. If you are unsure of whether or not there is one GGEP Block, use the read method.

Parameters:
messageBytes - The bytes of the message.
beginOffset - The begin index of the GGEP prefix.
endOffset - If you want to get the offset where the GGEP block ends (more precisely, one above the ending index), then send me a int[1]. I'll put the endOffset in endOffset[0]. If you don't care, null will do....
Throws:
BadGGEPBlockException - Thrown if the block could not be parsed correctly.
Method Detail

write

public void write(java.io.OutputStream out)
           throws java.io.IOException
Writes this GGEP instance as a properly formatted GGEP Block.

Parameters:
out - This GGEP instance is written to out.
Throws:
java.io.IOException - Thrown if had error writing to out.

read

public static GGEP[] read(byte[] messageBytes,
                          int beginOffset,
                          int[] endOffset)
                   throws BadGGEPBlockException
Constructs an array of all GGEP blocks starting at messageBytes[beginOffset].

Parameters:
messageBytes - The input bytes to attempt to read one or more GGEP blocks from.
beginOffset - The begin index of the (first) GGEP prefix.
endOffset - If the reader wants to know where the last GGEP block was read, fill this with a blank int[1] and the endOffset will be placed here. Otherwise, null is allowed.
Throws:
BadGGEPBlockException - Thrown if ANY block could not be parsed correctly.

read

public static GGEP[] read(byte[] messageBytes,
                          int beginOffset)
                   throws BadGGEPBlockException
Utility method for calling read(messageBytes, beginOffset, null). Constructs an array of all GGEP blocks starting at messageBytes[beginOffset].

Parameters:
messageBytes - The input bytes to attempt to read one or more GGEP blocks from.
beginOffset - The begin index of the (first) GGEP prefix.
Throws:
BadGGEPBlockException - Thrown if ANY block could not be parsed correctly.

put

public void put(java.lang.String key,
                byte[] value)
         throws java.lang.IllegalArgumentException
Adds a key with raw byte value.

Parameters:
key - the name of the GGEP extension, whose length should be between 1 and 15, inclusive
value - the GGEP extension data
Throws:
java.lang.IllegalArgumentException - key is of an illegal length; or value contains a null bytes, null bytes are disallowed, and if you didn't allow nulls at construction but has nulls

put

public void put(java.lang.String key,
                java.lang.String value)
         throws java.lang.IllegalArgumentException
Adds a key with string value, using the default character encoding.

Parameters:
key - the name of the GGEP extension, whose length should be between 1 and 15, inclusive
value - the GGEP extension data
Throws:
java.lang.IllegalArgumentException - key is of an illegal length; or value contains a null bytes, null bytes are disallowed, if you didn't allow nulls at construction but has nulls

put

public void put(java.lang.String key,
                int value)
         throws java.lang.IllegalArgumentException
Adds a key with integer value.

Parameters:
key - the name of the GGEP extension, whose length should be between 1 and 15, inclusive
value - the GGEP extension data, which should be an unsigned integer
Throws:
java.lang.IllegalArgumentException - key is of an illegal length; or value is negative; or value contains a null bytes, null bytes are disallowed, and COBS encoding is not supported

put

public void put(java.lang.String key)
         throws java.lang.IllegalArgumentException
Adds a key without any value.

Parameters:
key - the name of the GGEP extension, whose length should be between 1 and 15, inclusive
Throws:
java.lang.IllegalArgumentException - key is of an illegal length.

getBytes

public byte[] getBytes(java.lang.String key)
                throws BadGGEPPropertyException
Returns the value for a key, as raw bytes.

Parameters:
key - the name of the GGEP extension
Returns:
the GGEP extension data associated with the key
Throws:
BadGGEPPropertyException - extension not found, was corrupt, or has no associated data. Note that BadGGEPPropertyException is is always thrown for extensions with no data; use hasKey instead.

getString

public java.lang.String getString(java.lang.String key)
                           throws BadGGEPPropertyException
Returns the value for a key, as a string.

Parameters:
key - the name of the GGEP extension
Returns:
the GGEP extension data associated with the key
Throws:
BadGGEPPropertyException - extension not found, was corrupt, or has no associated data. Note that BadGGEPPropertyException is is always thrown for extensions with no data; use hasKey instead.

getInt

public int getInt(java.lang.String key)
           throws BadGGEPPropertyException
Returns the value for a key, as an integer

Parameters:
key - the name of the GGEP extension
Returns:
the GGEP extension data associated with the key
Throws:
BadGGEPPropertyException - extension not found, was corrupt, or has no associated data. Note that BadGGEPPropertyException is is always thrown for extensions with no data; use hasKey instead.

hasKey

public boolean hasKey(java.lang.String key)
Returns whether this has the given key.

Parameters:
key - the name of the GGEP extension
Returns:
true if this has a key

getHeaders

public java.util.Set getHeaders()
Returns the set of keys.

Returns:
a set of all the GGEP extension header name in this, each as a String.

equals

public boolean equals(java.lang.Object o)
Returns:
True if the two Maps that represent header/data pairs are equivalent.

hashCode

public int hashCode()