NAME

Net::OSCAR - Implementation of AOL's OSCAR protocol for instant messaging

SYNOPSIS

use Net::OSCAR qw(:standard);

$oscar = Net::OSCAR->new();
$oscar->set_callback_foo(\&foo);
$oscar->signon($screenname, $password);
while(1) {
	$oscar->do_one_loop();
	# Do stuff
}

ABSTRACT

Net::OSCAR implements the OSCAR protocol which is used by AOL's AOL Instant Messenger service. To use the module, you create a Net::OSCAR object, register some functions as handlers for various events by using the module's callback mechanism, and then continually make calls to the module's event processing methods.

You probably want to use the :standard parameter when importing this module in order to have a few important constants added to your namespace.

No official documentation exists for the OSCAR protocol, so it had to be figured out by analyzing traffic generated by AOL's official AOL Instant Messenger client. That doesn't really help this module's stability much.

This module strives to be as compatible with Net::AIM as possible, but some protocol-level differences prevent total compatibility. The TOC protocol implemented by Net::AIM is simpler and more well-documented but less-powerful protocol then OSCAR. See the section on "Net::AIM Compatibility" for more information.

EVENT PROCESSING

There are two main ways for the module to handle event processing. The first is to call the do_one_loop method, which performs a select call on all the object's sockets and reads incoming commands from the OSCAR server on any connections which have them. The select call has a default timeout of 0.01 seconds which can be adjust using the timeout method.

The other way of doing event processing is designed to make it easy to integrate Net::OSCAR into an existing select-based event loop, especially one where you have many Net::OSCAR objects. Simply call the process_connections method with references to the lists of readers, writers, and errors given to you by select. Connections that don't belong to the object will be ignored, and connections that do belong to the object will be removed from the select lists so that you can use the lists for your own purposes. Here is an example that demonstrates how to use this method with multiple Net::OSCAR objects:

my $rin = $my_readers;
my $win = $my_writers;
foreach my $oscar(@oscars) {
	foreach my $socket($oscar->connections) {
		vec($rin, fileno $socket, 1) = 1;
		vec($win, fileno $socket, 1) = 1;
	}
}
my $ein = $rin | $win;
select($rin, $win, $ein, 0.01);
foreach my $oscar(@oscars) {
	$oscar->process_connections(\$rin, \$win, \$ein);
}

# Now $rin, $win, and $ein only have the file descriptors not
# associated with any of the OSCAR objects in them - we can
# process our events.

PREREQUISITES

Digest::MD5

FUNCTIONALITY

Net::OSCAR pretends to be WinAIM 4.3.2229. It supports remote buddylists including permit and deny settings. It also supports chat. At the present time, setting and retrieving of directory information is not supported; nor are email privacy settings, buddy icons, voice chat, stock ticker, and many other of the official AOL Instant Messenger client's features.

TERMINOLOGY/METHODOLOGY

When you sign on with the OSCAR service, you are establishing an OSCAR session. Net::OSCAR connects to the login server and requests a random challenge string. It then sends the MD5 sum of the challenge string, AOL Instant Messenger (SM), and your password to the server. If the login is successful, the login server gives you an IP address and an authorization cookie to use to connect with the BOS (Basic OSCAR Services) server.

Net::OSCAR proceeds to disconnect from the login server and connect to the BOS server. The two go through a handshaking process which includes the server sending us our buddylist. The buddylist includes our normal buddies as well as two special groups - the permit and deny groups. These groups, along with our visibility setting, determine who can contact us. Visibility can be set to permit or deny everyone, permit only those on the permit list, deny only those on the deny list, or permit everyone on our buddylist.

METHODS

new

Creates a new Net::OSCAR object.

timeout ([NEW TIMEOUT])

Gets or sets the timeout value used by the do_one_loop method. The default timeout is 0.01 seconds.

signon (SCREENNAME, PASSWORD)

Sign on to the OSCAR service.

debug (DEBUGLEVEL[, SCREENNAME DEBUG])

Sets the debugging level. If this is non-zero, lots of information will be printed to standard error. In theory, higher debugging levels will give you more information, but right now it's all or nothing. If the optional screenname debug parameter is non-zero, debug messages will be prepended with the screenname of the OSCAR session which is generating the message. This is useful when you have multiple Net::OSCAR objects.

process_connections (READERSREF, WRITERSREF, ERRORSREF)

Use this method when you want to implement your own select statement for event processing instead of using Net::OSCAR's do_one_loop method. The parameters are references to the readers, writers, and errors parameters used by the select statement. The method will ignore all connections which are not Net::OSCAR::Connection objects or which are Net::OSCAR::Connection objects from a different Net::OSCAR object. It modifies its arguments so that its connections are removed from the connection lists. This makes it very convenient for use with multiple Net::OSCAR objects or use with a select-based event loop that you are also using for other purposes.

