net.kano.joscar.snaccmd
Class CapabilityBlock

java.lang.Object
  extended byCapabilityBlock
All Implemented Interfaces:
LiveWritable, Writable

public final class CapabilityBlock
extends java.lang.Object
implements Writable

Represents a single "capability" that a client may have. Such capabilities include being able to invited to chat rooms, hold Direct IM sessions, and receive files. Capabilities are represented as unique sixteen-byte blocks that are sent to the server upon connecting; these blocks are visible to anyone who can view your user info, and clients can use them to determine which operations are possible (such as whether the user can send a file to a given other user).

A standard set of these blocks is used and recognized by WinAIM, gaim, and iChat, among other OSCAR-based AIM clients; these blocks are defined as constants in this class. Other blocks can be easily created and advertised in order to, say, create your own inter-client feature such as encryption (which Trillian does with its "Trillian encryption" block).


Field Summary
static CapabilityBlock BLOCK_ADDINS
          A capability block indicating that a client allows for using "add-ins" like MS Hearts, NetMeeting, and Quake II with other buddies.
static CapabilityBlock BLOCK_CHAT
          A capability block used to indicate that a client is able to receive invitations to chat rooms.
static CapabilityBlock BLOCK_DIRECTIM
          A capability block used to indicate that a client can receive a Direct IM invitation.
static CapabilityBlock BLOCK_ENCRYPTION
          A capability block indicating that the user is available for Secure IM and may be available for other secure communcations (secure chat rooms, file transfer, and so on).
static CapabilityBlock BLOCK_FILE_GET
          A capability block used to indicate that a client can receive requests to list files he or she is sharing.
static CapabilityBlock BLOCK_FILE_SEND
          A capability block used to indicate that a client can be sent files.
static CapabilityBlock BLOCK_GAMES
          The first of two blocks used to indicate that a client can receive invitations to play games.
static CapabilityBlock BLOCK_GAMES2
          The second of two blocks used to indicate that a client can receive invitations to play games.
static CapabilityBlock BLOCK_ICON
          A capability block used to indicate that a client can receive buddy icons.
static CapabilityBlock BLOCK_ICQCOMPATIBLE
          A capability block that indicates that a client can chat with ICQ users.
static CapabilityBlock BLOCK_SENDBUDDYLIST
          A capability block used to indicate that a client can receive a copy of another user's buddy list.
static CapabilityBlock BLOCK_SHORTCAPS
          A capability block indicating that the client is capable of parsing "short capability blocks."
static CapabilityBlock BLOCK_SOMETHING
          A capability block whose purpose is unknown at the time of this writing.
static CapabilityBlock BLOCK_TRILLIANCRYPT
          A capability block used to indicate that a client can chat using "Trillian encryption."
static CapabilityBlock BLOCK_VOICE
          A capability block used to indicate that a client is able to receive voice chat invitations.
 
Constructor Summary
CapabilityBlock(ByteBlock block)
          Creates a new capability block from the given sixteen-byte block.
 
Method Summary
static byte[] convertToBytes(CapabilityBlock[] capabilities)
          Converts the given list of capabilities to a block of bytes, suitable for sending in a InfoData structure.
 boolean equals(java.lang.Object other)
          Returns true if this and the given CapabilityBlock represent the same capability.
 ByteBlock getBlock()
          Returns the sixteen-byte block that identifies this capability block.
static CapabilityBlock[] getCapabilityBlocks(ByteBlock block)
          Extracts a list of capability blocks from the given data block.
 long getWritableLength()
          Returns the length of the data that was or will be written in a call to write.
 int hashCode()
           
 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, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

BLOCK_CHAT

public static final CapabilityBlock BLOCK_CHAT
A capability block used to indicate that a client is able to receive invitations to chat rooms. Note that this capability need not be advertised in order to create or join rooms or to invite others to chat rooms.


BLOCK_VOICE

public static final CapabilityBlock BLOCK_VOICE
A capability block used to indicate that a client is able to receive voice chat invitations.


BLOCK_FILE_SEND

