net.kano.joscar.tlv
Class Tlv

java.lang.Object
  Tlv

All Implemented Interfaces:

LiveWritable, Writable

public final class Tlv

extends java.lang.Object

implements Writable

Represents a "Type-Length-Value" block, a very popular data structure in the OSCAR protocol. Fun trivia: as of this writing, this class is referenced 267 times throughout joscar. A TLV simply contains a two-byte unsigned "type" and a "value" whose binary length is less than 65536 bytes. This class is immutable.

Constructor Summary

Tlv(ByteBlock tlvBytes)
Creates a new TLV from the beginning of the given data block.

Tlv(int type)
Creates a TLV of the given type with no data block.

Tlv(int type, Writable data)
Creates a TLV of the given type with the given data block.

Method Summary

ByteBlock	getData() Returns this TLV's data block.
java.lang.String	getDataAsString() Returns this TLV's data block decoded into an US-ASCII string.
long	getDataAsUInt() Returns an unsigned integer read from the first four bytes of this TLV's data block, or -1 if fewer than four bytes exist in the block.
int	getDataAsUShort() Returns an unsigned integer read from the first two bytes of this TLV's data block, or -1 if fewer than two bytes exist in the block.
LiveWritable	getDataWriter() Returns the object that will be used to write the TLV data to a stream.
static Tlv	getStringInstance(int type, java.lang.String string) Returns a new TLV of the given type containing the given string encoded to bytes with the US-ASCII encoder.
int	getTotalSize() Returns the total size of this object, as read from an input stream.
int	getType() Returns this TLV's type.
static Tlv	getUIntInstance(int type, long number) Returns a new TLV of the given type containing the given value as a four-byte unsigned integer as its data block.
static Tlv	getUShortInstance(int type, int number) Returns a new TLV of the given type containing the given value as a two-byte unsigned integer as its data block.
long	getWritableLength() Returns the length of the data that was or will be written in a call to write.
static boolean	isValidTLV(ByteBlock tlvBytes) Returns true if there is a valid TLV at the beginning of the given data block.
java.lang.String	toString()
void	write(java.io.OutputStream out) Writes a representation of this object to the given stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

Tlv

public Tlv(int type)

Creates a TLV of the given type with no data block. Equivalent to calling new Tlv(type, ByteBlock.EMPTY_BLOCK).

Parameters:

type - the type of this TLV

Tlv

public Tlv(int type,
           Writable data)

Creates a TLV of the given type with the given data block.

Parameters:

type - the type of this TLV

data - this TLV's data block

Tlv

public Tlv(ByteBlock tlvBytes)
    throws java.lang.IllegalArgumentException

Creates a new TLV from the beginning of the given data block. The total number of bytes read can be returned by calling getTotalSize.

Parameters:

tlvBytes - a block of data containing a TLV at the beginning

Throws:

java.lang.IllegalArgumentException - if the beginning of the given byte block does not contain a valid TLV at the beginning

Method Detail

getStringInstance

public static Tlv getStringInstance(int type,
                                    java.lang.String string)

Returns a new TLV of the given type containing the given string encoded to bytes with the US-ASCII encoder. In other words, creates a TLV containing the given ASCII string.

Parameters:

type - the type of the TLV to be returned

string - the ASCII string to use as the TLV's data

Returns:

a TLV of the given type containing the given ASCII string as its data block

getUShortInstance

public static Tlv getUShortInstance(int type,
                                    int number)

Returns a new TLV of the given type containing the given value as a two-byte unsigned integer as its data block.

Parameters:

type - the type of the TLV to be returned

number - the value of the TLV, to be encoded as a two-byte unsigned integer

Returns:

a TLV of the given type with the given value as its data block

getUIntInstance

public static Tlv getUIntInstance(int type,
                                  long number)

Returns a new TLV of the given type containing the given value as a four-byte unsigned integer as its data block.

Parameters:

type - the type of the TLV to be returned

number - the value of the TLV, to be encoded as a four-byte unsigned integer

Returns:

a TLV of the given type with the given value as its data block

isValidTLV

public static boolean isValidTLV(ByteBlock tlvBytes)

Returns true if there is a valid TLV at the beginning of the given data block. This only checks for the length of the block, and in no way performs validation on its contents.

Parameters:

tlvBytes - the bytes supposedly containing a TLV at the beginning

Returns:

whether or not a valid TLV exists at the beginning of the given block of data

getType

public final int getType()

Returns this TLV's type. This will be an integer ranging inclusively from 0 to BinaryTools.USHORT_MAX.

Returns:

this TLV's type

getData

public final ByteBlock getData()

Returns this TLV's data block. Note that if this TLV was created with a Writable that is not a ByteBlock, a byte block is generated from that Writable, which may be a computationally expensive operation.

Returns:

this TLV's data block

getDataWriter

public final LiveWritable getDataWriter()

Returns the object that will be used to write the TLV data to a stream. May be a ByteBlock.

Returns:

the object that will be used to write the TLV data block to a stream with write(java.io.OutputStream)

getDataAsString

public final java.lang.String getDataAsString()

Returns this TLV's data block decoded into an US-ASCII string. In other words, reads the TLV's data block as if it were an ASCII string.

Returns:

an ASCII string read from this TLV's data block

See Also:

BinaryTools.getAsciiString(net.kano.joscar.ByteBlock)

getDataAsUShort

public final int getDataAsUShort()

Returns an unsigned integer read from the first two bytes of this TLV's data block, or -1 if fewer than two bytes exist in the block.

Returns:

an unsigned two-byte integer read from this TLV's data block, or -1 if none exists

See Also:

BinaryTools.getUShort(ByteBlock, int)

getDataAsUInt

public final long getDataAsUInt()

Returns an unsigned integer read from the first four bytes of this TLV's data block, or -1 if fewer than four bytes exist in the block.

Returns:

an unsigned four-byte integer read from this TLV's data block, or -1 if none exists

See Also:

BinaryTools.getUInt(ByteBlock, int)

getTotalSize

public final int getTotalSize()

Returns the total size of this object, as read from an input stream. Will be -1 if this TLV was not read from a stream but instead constructed manually.

Returns:

the total size, in bytes, of this object, or -1 if this object wasn't read from an incoming stream

getWritableLength

public long getWritableLength()

Description copied from interface: Writable

Returns the length of the data that was or will be written in a call to write. The value returned by this method must not change after its first invocation.

Specified by:

getWritableLength in interface Writable

Returns:

the length of the data to be written by write

write

public void write(java.io.OutputStream out)
           throws java.io.IOException

Description copied from interface: Writable

Writes a representation of this object to the given stream. The length of the data written by this function must match any value previously returned by getWritableLength.

Specified by:

write in interface Writable

Parameters:

out - the stream to which to write

Throws:

java.io.IOException - if an I/O error occurs

toString

public java.lang.String toString()