See the connections method for a way to get the file descriptors to add to your select.

do_one_loop

Processes incoming data from our connections to the various OSCAR services. This method reads one command from any connections which have data to be read. See the timeout method to set the timeout interval used by this method.

findbuddy (BUDDY)

Returns the name of the group that BUDDY is in, or undef if BUDDY could not be found in any group. If BUDDY is in multiple groups, will return the first one we find. Note that this method skips the permit and deny groups.

add_permit (BUDDIES)

Add buddies to your permit list. Note that this is the same as calling add_buddy with a group of permit.

add_deny (BUDDIES)

See add_permit.

remove_permit (BUDDIES)

See add_permit.

remove_deny (BUDDIES)

See add_permit.

add_buddy (GROUP, BUDDIES)

Adds buddies to the given group on your buddylist.

remove_buddy (GROUP, BUDDIES)

See add_buddy.

set_visibility (MODE)

Sets the visibility mode, which determines how the permit and deny lists are interpreted. The visibility mode may be:

• VISMODE_PERMITALL: Permit everybody.

• VISMODE_DENYALL: Deny everybody.

• VISMODE_PERMITSOME: Permit only those on your permit list.

• VISMODE_DENYSOME: Deny only those on your deny list.

• VISMODE_PERMITBUDS: Same as VISMODE_PERMITSOME, but your permit list is made to be the same as the buddies from all the various groups in your buddylist (except the deny group!) Adding and removing buddies maintains this relationship. You shouldn't manually alter the permit or deny groups when using this visibility mode.

These constants are contained in the Net::OSCAR::Common package, and will be imported into your namespace if you import Net::OSCAR with the :standard parameter.

When someone is permitted, they can see when you are online and send you messages. When someone is denied, they can't see when you are online or send you messages. You cannot see them or send them messages. You can talk to them if you are in the same chatroom, although neither of you can invite the other one into a chatroom.

get_info (WHO)

Requests a user's information, which includes their profile and idle time. See the buddy_info callback for more information.

get_away (WHO)

Similar to get_info, except requests the user's away message instead of their profile.

send_im(WHO, MESSAGE[, AWAY])

Sends someone an instant message. If the message is an automated reply generated, perhaps, because you have an away message set, give the AWAY parameter a non-zero value. Note that Net::OSCAR will not handle sending away messages to people who contact you when you are away - you must perform this yourself if you want it done.

evil (WHO[, ANONYMOUSLY])

Evils, or warns, a user. Evilling a user increases their evil level, which makes them look bad and decreases the rate at which they can send messages. Evil level gradually decreases over time. If the second parameter is non-zero, the evil will be done anonymously, which does not increase the user's evil level by as much as a standard evil.

You can't always evil someone. You can only do it when they do something like send you an instant message.

set_away (MESSAGE)

Set's the users away message, also marking them as being away. If the message is undef or the empty string, the user will be marked as no longer being away.

set_info (PROFILE)

Sets the user's profile.

change_password (CURRENT PASSWORD, NEW PASSWORD)

Changes the user's password.

confirm_account

Confirms the user's account. This can be used when the user's account is in the trial state, as determined by the presence of the trial key in the information given when the user's information is requested.

change_email (NEW EMAIL)

Requests that the email address registered to the user's account be changed. This causes the OSCAR server to send an email to both the new address and the old address. To complete the change, the user must follow instructions contained in the email sent to the new address. The email sent to the old address contains instructions which allow the user to cancel the change within three days of the change request. It is important that the user's current email address be known to the OSCAR server so that it may email the account password if the user forgets it.

format_screenname (NEW FORMAT)

Allows the capitalization and spacing of the user's screenname to be changed. The new format must be the same as the user's current screenname, except that case may be changed and spaces may be inserted or deleted.

chat_join(NAME[, EXCHANGE])

Creates (or joins?) a chatroom. The exchange parameter should probably not be specified unless you know what you're doing. Do not use this method to accept invitations to join a chatroom - use the chat_accept method for that.

chat_accept (CHAT)

Use this to accept an invitation to join a chatroom.

set_idle (TIME)

Sets the user's idle time in seconds. Set to zero to mark the user as not being idle. Set to non-zero once the user becomes idle. The OSCAR server will automatically increment the user's idle time once you mark the user as being idle.

clone

Clones the object. This creates a new Net::OSCAR object whose callbacks, debug level, screenname debugging, and timeout are the same as those of the current object. This is provided as a convenience when using multiple Net::OSCAR objects in order to allow you to set those parameters once and then call the signon method on the object returned by clone.

connections

