org.walluck.oscar.handlers
Class SSIHandler

java.lang.Object
  extended byorg.walluck.oscar.handlers.SNACHandler
      extended byorg.walluck.oscar.handlers.SSIHandler

public class SSIHandler
extends SNACHandler

Family 0x0013 - Server-Side/Stored Information.

Relatively new facility that allows storing of certain types of information, such as a users buddy list, permit/deny list, and permit/deny preferences, to be stored on the server, so that they can be accessed from any client.

We keep 2 copies of SSI data:

  1. An exact copy of what is stored on the AIM servers.
  2. A local copy that we make changes to, and then send diffs between this and the exact copy to keep them in sync.

All of the itemList functions near the top just modify the list that is given to them (e.g. they don't send SNAC's).

The SNAC sending and receiving functions are lower down in the file, and they're simpler. They are in the order of the subtypes they deal with, starting with the request rights function (subtype 0x0002), then parse rights (subtype 0x0003), then -- well, you get the idea.

types:

0x0000 - buddy entry
0x0001 - group entry
0x0002 - permit entry
0x0003 - deny entry
0x0004 - permit/deny settings entry
0x0005 - presence setting entry
0x0009 - ICQTIC settings 0x000e - ignore entry (ICQ only)
0x0013 - import time entry (ICQ only)

TLV's (with associated types):

TLV(0x0066) - awaiting authorization (0x0000)
TLV(0x00c8) - group or buddy id's (0x0001)
TLV(0x00c9) - visibility flags (0x0005)
TLV(0x00ca) - privacy flags for allow users (0x0004)
TLV(0x00cb) - privacy flags for user class (0x0004)
TLV(0x00cc) - privacy flags for allow others (0x0004)
TLV(0x00cd) - unknown ICQTIC values (ICQ only) (0x0009)
TLV(0x00d4) - list timestamp (ICQ only?) (0x0013)
TLV(0x0131) - user alias (ICQ only) (0x0000)
TLV(0x013a) - SMS number (ICQ only) (0x0000)
TLV(0x013c) - buddy comment field (0x0000)
TLV(0x013b) - unknown
TLV(0x013d) - buddy alert type (0x0000)
TLV(0x013e) - buddy alert sound (0x0000)

Since:
1.0
Version:
1.0
Author:
David Walluck
See Also:
SNACHandler

Constructor Summary
SSIHandler()
          Family 0x0013.
 
