File: supplement.txt

The following is a supplement to the manual because it seems massive.

Below you will find a list of commands that you can create handlers to, and what fields the $info array returned
by msg_parse will return.

For this document, assume that 
$info=msg_parse(msg_type($message));
where $message is what is coming into your event handler.
and
$aim is an instnace of the class Aim.

To set an even handler, you need to declare a function thats heading looks like this:
function <functionname>($message)

where <functionname> is the name of your function.

Once you have the function declared(not in the class), you need to associate it with an incoming message. To do
this, use the following method:
$aim->registerHandler($command,$function);

Where $command is one of the commands listed below (should be a string), and $function is the name of the
function you defined earlier(also a string).

The following is a list of commands, when you might reveive them, and what fields $info will have


SIGN_ON
This command is sent to the client telling it that the authentication has been accepted, and it should
continue with sign on. 

$info['version'] contains the version of TOC we are using

CONFIG2
This message is received telling the client who is on their buddy list. This is currently parsed internally.
msg_parse does not support this command, but the information that is received by it can be retreived 
using the methods
$aim->getBuddies();
$aim->getBlocked();
$aim->getPermit();


ERROR
This is received when there has been an error. 
$info['errorcode'] contains the code of the error received.
$info['args'] This conatains any arguments, sometimes this is additional error information. This is often an empty string

NICK
This message is received at signon. This will give the user their un-normalized nickname (has spaces, caps,and other formatting)
$info['nickname'] is the formatted screen name. This is what will be displayed to other users

IM_IN2
This is probably the most important message that you will deal with. This is received every time that you get
an IM.
$info['from'] is the screen name of who the message is from (if you plan on using it, you need to run it through $aim->normalize)
$info['auto'] This will either equal T or F. If it is T, then this message was sent as like an away message, or something of the sort
$info['message'] This is the actual message sent by the user. It does contain HTML

UPDATE_BUDDY2
This message is received to inform you of status changes of the people on your buddy list
$info['sn'] Is the screen name this message is referring to
$info['online'] Either 'T' or 'F'. If it is 'T', then the user is online, otherwise it is 'F'.
$info['warnlevel'] This is a percentage representing the users warning level. It does have a percent sign attached
$info['signon'] This is a UNIX timestamp representing when the user signed on
$info['idle'] This is the number of minuted a user has been idle
$info['uc'] This is a 3 character string representing the user class. No more information is currently available on this.


EVILED
This message comes in when you are warned by another user
$info['warnlevel'] is your new warning level (This is the percentage, but does not have a '%' at the end)
$info['from'] is the screen name that sent you the warning. If it is '0' then you were warned anonomously

CHAT_JOIN
This message is received when you join a chatroom
$info['chatid'] is the ID number of the chat. This is needed when sending chat messages
$info['chatname'] is the actual name of the chat. This is set by the user that created it

CHAT_IN
This is the message you receive when you get a message from a chatroom.
$info['chatid'] is the ID of the chat the message was received in. This will be one of the id's from CHAT_JOIN
$info['user'] is the screen name of the person who sent the message
$info['whisper'] is either 'T' or 'F'. If it is 'T' then this is a whisper. Otherwise it isn't... I have no clue what this means
$info['message'] This is the actual message received. It may contain HTML, though I'm not sure on that

CHAT_UPDATE_BUDDY
This is sent when a user enters or exits a chat
$info['chatid'] is the id of the chat that the user us being updated in. This will be one of the id's from CHAT_JOIN
$info['inside'] is either 'T' or 'F'. If it is 'T' it means the user is in the chatroom. Otherwise he is not
$info['userlist'] This is a list of users in the chat seperated by a ':'


CHAT_INVITE
This is received when you have been invited to a chat.
$info['chatname'] is the name of the chatroom
$info['chatid'] is the id of the chatroom you are being invited to
$info['from'] is the is the screen name of the user who invited you
$info['message'] is the message attached with the invitation. This could possibly contain HTML (not sure)

CHAT_LEFT
This is sent when you leave a chatroom
$info['chatid'] is the ID of the chatroom you just left

GOTO_URL
This is sent when the server wants the client to visit a URL. I beleive this is associated with getting a users profile
$info['windowname'] is the suggested name of the new window
$info['url'] is the URL to visit

DIR_STATUS
I beleive this command has been discontinued. 
There is no $info for this command

ADMIN_NICK_STATUS
Received when you change the formatting of your nickname
$info['returncode'] is always 0 on success
$info['opt'] are optional arguments

ADMIN_PASSWD_STATUS
Receives when you change your password
$info['returncode'] is always 0 on success
$info['opt'] are optional arguments

PAUSE
This is sent to the client when you need to pause. ANything sent to the server after a PAUSE command will
be ignored. Things will be accepted when you receive a SIGN_ON message.
There is no $info for this command

RVOUS_PROPOSE
This command is beleived to be obsolete.
There is no $info for this command

other
This isn't really a command. This is a string you can pass to $aim->registerHandler() to create a function
for any commands that aren't on this list (and it is possible I have missed some). 
There is no $info for this command



Now, using the above information, you should be able to register a handler for every event that AIM trows your way.

So now lets have a little example on how this should work. Below is a small php script that implements a message
handler.

<?php
include "aimclassw.php"; //Include the class

$aim=new Aim("screen name","password",4); //Create an instance of the Aim class

//You should register all handlers before you sign on. This prevents anything weird from happening.
$aim->registerHandler("IM_IN2","IMinHand");  //Register the function IminHand as the handler for IM_IN2

//Now sign on
$aim->signon();
$aim->update_profile("This is my profile!<br>",true); //Give us a profile

while(1) //We want this to go forever
{
   $aim->reveive(); //This handles pretty much everything
   $aim->myLastReceived=""; //Clear the last command out
}

//Here we define the function that we are using in our handler
function IMinHand($message)   //Note the header, all your handlers headers should look like this
{
  global $aim; //We need to make sure we are using the instance of the $aim class 
  $info=msg_parse(msg_type($message)); //Get the $info array.. This is highly recommended
  $aim->send_im($info['from'],$info['message']); //Send the message back to who sent it to us   	
}
?>

And thats it! With that, you have a working "bot" that utilizes message handlers!