Returns all the filehandles being used by this object. At present, these are symbol references generated by the Socket package, but that might change in the future. However, this will always be something you can use the fileno function on. This method is provided primarily for use with the process_connections method.

visibility

Returns the user's current visibility setting. See set_visibility.

groups

Returns a list of groups in the user's buddylist. This includes the permit and deny groups.

buddies (GROUP)

Returns the names of the buddies in the specified group in the user's buddylist. The names may not be formatted - that is, they may have spaces and capitalization removed.

buddy (BUDDY[, GROUP])

Returns information about a buddy on the user's buddylist. This information is a hashref which may have the following keys:

online

The user is signed on. If this key is not present, all of the other keys may not be present.

screenname

The formatted version of the user's screenname. This includes all spacing and capitalization.

trial

The user's account has trial status.

aol

The user is accessing the AOL Instant Messenger service from America OnLine.

free

Opposite of aol.

away

The user is away.

admin

The user is an administrator.

membersince

Time that the user's account was created, in the same format as the time function.

onsince

Time that the user signed on to the service, in the same format as the time function.

idle

Time that the user has been idle for, in seconds. If this key is present but zero, the user is not idle. If this key is not present, the user is not reporting idle time.

email

Returns the email address currently assigned to the user's account.

screenname

Returns the user's current screenname, including all capitalization and spacing.

chat_invite(CHAT, MESSAGE, WHO)

Deprecated. Provided for compatibility with Net::AIM. Use the appropriate method of the Net::OSCAR::Chat object instead.

chat_leave(CHAT)

Deprecated. Provided for compatibility with Net::AIM. Use the appropriate method of the Net::OSCAR::Chat object instead.

chat_send(CHAT, MESSAGE)

Deprecated. Provided for compatibility with Net::AIM. Use the appropriate method of the Net::OSCAR::Chat object instead.

CALLBACKS

Net::OSCAR uses a callback mechanism to notify you about different events. A callback is registered by calling the set_callback_callbackname method with a code reference as a parameter. For instance, you might call $oscar-set_callback_error(\&got_error);>. Your callback function will be passed parameters which are different for each callback type (and are documented below). The first parameter to each callback function will be the Net::OSCAR object which generated the callback. This is useful when using multiple Net::OSCAR objects.

error (OSCAR, CONNECTION, DESCRIPTION, ERRNO, URL, REQDATA, FAMILY, SUBTYPE[, FATAL])

Called when any sort of error occurs (except see admin_error below.) Note that most of these parameters, except for OSCAR, DESCRIPTION, and FATAL, are optional.

CONNECTION is the particular connection which generated the error - the debug_print method of Net::OSCAR::Connection may be useful, as may be getting $connection-{description}>. DESCRIPTION is a somewhat nicely formatted error message. It is recommended that you just use this and ignore all the other parameters (except for FATAL) unless you want to get fancy.

ERRNO is the error number - a list of error descriptions indexed by error number is returned by Net::OSCAR::Common::ERRORS. URL is an http URL which the user can visit for more information about the error. REQDATA is some data the was associated with the request which generated the error. At present, it is a screenname for errors sending IMs or retrieving user information. FAMILY and SUBTYPE are the SNAC numbers of the request which generated the error and probably aren't too useful to you. FATAL is non-zero if the error was fatal - something like an invalid password on signon or the connection to OSCAR being severed.

rate_alert (OSCAR, LEVEL, CLEAR, WINDOW)

This is called when you are sending commands to OSCAR too quickly.

LEVEL is one of RATE_CLEAR, RATE_ALERT, RATE_LIMIT, or RATE_DISCONNECT from the Net::OSCAR::Common package (they are imported into your namespace if you import Net::OSCAR with the :standard parameter.) RATE_CLEAR means that you're okay. RATE_ALERT means you should slow down. RATE_LIMIT means that the server is ignoring messages from you until you slow down. RATE_DISCONNECT means you're about to be disconnected.

CLEAR and WINDOW tell you the maximum speed you can send in order to maintain RATE_CLEAR standing. You must send no more than WINDOW commands in CLEAR milliseconds. If you just want to keep it simple, you can just not send any commands for CLEAR milliseconds and you'll be fine.

admin_error (OSCAR, REQTYPE, ERROR, ERRURL)

This is called when there is an error performing an administrative function - changing your password, formatting your screenname, changing your email address, or confirming your account. REQTYPE is a string describing the type of request which generated the error. ERROR is an error message. ERRURL is an http URL which the user may visit for more information about the error.

admin_ok (OSCAR, REQTYPE)

This is called when an administrative function succeeds. See admin_error for more info.

chat_closed (OSCAR, CHAT, ERROR)

Your connection to CHAT (a Net::OSCAR::Chat object) was severed due to ERROR.

buddy_in (OSCAR, SCREENNAME, GROUP, BUDDY DATA)

