com.limegroup.gnutella.messages
Class GGEP

java.lang.Object
  com.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()