public static final CapabilityBlock BLOCK_FILE_SEND
A capability block used to indicate that a client can be sent files.


BLOCK_DIRECTIM

public static final CapabilityBlock BLOCK_DIRECTIM
A capability block used to indicate that a client can receive a Direct IM invitation.


BLOCK_ICON

public static final CapabilityBlock BLOCK_ICON
A capability block used to indicate that a client can receive buddy icons. Note that this system, however, is becoming obsolete with the recent inception of the icon service.


BLOCK_FILE_GET

public static final CapabilityBlock BLOCK_FILE_GET
A capability block used to indicate that a client can receive requests to list files he or she is sharing.


BLOCK_GAMES

public static final CapabilityBlock BLOCK_GAMES
The first of two blocks used to indicate that a client can receive invitations to play games. This block and BLOCK_GAMES2 are treated as if they are the same block by WinAIM and other clients.


BLOCK_GAMES2

public static final CapabilityBlock BLOCK_GAMES2
The second of two blocks used to indicate that a client can receive invitations to play games. This block and BLOCK_GAMES are treated as if they are the same block by WinAIM and other clients.


BLOCK_SENDBUDDYLIST

public static final CapabilityBlock BLOCK_SENDBUDDYLIST
A capability block used to indicate that a client can receive a copy of another user's buddy list.


BLOCK_TRILLIANCRYPT

public static final CapabilityBlock BLOCK_TRILLIANCRYPT
A capability block used to indicate that a client can chat using "Trillian encryption."


BLOCK_ICQCOMPATIBLE

public static final CapabilityBlock BLOCK_ICQCOMPATIBLE
A capability block that indicates that a client can chat with ICQ users.


BLOCK_ADDINS

public static final CapabilityBlock BLOCK_ADDINS
A capability block indicating that a client allows for using "add-ins" like MS Hearts, NetMeeting, and Quake II with other buddies.


BLOCK_SOMETHING

public static final CapabilityBlock BLOCK_SOMETHING
A capability block whose purpose is unknown at the time of this writing.


BLOCK_SHORTCAPS

public static final CapabilityBlock BLOCK_SHORTCAPS
A capability block indicating that the client is capable of parsing "short capability blocks." See ShortCapabilityBlock as well as FullUserInfo.getShortCapabilityBlocks() for more information on short capability blocks.


BLOCK_ENCRYPTION

public static final CapabilityBlock BLOCK_ENCRYPTION
A capability block indicating that the user is available for Secure IM and may be available for other secure communcations (secure chat rooms, file transfer, and so on). This capability block causes a padlock icon to be displayed next to one's screenname in the official AIM clients.

Constructor Detail

CapabilityBlock

public CapabilityBlock(ByteBlock block)
                throws java.lang.IllegalArgumentException
Creates a new capability block from the given sixteen-byte block.

Parameters:
block - the sixteen-byte block that comprises the capability block to be created
Throws:
java.lang.IllegalArgumentException - if the given block does not contain exactly sixteen bytes
Method Detail

convertToBytes

public static byte[] convertToBytes(CapabilityBlock[] capabilities)
Converts the given list of capabilities to a block of bytes, suitable for sending in a InfoData structure.

Parameters:
capabilities - the list of capabilities to convert to a block of binary data
Returns:
a block of binary data containing the binary representations of the given capabilities

getCapabilityBlocks

public static CapabilityBlock[] getCapabilityBlocks(ByteBlock block)
Extracts a list of capability blocks from the given data block.

Parameters:
block - the data block containing zero or more capability blocks
Returns:
a list of capability blocks contained in the given data block

getBlock

public final ByteBlock getBlock()
Returns the sixteen-byte block that identifies this capability block.

Returns:
this capability's byte block

getWritableLength

public final 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

equals

public boolean equals(java.lang.Object other)
Returns true if this and the given CapabilityBlock represent the same capability. That is, returns whether or not this and the given capability block have the same underlying sixteen-byte data block.

Parameters:
other - the CapabilityBlock to compare to
Returns:
whether this capability block represents the same capability as the given block

hashCode

public int hashCode()

toString

public java.lang.String toString()