SCREENNAME (in buddy group GROUP) has signed on, or their information has changed. BUDDY DATA is the same as that returned by the buddy method.

chat_buddy_in (OSCAR, SCREENNAME, CHAT, BUDDY DATA)

SCREENNAME has entered CHAT. BUDDY DATA is the same as that returned by the buddy method.

buddy_out (OSCAR, SCREENNAME, GROUP)

Called when a buddy has signed off (or added us to their deny list.)

chat_buddy_out (OSCAR, SCREENNAME, CHAT)

Called when someone leaves a chatroom.

im_in (OSCAR, FROM, MESSAGE[, AWAY])

Called when someone sends you an instant message. If the AWAY parameter is non-zero, the message was generated as an automatic reply, perhaps because you sent that person a message and they had an away message set.

chat_im_in(OSCAR, FROM, CHAT, MESSAGE)

Called when someone says something in a chatroom. Note that you receive your own messages in chatrooms unless you specify the NOREFLECT parameter in chat_send.

chat_invite(OSCAR, WHO, MESSAGE, CHAT)

Called when someone invites us into a chatroom. MESSAGE is the message that they specified on the invitation. CHAT is a chat URL and not a Net::OSCAR::Chat object. CHAT can be passed to the chat_accept method to accept the invitation.

chat_joined(OSCAR, CHATNAME, CHAT)

Called when you enter a chatroom. CHAT is the Net::OSCAR::Chat object for the chatroom.

evil(OSCAR, NEWEVIL[, FROM])

Called when your evil level changes. NEWEVIL is your new evil level, as a percentage (accurate to tenths of a percent.) ENEMY is undef if the evil was anonymous (or if the message was triggered because your evil level naturally decreased), otherwise it is the screenname of the person who sent us the evil. See the evil method for more information on evils.

buddy_info(OSCAR, SCREENNAME, BUDDY DATA)

Called in response to a get_info or get_away request. BUDDY DATA is the same as that returned by the buddy method, except that one of two additional keys, profile and awaymsg, may be present.

signon_done(OSCAR)

Called when the user is completely signed on to the service.

CHATS

Aside from the methods listed here, there are a couple of methods of the Net::OSCAR::Chat object that are important for implementing chat functionality. Net::OSCAR::Chat is a descendent of Net::OSCAR::Connection.

invite (WHO, MESSAGE)

Invite somebody into the chatroom.

chat_send (MESSAGE[, NOREFLECT[, AWAY]])

Sends a message to the chatroom. If the NOREFLECT parameter is present, you will not receive the message as an incoming message from the chatroom. If AWAY is present, the message was generated as an automatic reply, perhaps because you have an away message set.

part

Leave the chatroom.

Net::AIM Compatibility

Here are the major differences between the Net::OSCAR interface and the Net::AIM interface:

• No get/set method.

• No newconn/getconn method.

• No group parameter for add_permit or add_deny.

• Many differences in chat handling.

• No chat_whisper.

• No encode method - it isn't needed.

• No send_config method - it isn't needed.

• No send_buddies method - we don't keep a separate local buddylist.

• No normalize method - it isn't needed. Okay, there is a normalize function in Net::OSCAR::Common, but I can't think of any reason why it would need to be used outside of the module internals.

• Different callbacks with different parameters.

MISCELLANEOUS

There are two programs included with the Net::OSCAR distribution. oscartest is a minimalist implementation of a Net::OSCAR client. snacsnatcher is a tool designed for analyzing the OSCAR protocol from libpcap-format packet captures.

SUPPORT

See http://www.zevils.com/programs/net-oscar/ for support, including a mailing list and bug-tracking system.

AUTHOR

Matthew Sachs <matthewg@zevils.com>.

CREDITS

John "VBScript" for a lot of technical assistance, including the explanation of rates.

Adam Fritzler and the libfaim team for their documentation and an OSCAR implementation that was used to help figure out a lot of the protocol details. <http://www.zigamorph.net/faim/protocol/>

Mark Doliner for help with remote buddylists. <http://kingant.net/libfaim/ReadThis.html>

The gaim team - the source to their libfaim client was also very helpful. <http://gaim.sourceforge.net/>

The users of aimirc for being reasonably patient while this module was developed. <http://www.zevils.com/programs/aimirc/>

Jayson Baker for some last-minute debugging help.

AOL, for creating the AOL Instant Messenger service, even though they aren't terribly helpful to developers of third-party clients.

LEGAL

Copyright (c) 2001 Matthew Sachs. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AOL Instant Messenger and AIM are registered service marks of AOL/Time Warner. America OnLine is a registered trademark of AOL/Time Warner. Net::OSCAR is not affiliated with, endorsed by, or supported by AOL.