net.kano.joscar.tlv
Class Tlv

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