Method Summary
 void addBuddy(AIMSession sess, java.lang.String name, java.lang.String group, java.lang.String alias, java.lang.String comment, java.lang.String smsnum, boolean needauth)
          Add a buddy to the list.
 void addDeny(AIMSession sess, java.lang.String name)
          Add a deny buddy to the list.
 void addModDel(AIMSession sess)
          Subtype 0x0008/0x0009/0x000a - SSI Add/Mod/Del Item(s).
 void addPermit(AIMSession sess, java.lang.String name)
          Add a permit buddy to the list.
 void aliasBuddy(AIMSession sess, java.lang.String gn, java.lang.String sn, java.lang.String alias)
          Change the alias stored on the server for a given buddy.
 void cleanList(AIMSession sess)
          This "cleans" the SSI list.
 void debugPrintLists(AIMSession sess)
          Debug method to print the official and local lists.
 void delBuddy(AIMSession sess, java.lang.String name, java.lang.String group)
          Deletes a buddy from the list.
 void delDeny(AIMSession sess, java.lang.String name)
          Deletes a deny buddy from the list.
 void deleteList(AIMSession sess)
          Delete all SSI data.
 void delPermit(AIMSession sess, java.lang.String name)
          Deletes a permit buddy from the list.
 void enable(AIMSession sess)
          Subtype 0x0007 - SSI Activate Data.
 void freeList(AIMSession sess)
          Free all SSI data.
 java.lang.String getAlias(java.util.List list, java.lang.String gn, java.lang.String sn)
          Locally find the alias of the given buddy.
 java.lang.String getBuddyComment(java.util.List list, java.lang.String gn, java.lang.String sn)
          Locally find the buddy comment of the given buddy.
 byte getPermdeny(java.util.List list)
          Locally find the permit/deny setting item, and return the setting.
 int getPresence(java.util.List list)
          Locally find the presence flag item, and return the setting.
 void handleSNAC(AIMSession sess, SNACHandler handler, AIMFrame frame, SNAC snac, AIMInputStream buffer)
          Handles incoming SNAC's.
 SSIItem itemListAdd(java.util.List list, java.lang.String name, int gid, int bid, int type, TLVChain data)
          Locally add a new item to the given item list.
 int itemListCmp(SSIItem cur1, SSIItem cur2)
          Compare two items to see if they have the same data.
 int itemListDel(java.util.List list, SSIItem del)
          Locally delete an item from the given item list.
 SSIItem itemListExists(java.util.List list, java.lang.String sn)
          Check if the given buddy exists in any group in the buddy list.
 SSIItem itemListFind(java.util.List list, int gid, int bid)
          Locally find an item given a group ID and a buddy ID.
 SSIItem itemListFindItem(java.util.List list, java.lang.String gn, java.lang.String sn, int type)
          Locally find an item given a group name, screen name, and type.
 java.lang.String itemListFindParentName(java.util.List list, java.lang.String sn)
          Locally find the parent item of the given buddy name.
 boolean itemListValid(java.util.List list, SSIItem item)
          Tests whether the item is actually present in the SSI list.
 void modBegin(AIMSession sess)
          Subtype 0x0011 - SSI Begin Data Modification.
 void modEnd(AIMSession sess)
          Subtype 0x0012 - SSI End Data Modification.
 void moveBuddy(AIMSession sess, java.lang.String oldgn, java.lang.String newgn, java.lang.String sn)
          Move a buddy from one group to another group.
 void renameGroup(AIMSession sess, java.lang.String oldgn, java.lang.String newgn)
          Rename a group.
 void reqData(AIMSession sess)
          Subtype 0x0004 - Request SSI Data when you don't have a timestamp and revision number.
 void reqIfChanged(AIMSession sess, long timestamp, short numitems)
          Subtype 0x0005 - Request SSI Data when you have a timestamp and revision number.
 void reqRights(AIMSession sess)
          Subtype 0x0002 - Request SSI Rights.
 void sendAuth(AIMSession sess, java.lang.String sn, java.lang.String msg)
          Subtype 0x0014 - Grant authorization Authorizes a contact so they can add you to their contact list.
 void sendAuthReply(AIMSession sess, java.lang.String sn, byte reply, java.lang.String msg)
          Subtype 0x001a - Send authorization reply Sends a reply to a request for authorization.
 void sendAuthRequest(AIMSession sess, java.lang.String sn, java.lang.String msg)
          Subtype 0x0018 - Send authorization request Sends a request for authorization to the given contact.
 void setIcon(AIMSession sess, byte[] iconsum)
          Set buddy icon information
 void setPermDeny(AIMSession sess, byte permdeny, int vismask)
          Store your permit/deny setting on the server, and start using it.
 void setPresence(AIMSession sess, int presence)
          Stores your setting for whether you should show up as idle or not.
 void sync(AIMSession sess)
          If there are changes, then create temporary items and call addModDel.
 boolean waitingForAuth(java.util.List list, java.lang.String gn, java.lang.String sn)
          Locally find if you are waiting for authorization for a buddy.
 
Methods inherited from class org.walluck.oscar.handlers.SNACHandler
getFamily, getVersion, setFamily, setVersion
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SSIHandler

public SSIHandler()
Family 0x0013.

Method Detail

debugPrintLists

public void debugPrintLists(AIMSession sess)
Debug method to print the official and local lists.

Parameters:
sess - the oscar session

itemListAdd

public SSIItem itemListAdd(java.util.List list,
                           java.lang.String name,
                           int gid,
                           int bid,
                           int type,
                           TLVChain data)
Locally add a new item to the given item list.

Parameters:
list - the current list of items
name - string of the name of the new item, or null if the item should have no name
gid - The group ID# you want the new item to have, or -1 if we should pick something
bid - The buddy ID# you want the new item to have, or -1 if we should pick something
type - The type of the item, 0x0000 for a contact, 0x0001 for a group, etc.
data - The additional data for the new item
Returns:
the newly created item

itemListDel

public int itemListDel(java.util.List list,
                       SSIItem del)
Locally delete an item from the given item list.

Parameters:
list - the current list of items
del - the item you want to remove from the list
Returns:
0 if no errors, otherwise return the error number

itemListCmp

