net.kano.joscar.snaccmd
Class ExtraInfoData

java.lang.Object
  ExtraInfoData

All Implemented Interfaces:

LiveWritable, Writable

public final class ExtraInfoData

extends java.lang.Object

implements Writable

A data structure used to hold data in ExtraInfoBlocks, containing a set of flags and a block of data.

A few notes on flags:

• When an extra info block received from the server is an icon hash block (like in a FullUserInfo):
  • If the flags include the FLAG_HASH_PRESENT bit, the data field is a buddy icon hash (in MD5 format). If the FLAG_HASH_PRESENT bit is off,that user may not have an icon, and the data field will (normally) be HASH_SPECIAL. The significance of HASH_SPECIAL is unknown at the time of this writing. One should note that if the flags include the FLAG_HASH_PRESENT bit, the data block may still be HASH_SPECIAL.
  • When received in an ExtraInfoAck, the flags FLAG_UPLOAD_ICON or FLAG_ALREADY_HAVE_ICON may be present. If FLAG_UPLOAD_ICON is present, the client should upload the user's buddy icon to the buddy icon server (with an UploadIconCmd. If FLAG_ALREADY_HAVE_ICON is present, the server has your buddy icon cached and no further action is necessary. Normally, the FLAG_ALREADY_HAVE_ICON flag is accompanied by a FLAG_HASH_PRESENT flag; the FLAG_UPLOAD_ICON flag normally is the only flag set (if, of course, it is set).
• When sending icon data to the server, like in a IconItem:
  • When setting a buddy icon, FLAG_HASH_PRESENT should be set and the data block should be an MD5 hash of the icon.
  • When clearing (removing) a buddy icon, no flags should be set (FLAG_DEFAULT) and the data block should be #HASH_SPECIAL.
• When setting an iChat availability message, the flag FLAG_AVAILMSG_PRESENT should be set. The data should be as follows:
  • An unsigned two-byte value indicating the length of the message data
  • The message data: the message string encoded as UTF-8
  • Two zero bytes
• To "unset" or clear an iChat availability message, one should simply set an empty (zero-length) availability message.

Note that, as used above, a "flag" means a single bit, and a flag being "present," "on"," or "included" means that the bit is "on." For example, to see if an extra info data's FLAG_HASH_PRESENT flag is on, one could use code such as the following:

if ((extraInfoData.getFlags()
        & ExtraInfoData.FLAG_HASH_PRESENT) != 0) {
    System.out.println("this extra info data block "
            + "contains a buddy icon MD5 hash!");
}
 

Field Summary

static int	FLAG_ALREADY_HAVE_ICON A flag indicating that the server already has a copy of your buddy icon.
static int	FLAG_AVAILMSG_PRESENT A flag indicating that an iChat availability message is present.
static int	FLAG_DEFAULT A flagset with no flags on (0x00).
static int	FLAG_HASH_PRESENT A flag indicating that a hash (for example, an MD5 hash of the user's buddy icon) is present.
static int	FLAG_UPLOAD_ICON A flag indicating that the client should upload its buddy icon.
static ByteBlock	HASH_SPECIAL A "special" icon hash which appears to indicate that no icon has been set.

Constructor Summary

ExtraInfoData(int flags, ByteBlock data)
Creates a new extra info block object with the given flags and given data block.

Method Summary

ByteBlock	getData() Returns the data stored in this extra info data block.
int	getFlags() Returns the flags stored in this extra info data object.
int	getTotalSize() Returns the size, in bytes, of this object, as read from a block of binary data.
long	getWritableLength() Returns the length of the data that was or will be written in a call to write.
static ExtraInfoData	readExtraInfoData(ByteBlock block) Reads an extra info data block from the given block of binary data.
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

Field Detail

FLAG_DEFAULT

public static final int FLAG_DEFAULT

A flagset with no flags on (0x00).

See Also:

Constant Field Values

FLAG_HASH_PRESENT

public static final int FLAG_HASH_PRESENT

A flag indicating that a hash (for example, an MD5 hash of the user's buddy icon) is present. See above for details.

See Also:

Constant Field Values

FLAG_UPLOAD_ICON

public static final int FLAG_UPLOAD_ICON

A flag indicating that the client should upload its buddy icon. See above for details.

See Also:

Constant Field Values

FLAG_ALREADY_HAVE_ICON

public static final int FLAG_ALREADY_HAVE_ICON

A flag indicating that the server already has a copy of your buddy icon. This flag is normally accompanied by FLAG_HASH_PRESENT. See above for details.

See Also:

Constant Field Values

FLAG_AVAILMSG_PRESENT

public static final int FLAG_AVAILMSG_PRESENT

A flag indicating that an iChat availability message is present. See above for details.

See Also:

Constant Field Values

HASH_SPECIAL

public static final ByteBlock HASH_SPECIAL

A "special" icon hash which appears to indicate that no icon has been set. See above for details.

Constructor Detail

ExtraInfoData

public ExtraInfoData(int flags,
                     ByteBlock data)
              throws java.lang.IllegalArgumentException

Creates a new extra info block object with the given flags and given data block. One should note that the block of data must contain no more than BinaryTools.UBYTE_MAX (255) bytes.

Parameters:

flags - a set of bit flags, like FLAG_AVAILMSG_PRESENT

data - a block of data to store in this extra info data block

Throws:

java.lang.IllegalArgumentException - if data.length > BinaryTools.UBYTE_MAX

Method Detail

readExtraInfoData

public static ExtraInfoData readExtraInfoData(ByteBlock block)

Reads an extra info data block from the given block of binary data. The total number of bytes read can be retrieved by calling getTotalSize on the returned object. Note that this will return null if no valid extra info data block can be read.

Parameters:

block - the block containing an extra info data block

Returns:

an extra info data block object read from the given data block, or null if no valid block could be read

getFlags

public final int getFlags()

Returns the flags stored in this extra info data object. The returned value will normally be a bitwise combination of the FLAG_* constants defined in this class. See above for details on how to check for specific flags.

Returns:

a set of bit flags associated with this extra info data block

getData

public final ByteBlock getData()

Returns the data stored in this extra info data block. The type of the returned data may be inferred from this object's flags.

Returns:

the data contained in this extra info data block

getTotalSize

public final int getTotalSize()

Returns the size, in bytes, of this object, as read from a block of binary data. Will be -1 if this object was not read from a data block with readExtraInfoData.

Returns:

the total size of this object, in bytes

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()