net.kano.joscar.ssiitem
Class BuddyItem

java.lang.Object
  extended byAbstractItemObj
      extended byBuddyItem
All Implemented Interfaces:
SsiItemObj

public class BuddyItem
extends AbstractItemObj

An SSI item object representing a buddy on the user's buddy list. A buddy item contains a set of buddy alert flags (for the different types of alerts), an alert sound filename, a buddy comment, and (though WinAIM does not yet support it) an "alias" or "display name" for the buddy.

Note that this class is only used to store data and that changes to this object are not reflected on the server without sending the changes to the server with a ModifyItemsCmd.


Field Summary
static int MASK_ACTION_PLAY_SOUND
          An alert action flag indicating that a sound should be played when the buddy alert is activated.
static int MASK_ACTION_POPUP
          An alert action flag indicating that a window should be popped up when the buddy alert is activated.
static int MASK_WHEN_ONLINE
          An alert flag indicating that the buddy's alert should be activated when he or she signs on.
static int MASK_WHEN_UNAWAY
          An alert flag indicating that the buddy's alert should be activated when he or she comes back from being away.
static int MASK_WHEN_UNIDLE
          An alert flag indicating that the buddy's alert should be activated when he or she comes back from being idle.
 
Constructor Summary
BuddyItem(BuddyItem other)
          Creates a buddy item object with the same properties as the given object.
BuddyItem(SsiItem item)
          Creates a new buddy item object from the given SSI item.
BuddyItem(java.lang.String sn, int groupid, int id)
          Creates a new buddy item with the given screenname, group ID, and buddy ID.
BuddyItem(java.lang.String sn, int groupid, int id, java.lang.String alias, java.lang.String comment, int alertWhenMask, int alertActionMask, java.lang.String alertSound)
          Creates a new buddy item object with the given properties.
BuddyItem(java.lang.String sn, int groupid, int id, java.lang.String alias, java.lang.String comment, int alertWhenMask, int alertActionMask, java.lang.String alertSound, TlvChain extraTlvs)
          Creates a new buddy item object with the given properties.
 
Method Summary
 int getAlertActionMask()
          Returns a bit mask describing what should happen when a buddy alert is activated for this buddy.
 java.lang.String getAlertSound()
          Returns the name of a sound file that should be played when this buddy's alert is activated.
 int getAlertWhenMask()
          Returns a bit mask describing when a buddy alert for this user should be activated.
 java.lang.String getAlias()
          Returns this buddy's "alias" or "display name."
 java.lang.String getBuddyComment()
          Returns this buddy's "buddy comment."
 int getGroupId()
          Returns the ID of the group in which this buddy resides.
 int getId()
          Returns the ID of this buddy in its parent group.
 java.lang.String getScreenname()
          Returns this buddy's screenname.
 void setAlertActionMask(int alertActionMask)
          Sets this buddy's "alert action mask."
 void setAlertSound(java.lang.String alertSound)
          Sets the "alert sound" filename for this buddy.
 void setAlertWhenMask(int alertWhenMask)
          Sets this buddy's "alert criteria mask."
 void setAlias(java.lang.String alias)
          Sets this buddy's "alias" or "display name."
 void setComment(java.lang.String comment)
          Sets this buddy's "buddy comment."
 SsiItem toSsiItem()
          Returns an SsiItem that represents this item object.
 java.lang.String toString()
           
 
Methods inherited from class AbstractItemObj
addExtraTlvs, copyExtraTlvs, generateItem, generateSsiItems, getExtraTlvs
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MASK_ACTION_POPUP

public static final int MASK_ACTION_POPUP
An alert action flag indicating that a window should be popped up when the buddy alert is activated.

See Also:
Constant Field Values

MASK_ACTION_PLAY_SOUND

public static final int MASK_ACTION_PLAY_SOUND
An alert action flag indicating that a sound should be played when the buddy alert is activated. The sound file is specified in getAlertSound.

See Also:
Constant Field Values

MASK_WHEN_ONLINE

public static final int MASK_WHEN_ONLINE
An alert flag indicating that the buddy's alert should be activated when he or she signs on.

See Also:
Constant Field Values

MASK_WHEN_UNIDLE

public static final int MASK_WHEN_UNIDLE
An alert flag indicating that the buddy's alert should be activated when he or she comes back from being idle.

See Also:
Constant Field Values

MASK_WHEN_UNAWAY

public static final int MASK_WHEN_UNAWAY
An alert flag indicating that the buddy's alert should be activated when he or she comes back from being away.

See Also:
Constant Field Values
Constructor Detail

BuddyItem

public BuddyItem(SsiItem item)
Creates a new buddy item object from the given SSI item.

Parameters:
item - a "buddy" (type SsiItem.TYPE_BUDDY) SSI item

BuddyItem

public BuddyItem(BuddyItem other)
Creates a buddy item object with the same properties as the given object.

Parameters:
other - a buddy item object to copy

BuddyItem

public BuddyItem(java.lang.String sn,
                 int groupid,
                 int id)
Creates a new buddy item with the given screenname, group ID, and buddy ID. All other fields are set to null or 0 depending on the field's type.

Parameters:
sn - the buddy's screenname
groupid - the ID of the group in which this buddy resides
id - the buddy's buddy ID

BuddyItem

public BuddyItem(java.lang.String sn,
                 int groupid,
                 int id,
                 java.lang.String alias,
                 java.lang.String comment,
                 int alertWhenMask,
                 int alertActionMask,
                 java.lang.String alertSound)
Creates a new buddy item object with the given properties. All fields other than sn, groupid, and id can be either 0 or null (depending on type) to indicate that the given field should not be sent.