public int itemListCmp(SSIItem cur1,
                       SSIItem cur2)
                throws java.io.IOException
Compare two items to see if they have the same data.

Parameters:
cur1 - the first item
cur2 - the second item
Returns:
0 if no differences, or a number if there are differences
Throws:
java.io.IOException - if an error occurs

itemListValid

public boolean itemListValid(java.util.List list,
                             SSIItem item)
Tests whether the item is actually present in the SSI list.

Parameters:
list - the list
item - the item
Returns:
true if item is valid, false otherwise

itemListFind

public SSIItem itemListFind(java.util.List list,
                            int gid,
                            int bid)
Locally find an item given a group ID and a buddy ID.

Parameters:
list - the current list of items
gid - the group ID of the desired item
bid - the buddy ID of the desired item
Returns:
the item if found or else null

itemListFindItem

public SSIItem itemListFindItem(java.util.List list,
                                java.lang.String gn,
                                java.lang.String sn,
                                int type)
Locally find an item given a group name, screen name, and type. If group name and screen name are null, then just return the first item of the given type.

Parameters:
list - the current list of items
gn - the group name of the desired item
sn - the buddy name of the desired item
type - the type of the desired item
Returns:
the new item if found or else null

itemListExists

public SSIItem itemListExists(java.util.List list,
                              java.lang.String sn)
Check if the given buddy exists in any group in the buddy list.

Parameters:
list - the current list of items
sn - the group name of the desired item
Returns:
a pointer to the name of the item if found, else return null

itemListFindParentName

public java.lang.String itemListFindParentName(java.util.List list,
                                               java.lang.String sn)
Locally find the parent item of the given buddy name.

Parameters:
list - the current list of items
sn - the buddy name of the desired item
Returns:
the name of the item if found or else null

getPermdeny

public byte getPermdeny(java.util.List list)
                 throws java.io.IOException
Locally find the permit/deny setting item, and return the setting.

Parameters:
list - the current list of items
Returns:
the current permit/deny setting or 0 if no setting was found
Throws:
java.io.IOException - if an error occurs

getPresence

public int getPresence(java.util.List list)
                throws java.io.IOException
Locally find the presence flag item, and return the setting. The returned setting is a bitmask of the user flags that you are visible to. See the AIM_FLAG constants in AIMConstants.

Parameters:
list - the current list of items
Returns:
the current visbility mask or -1 if no visibity mask is found
Throws:
java.io.IOException - if an error occurs
See Also:
AIMConstants

getAlias

public java.lang.String getAlias(java.util.List list,
                                 java.lang.String gn,
                                 java.lang.String sn)
                          throws java.io.IOException
Locally find the alias of the given buddy.

Parameters:
list - the current list of items
gn - the group of the buddy.
sn - the name of the buddy.
Returns:
the string that is the buddies alias, or null if the buddy has no alias
Throws:
java.io.IOException - if an error occurs

getBuddyComment

public java.lang.String getBuddyComment(java.util.List list,
                                        java.lang.String gn,
                                        java.lang.String sn)
                                 throws java.io.IOException
Locally find the buddy comment of the given buddy.

Parameters:
list - the current list of items
gn - the group of the buddy.
sn - the name of the buddy.
Returns:
the string that is the buddy's comment, or null if the buddy has no comment
Throws:
java.io.IOException - if an error occurs

waitingForAuth

public boolean waitingForAuth(java.util.List list,
                              java.lang.String gn,
                              java.lang.String sn)
                       throws java.io.IOException
Locally find if you are waiting for authorization for a buddy.

Parameters:
list - the current list of items
gn - the group of the buddy
sn - the name of the buddy
Returns:
the terminated string that is the buddy's alias, or null if the buddy has no alias.
Throws:
java.io.IOException - if an error occurs

sync

public void sync(AIMSession sess)
          throws java.io.IOException
If there are changes, then create temporary items and call addModDel.

Parameters:
sess - the oscar session
Throws:
java.io.IOException - if an error occurs

freeList

public void freeList(AIMSession sess)
Free all SSI data. This doesn't remove it from the server, that's different.

Parameters:
sess - the oscar session

deleteList

public void deleteList(AIMSession sess)
                throws java.io.IOException
Delete all SSI data.

Parameters:
sess - the oscar session
Throws:
java.io.IOException - if an error occurs

cleanList

public void cleanList(AIMSession sess)
               throws java.io.IOException
This "cleans" the SSI list. It does the following:
  1. Makes sure all buddies, permits, and denies have names
  2. Makes sure that all buddies are in a group that exist
  3. Deletes any empty groups

Parameters:
sess - the oscar session
Throws:
java.io.IOException - if an error occurs

addBuddy

public void addBuddy(AIMSession sess,
                     java.lang.String name,
                     java.lang.String group,
                     java.lang.String alias,
                     java.lang.String comment,
                     java.lang.String smsnum,
                     boolean needauth)
              throws java.io.IOException
Add a buddy to the list.

Parameters:
sess - the oscar session
name - the name of the item
group - the group of the item
alias - the alias/nickname of the item, or null
comment - the buddy comment for the item, or null
smsnum - the locally assigned SMS number, or null
needauth - a boolean value
Throws:
java.io.IOException - if an error occurs

addPermit

public void addPermit(AIMSession sess,
                      java.lang.String name)
               throws java.io.IOException
Add a permit buddy to the list.

Parameters:
sess - the oscar session
name - the name of the item
Throws:
java.io.IOException - if an error occurs

addDeny

public void addDeny(AIMSession sess,
                    java.lang.String name)
             throws java.io.IOException
Add a deny buddy to the list.

Parameters:
sess - the oscar session
name - the name of the item
Throws:
java.io.IOException - if an error occurs

delBuddy

public void delBuddy(AIMSession sess,
                     java.lang.String name,
                     java.lang.String group)
              throws java.io.IOException
Deletes a buddy from the list.

Parameters:
sess - the oscar session
name - the name of the item, or null
group - the group of the item, or null
Throws:
java.io.IOException - if an error occurs

delPermit

public void delPermit(AIMSession sess,
                      java.lang.String name)
               throws java.io.IOException
Deletes a permit buddy from the list.

Parameters:
sess - the oscar session
name - the name of the item, or null
Throws:
java.io.IOException - if an error occurs

delDeny

public void delDeny(AIMSession sess,
                    java.lang.String name)
             throws java.io.IOException
Deletes a deny buddy from the list.

Parameters:
sess - the oscar session
name - the name of the item, or null
Throws:
java.io.IOException - if an error occurs

moveBuddy

public void moveBuddy(AIMSession sess,
                      java.lang.String oldgn,
                      java.lang.String newgn,
                      java.lang.String sn)
               throws java.io.IOException
Move a buddy from one group to another group. This basically just deletes the buddy and re-adds it.

Parameters:
sess - the oscar session
oldgn - the group that the buddy is currently in
newgn - the group that the buddy should be moved in to
sn - the name of the buddy to be moved
Throws:
java.io.IOException - if an error occurs

aliasBuddy

public void aliasBuddy(AIMSession sess,
                       java.lang.String gn,
                       java.lang.String sn,
                       java.lang.String alias)
                throws java.io.IOException
Change the alias stored on the server for a given buddy.

Parameters:
sess - the oscar session
gn - the group that the buddy is currently in
sn - the screen name of the buddy
alias - the new alias for the buddy
Throws:
java.io.IOException - if an error occurs

renameGroup

public void renameGroup(AIMSession sess,
                        java.lang.String oldgn,
                        java.lang.String newgn)
                 throws java.io.IOException
Rename a group.

Parameters:
sess - the oscar session
oldgn - the old group name
newgn - the new group name
Throws:
java.io.IOException - if an error occurs

setPermDeny

public void setPermDeny(AIMSession sess,
                        byte permdeny,
                        int vismask)
                 throws java.io.IOException
Store your permit/deny setting on the server, and start using it.

Parameters:
sess - The oscar session.
permdeny - Your permit/deny setting. Can be one of the following:
  1. Allow all users
  2. Block all users
  3. Allow only the users below
  4. Block only the users below
  5. Allow only users on my buddy list
vismask - A bitmask of the class of users to whom you want to be visible. See the AIM_FLAG_BLEH in AIMConstants
Throws:
java.io.IOException - if an error occurs

setIcon

public void setIcon(AIMSession sess,
                    byte[] iconsum)
             throws java.io.IOException
Set buddy icon information

Parameters:
sess - the oscar session
iconsum - a byte[] value
Throws:
java.io.IOException - if an error occurs

setPresence

public void setPresence(AIMSession sess,
                        int presence)
                 throws java.io.IOException