Parameters:
sn - the buddy's screenname
groupid - the ID of the group in which this buddy resides
id - the buddy's buddy ID
alias - an "alias" or "display name" for this buddy (only supported by joscar and gaim)
comment - a "buddy comment" for this buddy
alertWhenMask - a set of bit flags indicating when a buddy alert should be activated (see the MASK_WHEN_* constants)
alertActionMask - a set of bit flags indicating what should happen when a buddy alert is activated (see the MASK_ACTION_* constants)
alertSound - the name of a sound file to play when an alert is activated (normally stored without a full path or an extension, like "moo")

BuddyItem

public BuddyItem(java.lang.String sn,
                 int groupid,
                 int id,
                 java.lang.String alias,
                 java.lang.String comment,
                 int alertWhenMask,
                 int alertActionMask,
                 java.lang.String alertSound,
                 TlvChain extraTlvs)
Creates a new buddy item object with the given properties. All fields other than sn, groupid, and id can be either 0 or null (depending on type) to indicate that the given field should not be sent.

Parameters:
sn - the buddy's screenname
groupid - the ID of the group in which this buddy resides
id - the buddy's buddy ID
alias - an "alias" or "display name" for this buddy (only supported by joscar and gaim)
comment - a "buddy comment" for this buddy
alertWhenMask - a set of bit flags indicating when a buddy alert should be activated (see the MASK_WHEN_* constants)
alertActionMask - a set of bit flags indicating what should happen when a buddy alert is activated (see the MASK_ACTION_* constants)
alertSound - the name of a sound file to play when an alert is activated (normally stored without a full path or an extension, like "moo")
extraTlvs - a set of extra TLV's to store in this item
Method Detail

getScreenname

public final java.lang.String getScreenname()
Returns this buddy's screenname.

Returns:
this buddy's screenname

getGroupId

public final int getGroupId()
Returns the ID of the group in which this buddy resides.

Returns:
the ID of this buddy's parent group

getId

public final int getId()
Returns the ID of this buddy in its parent group.

Returns:
this buddy's "buddy ID"

getAlias

public final java.lang.String getAlias()
Returns this buddy's "alias" or "display name." Currently this feature is only supported by joscar and gaim, but it's conceivable that WinAIM will begin supporting it in the future.

Returns:
this buddy's "alias" or "display name," or null if this buddy has no alias

getBuddyComment

public final java.lang.String getBuddyComment()
Returns this buddy's "buddy comment." A buddy comment is a string of text normally edited by the user to store some brief information about the buddy. WinAIM puts a limit of 84 characters on this value, but there is no hard (server-side) limit. Note that this value is stored as ASCII text.

Returns:
this buddy's "buddy comment," or null if this buddy has no buddy comment

getAlertActionMask

public final int getAlertActionMask()
Returns a bit mask describing what should happen when a buddy alert is activated for this buddy. Normally a combination of any of MASK_ACTION_POPUP and MASK_ACTION_PLAY_SOUND. One can test for a given value using code resembling the following:
if ((buddyItem.getAlertActionMask() & BuddyItem.MASK_ACTION_POPUP) != 0) {
    // popup alert box
}
 

Returns:
a set of bit flags describing what should happen when this buddy's buddy alert is activated

getAlertWhenMask

public final int getAlertWhenMask()
Returns a bit mask describing when a buddy alert for this user should be activated. Normally a combination of any of MASK_WHEN_ONLINE, MASK_WHEN_UNAWAY, and MASK_WHEN_UNIDLE. One can test for a given value using code resembling the following:
if ((buddyItem.getAlertWhenMask() & BuddyItem.MASK_WHEN_ONLINE) != 0) {
    System.out.println("An alert should be triggered when "
            + buddyItem.getScreenname() + " signs on!");
}
 

Returns:
a set of bit flags describing when a buddy alert for this user should be activated

getAlertSound

public final java.lang.String getAlertSound()
Returns the name of a sound file that should be played when this buddy's alert is activated. The sound should only be played if this buddy's alert action mask contains MASK_ACTION_PLAY_SOUND. The filename is normally stored without a full path or file extension, like "moo" to represent C:\Program Files\AIM95\Sounds\moo.wav.

Returns:
the name of a sound file that should be played when this buddy's alert is activated, or null if none is stored for this buddy
See Also:
getAlertActionMask()

setAlias

public final void setAlias(java.lang.String alias)
Sets this buddy's "alias" or "display name."

Parameters:
alias - this buddy's new "alias" or "display name," or null to erase this buddy's alias

setComment

public final void setComment(java.lang.String comment)
Sets this buddy's "buddy comment."

Parameters:
comment - this buddy's new "buddy comment," or null to erase this buddy's comment

setAlertActionMask

public final void setAlertActionMask(int alertActionMask)
Sets this buddy's "alert action mask." Normally a combination of any of MASK_ACTION_POPUP and MASK_ACTION_PLAY_SOUND.

Parameters:
alertActionMask - a new "alert action mask" for this buddy

setAlertWhenMask

public final void setAlertWhenMask(int alertWhenMask)
Sets this buddy's "alert criteria mask." Normally a combination of any of MASK_WHEN_ONLINE, MASK_WHEN_UNAWAY, and MASK_WHEN_UNIDLE.

Parameters:
alertWhenMask - a new "alert criteria mask" for this buddy

setAlertSound

public final void setAlertSound(java.lang.String alertSound)
Sets the "alert sound" filename for this buddy. This is normally stored without full path or file extension, like "moo" to represent C:\Program Files\AIM95\Sounds\moo.wav.

Parameters:
alertSound - the buddy's "alert sound filename," or null to erase any alert sound file currently stored in this item

toSsiItem

public SsiItem toSsiItem()
Description copied from interface: SsiItemObj
Returns an SsiItem that represents this item object.

Returns:
an SsiItem that represents this item object

toString

public java.lang.String toString()