Stores your setting for whether you should show up as idle or not.

Parameters:
sess - The oscar session.
presence - I think it's a bitmask, but I only know what one of the bits is:
0x00000400 - Allow others to see your idle time
Throws:
java.io.IOException - if an error occurs

reqRights

public void reqRights(AIMSession sess)
               throws java.io.IOException
Subtype 0x0002 - Request SSI Rights.

Parameters:
sess - an AIMSession value
Throws:
java.io.IOException - if an error occurs

reqData

public void reqData(AIMSession sess)
             throws java.io.IOException
Subtype 0x0004 - Request SSI Data when you don't have a timestamp and revision number.

Parameters:
sess - the oscar session
Throws:
java.io.IOException - if an error occurs

reqIfChanged

public void reqIfChanged(AIMSession sess,
                         long timestamp,
                         short numitems)
                  throws java.io.IOException
Subtype 0x0005 - Request SSI Data when you have a timestamp and revision number. The data will only be sent if it is newer than the posted local timestamp and revision. Note that the client should never increment the revision, only the server.

Parameters:
sess - the oscar session
timestamp - the timestamp
numitems - the numitems array
Throws:
java.io.IOException - if an error occurs

enable

public void enable(AIMSession sess)
            throws java.io.IOException
Subtype 0x0007 - SSI Activate Data. Should be sent after receiving 13/6 or 13/f to tell the server you are ready to begin using the list. It will promptly give you the presence information for everyone in your list and put your permit/deny settings into effect.

Parameters:
sess - an AIMSession value
Throws:
java.io.IOException - if an error occurs

addModDel

public void addModDel(AIMSession sess)
               throws java.io.IOException
Subtype 0x0008/0x0009/0x000a - SSI Add/Mod/Del Item(s). Sends the SNAC to add, modify, or delete an item from the server-stored information. These 3 SNACs all have an identical structure. The only difference is the subtype that is set for the SNAC.

Parameters:
sess - an AIMSession value
Throws:
java.io.IOException - if an error occurs

modBegin

public void modBegin(AIMSession sess)
              throws java.io.IOException
Subtype 0x0011 - SSI Begin Data Modification. Tells the server you're going to start modifying data.

Parameters:
sess - the oscar session
Throws:
java.io.IOException - if an error occurs

modEnd

public void modEnd(AIMSession sess)
            throws java.io.IOException
Subtype 0x0012 - SSI End Data Modification. Tells the server you're finished modifying data.

Parameters:
sess - the oscar session
Throws:
java.io.IOException - if an error occurs

sendAuth

public void sendAuth(AIMSession sess,
                     java.lang.String sn,
                     java.lang.String msg)
              throws java.io.IOException
Subtype 0x0014 - Grant authorization Authorizes a contact so they can add you to their contact list.

Parameters:
sess - the oscar session
sn - the screenname
msg - the message
Throws:
java.io.IOException - if an error occurs

sendAuthRequest

public void sendAuthRequest(AIMSession sess,
                            java.lang.String sn,
                            java.lang.String msg)
                     throws java.io.IOException
Subtype 0x0018 - Send authorization request Sends a request for authorization to the given contact. The request will either be granted, denied, or dropped.

Parameters:
sess - the oscar session
sn - the screenname
msg - the message
Throws:
java.io.IOException - if an error occurs

sendAuthReply

public void sendAuthReply(AIMSession sess,
                          java.lang.String sn,
                          byte reply,
                          java.lang.String msg)
                   throws java.io.IOException
Subtype 0x001a - Send authorization reply Sends a reply to a request for authorization. The reply can either grant authorization or deny authorization. if reply = 0x00 then deny if reply = 0x01 then grant

Parameters:
sess - the oscar session
sn - the screenname
reply - the reply
msg - the message
Throws:
java.io.IOException - if an error occurs

handleSNAC

public void handleSNAC(AIMSession sess,
                       SNACHandler handler,
                       AIMFrame frame,
                       SNAC snac,
                       AIMInputStream buffer)
                throws java.io.IOException
Handles incoming SNAC's.

Specified by:
handleSNAC in class SNACHandler
Parameters:
sess - the oscar session
handler - the handler
frame - the incoming frame
snac - the incoming SNAC
buffer - the incoming buffer
Throws:
java.io.IOException - if an error occurs