Net::OSCAR

a b c d e f g h i j k l m n o p q r s t u v w x y z _

Net::OSCAR(3) User Contributed Perl Documentation Net::OSCAR(3)

NAME
Net::OSCAR - Implementation of AOL’s OSCAR protocol for instant mes-
saging (for interacting with AIM a.k.a. AOL IM a.k.a. AOL Instant Mes-
senger - and ICQ, too!)

SYNOPSIS
use Net::OSCAR qw(:standard);

sub im_in {
my($oscar, $sender, $message, $is_away) = @_;
print "[AWAY] " if $is_away;
print "$sender: $message\n";
}

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

INSTALLATION
HOW TO INSTALL

perl Build.PL
perl Build
perl Build test
perl Build install

See "perldoc Module::Build" for details. Note that this requires that
you have the perl module Module::Build installed. If you don’t, the
traditional "perl Makefile.PL ; make ; make test ; make install"
should still work.

DEPENDENCIES

This modules requires "Digest::MD5" and "Scalar::Util". "Test::More"
is needed to run the test suite, and "XML::Parser" is needed to gener-
ate the XML parse tree which is shipped with released versions.

INTRODUCTION
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 names-
pace. See "CONSTANTS" below for a list of the constants exported by
the ":standard" tag.

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. Source code from the Gaim client, the pro-
tocol analysis provided by the Ethereal network sniffer, and the
Alexander Shutko’s website <http://iserverd1.khstu.ru/oscar/> were
also used as references.

This module strives to be as compatible with "Net::AIM" as possible at
the API level, but some protocol-level differences prevent total com-
patibility. The TOC protocol implemented by "Net::AIM" is simpler
than OSCAR and has official reference documentation from AOL, but it
only provides a small subset of the full "OSCAR" functionality. See
the section on "Net::AIM Compatibility" for more information.

EVENT PROCESSING OVERVIEW

Event processing is the implementation of "Net::OSCAR" within the
framework of your program, so that your program can respond to things
happening on the OSCAR servers while still doing everything else that
you need it to do, such as accepting user input. There are three main
ways for the module to handle event processing. The simplest 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 adjusted using the timeout
method. This means that every time you call do_one_loop, it will
pause for that interval if there are no messages from the OSCAR
server. If you need lower overhead, want better performance, or need
to handle many Net::OSCAR objects and/or other files and sockets at
once, see "HIGH-PERFORMANCE EVENT PROCESSING" below.

FUNCTIONALITY

"Net::OSCAR" pretends to be WinAIM 5.5.3595. It supports remote bud-
dylists including permit and deny settings. It also supports chat,
buddy icons, and extended status messages. At the present time, set-
ting and retrieving of directory information is not supported; nor are
email privacy settings, voice chat, stock ticker, file transfer,
direct IM, and many other of the official AOL Instant Messenger
client’s features.

TERMINOLOGY

When you sign on with the OSCAR service, you are establishing an OSCAR
session.

CALLBACKS

"Net::OSCAR" uses a callback mechanism to notify you about different
events. A callback is a function provided by you which "Net::OSCAR"
will call when a certain event occurs. To register a callback, call-
ing the "set_callback_callbackname" method with a code reference as a
parameter. For instance, you might call "$oscar->set_call-
back_error(\&got_error);". Your callback function will be passed
parameters which are different for each callback type (and are docu-
mented 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.

REFERENCE
BASIC FUNCTIONALITY

METHODS

new ([capabilities => CAPABILITIES], [rate_manage => RATE_MAN-
AGE_MODE])
Creates a new "Net::OSCAR" object. You may optionally pass a hash
to set some parameters for the object.

capabilities
A listref of optional features that your client supports.
Valid capabilities are:

extended_status
iChat-style extended status messages

buddy_icons
file_transfer
file_sharing
typing_status
Typing status notification

buddy_list_transfer
rate_manage
Which mechanism will your application be using to deal with
the sending rates which the server enforces on the client?
See "RATE LIMIT OVERVIEW" for more information on the subject.

OSCAR_RATE_MANAGE_NONE
OSCAR_RATE_MANAGE_AUTO
OSCAR_RATE_MANAGE_MANUAL

$oscar = Net::OSCAR->new(capabilities => [qw(extended_status typing_status)], rate_manage => OSCAR_RATE_MANAGE_AUTO);

signon (HASH)
signon (SCREENNAME, PASSWORD[, HOST, PORT]
Sign on to the OSCAR service. You can specify an alternate
host/port to connect to. The default is login.oscar.aol.com port
5190.

The non-hash form of "signon" is obsolete and is only provided for
compatibility with "Net::AIM". If you use a hash to pass parame-
ters to this function, here are the valid keys:

screenname
password
Screenname and password are mandatory. The other keys are
optional. In the special case of password being present but
undefined, the auth_challenge callback will be used - see
"auth_challenge" for details.

stealth
Use this to sign on with stealth mode activated. Using this,
as opposed to signon on without this setting and then calling
"set_stealth", will prevent the user from showing as online
for a brief interval after signon. See "set_stealth" for
information about stealth mode.

pass_is_hashed
If you want to give Net::OSCAR the MD5 hash of the password
instead of the password itself, use the MD5’d password in the
password key and also set this key. The benefit of this is
that, if your application saves user passwords, you can save
them in hashed form and don’t need to store the plaintext.

local_ip
If you have more than one IP address with a route to the
internet, this parameter can be used to specify which to use
as the source IP for outgoing connections.

local_port
This controls which port Net::OSCAR will listen on for incom-
ing direct connections. If not specified, a random port will
be selected.

host
port
proxy_type
Either "SOCKS4", "SOCKS5", "HTTP", or HTTPS. This and
"proxy_host" must be specified if you wish to use a proxy.
"proxy_port", "proxy_username", "proxy_password" are optional.
Note that proxy support is considered experimental. You will
need to have the "Net::SOCKS" module installed for SOCKS prox-
ying or the "LWP::UserAgent" module installed for HTTP proxy-
ing.

proxy_host
proxy_port
proxy_username
proxy_password

If the screenname is all-numeric, it will automatically be treated
as an ICQ UIN instead of an AIM screenname.

signoff
Sign off from the OSCAR service.

CALLBACKS

signon_done (OSCAR)
Called when the user is completely signed on to the service.

BUDDIES AND BUDDYLISTS

See also "OTHER USERS" for methods which pertain to any other user,
regardless of whether they’re on the buddylist or not.

METHODS

findbuddy (BUDDY)
In scalar context, 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.

In list context, returns a two-element list consisting of the
group name followed by the group hashref (or the empty list of the
buddy is not found.)

commit_buddylist
Sends your modified buddylist to the OSCAR server. Changes to the
buddylist won’t actually take effect until this method is called.
Methods that change the buddylist have a warning about needing to
call this method in their documentation. After calling this
method, your program MUST not call it again until either the bud-
dylist_ok or buddylist_error callbacks are received.

rollback_buddylist
Revert changes you’ve made to the buddylist, assuming you haven’t
called "commit_buddylist" since making them.

reorder_groups (GROUPS)
Changes the ordering of the groups in your buddylist. Call "com-
mit_buddylist" to save the new order on the OSCAR server.

reorder_buddies (GROUP, BUDDIES)
Changes the ordering of the buddies in a group on your buddylist.
Call "commit_buddylist" to save the new order on the OSCAR server.

rename_group (OLDNAME, NEWNAME)
Renames a group. Call "commit_buddylist" for the change to take
effect.

add_buddy (GROUP, BUDDIES)
Adds buddies to the given group on your buddylist. If the group
does not exist, it will be created. Call "commit_buddylist" for
the change to take effect.

remove_buddy (GROUP, BUDDIES)
See add_buddy.

add_group (GROUP)
Creates a new, empty group. Call "commit_buddylist" for the
change to take effect.

remove_group (GROUP)
See add_group. Any buddies in the group will be removed from the
group first.

groups
Returns a list of groups in the user’s buddylist.

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. The names are
"Net::OSCAR::Screenname" objects, so you don’t have to worry that
they’re case and whitespace insensitive when using them for com-
parison.

buddy (BUDDY[, GROUP])
Returns information about a buddy on the user’s buddylist. This
information is a hashref as per "USER INFORMATION" below.

set_buddy_comment (GROUP, BUDDY[, COMMENT])
Set a brief comment about a buddy. You must call "commit_bud-
dylist" to save the comment to the server. If COMMENT is unde-
fined, the comment is deleted.

set_buddy_alias (GROUP, BUDDY[, ALIAS])
Set an alias for a buddy. You must call "commit_buddylist" to
save the comment to the server. If ALIAS is undefined, the alias
is deleted.

buddylist_limits
Returns a hash containing the maximum number of buddylist entries
of various types. The keys in the hash are:

* buddies

* groups

* permits

* denies

So, the maximum number of buddies allowed on a buddylist is stored
in the "buddies" key. Please note that buddylist storage has some
overhead, so the actual number of items you can have on a bud-
dylist may be slightly less than advertised.

If the OSCAR server did not inform us of the limits, values of 0
will be used.

CALLBACKS

buddy_in (OSCAR, SCREENNAME, GROUP, BUDDY DATA)
SCREENNAME (in buddy group GROUP) has signed on, or their informa-
tion has changed. 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.)

buddylist_error (OSCAR, ERROR, WHAT)
This is called when there is an error commiting changes to the
buddylist. "ERROR" is the error number. "WHAT" is a string
describing which buddylist change failed. "Net::OSCAR" will
revert the failed change to its state before "commit_buddylist"
was called. Note that the buddylist contains information other
than the user’s buddies - see any method which says you need to
call "commit_buddylist" to have its changes take effect.

buddylist_ok (OSCAR)
This is called when your changes to the buddylist have been suc-
cessfully commited.

buddylist_changed (OSCAR, CHANGES)
This is called when your buddylist is changed by the server. The
most common reason for this to happen is if the screenname you are
signed on with is also signed on somewhere else, and the buddylist
is changed in the other session.

Currently, only changes to buddies and groups will be listed in
"CHANGES". Changes to privacy settings and any other portions of
the buddylist will not be included in the list in the current ver-
sion of "Net::OSCAR".

"CHANGES" is a list of hash references, one for each change to the
buddylist, with the following keys:

* type: Either "MODBL_WHAT_BUDDY" or "MODBL_WHAT_GROUP". This
indicates if the change was to a buddy or a group.

* action: Either "MODBL_ACTION_DEL" or "MODBL_ACTION_ADD". This
indicates whether the change was an addition/modification or a
deletion.

* group: The name of the group which the modification took place
in. For "MODBL_WHAT_BUDDY", this will be the name of the
group which the changed buddy was changed in; for
"MODBL_WHAT_GROUP", this will be the name of the group which
was changed.

* buddy: This key is only present for "MODBL_WHAT_BUDDY". It’s
the name of the buddy which was changed.

The "MODBL_*" constants come from "Net::OSCAR::Common", and are
included in the ":standard" export list.

PRIVACY

"Net::OSCAR" supports privacy controls. Our visibility setting, along
with the contents of the permit and deny lists, determines 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

add_permit (BUDDIES)
Add buddies to your permit list. Call "commit_buddylist" for the
change to take effect.

add_deny (BUDDIES)
See add_permit.

remove_permit (BUDDIES)
See add_permit.

remove_deny (BUDDIES)
See add_permit.

get_permitlist
Returns a list of all members of the permit list.

get_denylist
Returns a list of all members of the deny list.

visibility
Returns the user’s current visibility setting. See set_visibil-
ity.

set_visibility (MODE)
Sets the visibility mode, which determines how the permit and deny
lists are interpreted. Note that if you’re looking for the fea-
ture which will prevent a user from showing up as online on any
buddy list while not affecting anything else, the droids you’re
looking for are "is_stealth"/"set_stealth".

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 per-
mit 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 chat-
room, although neither of you can invite the other one into a cha-
troom.

Call "commit_buddylist" for the change to take effect.

is_stealth
set_stealth STEALTH_STATUS
These methods deal with "stealth mode". When the user is in
stealth mode, she won’t show up as online on anyone’s buddylist.
However, for all other purposes, she will be online as usual. Any
restrictions, imposed by the visibility mode (see "set_visibil-
ity"), on who can communicate with her will remain in effect.

Stealth state can be changed by another signon of the user’s
screenname. So, if you want your application to be aware of the
stealth state, "is_stealth" won’t cut it; there’s a
"stealth_changed" callback which will serve nicely.

set_group_permissions (NEWPERMS)
Set group permissions. This lets you block any OSCAR users or any
AOL users. "NEWPERMS" should be a list of zero or more of the
following constants:

GROUPPERM_OSCAR
Permit AOL Instant Messenger users to contact you.

GROUPPERM_AOL
Permit AOL subscribers to contact you.

Call "commit_buddylist" for the change to take effect.

group_permissions
Returns current group permissions. The return value is a list
like the one that "set_group_permissions" wants.

OTHER USERS

See also "BUDDIES AND BUDDYLISTS".

METHODS

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.

Returns a "request ID" that you can use in the "im_ok" callback to
identify the message. If the message was too long to send,
returns zero.

send_typing_status (RECIPIENT, STATUS)
Send a typing status change to another user. Send these messages
to implement typing status notification. Valid values for "STA-
TUS" are:

* TYPINGSTATUS_STARTED: The user has started typing to the
recipient. This indicates that typing is actively taking
place.

* TYPINGSTATUS_TYPING: The user is typing to the recipient.
This indicates that there is text in the message input area,
but typing is not actively taking place at the moment.

* TYPINGSTATUS_FINISHED: The user has finished typing to the
recipient. This should be sent when the user starts to com-
pose a message, but then erases all of the text in the message
input area.

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 anony-
mously, 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.

get_icon (SCREENNAME, MD5SUM)
Gets a user’s buddy icon. See set_icon for details. To make sure
this method isn’t called excessively, please check the
"icon_checksum" and "icon_timestamp" data, which are available via
the buddy method (even for people not on the user’s buddy list.)
The MD5 checksum of a user’s icon will be in the "icon_md5sum" key
returned by buddy.

You should receive a buddy_icon_downloaded callback in response to
this method.

CALLBACKS

new_buddy_icon (OSCAR, SCREENNAME, BUDDY DATA)
This is called when someone, either someone the user is talking
with or someone on their buddylist, has a potentially new buddy
icon. The buddy data is guaranteed to have at least "icon_check-
sum" available; "icon_timestamp" and "icon_length" may not be.
Specifically, if "Net::OSCAR" found out about the buddy icon
through a buddy status update (the sort that triggers a buddy_in
callback), these data will not be available; if "Net::OSCAR" found
out about the icon via an incoming IM from the person, these data
will be available.

Upon receiving this callback, an application should use the
"icon_checksum" to search for the icon in its cache, and call
get_icon if it can’t find it. If the "icon_md5sum", which is what
needs to get passed to get_icon, is not present in the buddy data,
use get_info to request the information for the user, and then
call get_icon from the buddy_info callback.

buddy_icon_downloaded (OSCAR, SCREENNAME, ICONDATA)
This is called when a user’s buddy icon is successfully downloaded
from the server.

typing_status (OSCAR, SCREENNAME, STATUS)
Called when someone has sent us a typing status notification mes-
sage. See send_typing_status for a description of the different
statuses.

im_ok (OSCAR, TO, REQID)
Called when an IM to "TO" is successfully sent. REQID is the
request ID of the IM as returned by "send_im".

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.

buddylist_in (OSCAR, FROM, BUDDYLIST)
Called when someone sends you a buddylist. You must set the
"buddy_list_transfer" capability for buddylists to be sent to you.
The buddylist will be a "Net::OSCAR::Buddylist" hashref whose keys
are the groups and whose values are listrefs of
"Net::OSCAR::Screenname" strings for the buddies in the group.

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.

THE SIGNED-ON USER

These methods deal with the user who is currently signed on using a
particular "Net::OSCAR" object.

METHODS

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

screenname
Returns the user’s current screenname, including all capitaliza-
tion and spacing.

is_on
Returns true if the user is signed on to the OSCAR service. Oth-
erwise, returns false.

profile
Returns your current profile.

set_away (MESSAGE)
Sets the user’s 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. See also "get_away".

set_extended_status (MESSAGE)
Sets the user’s extended status message. This requires the
"Net::OSCAR" object to have been created with the "extended_sta-
tus" capability. Currently, the only clients which support
extended status messages are Net::OSCAR, Gaim, and iChat. If the
message is undef or the empty string, the user’s extended status
message will be cleared. Use "get_info" to get another user’s
extended status.

set_info (PROFILE)
Sets the user’s profile. Call "commit_buddylist" to have the new
profile saved into the buddylist, so that it will be set the next
time the screenname is signed on. (This is a Net::OSCAR-specific
feature, so other clients will not pick up the profile from the
buddylist.)

Note that Net::OSCAR stores the user’s profile in the server-side
buddylist, so if "commit_buddylist" is called after setting the
profile with this method, the user will automatically get that
same profile set whenever they sign on through Net::OSCAR. See
the file "PROTOCOL", included with the "Net::OSCAR" distribution,
for details of how we’re storing this data.

Use "get_info" to retrieve another user’s profile.

set_icon (ICONDATA)
Sets the user’s buddy icon. The "Net::OSCAR" object must have
been created with the "buddy_icons" capability to use this.
"ICONDATA" must be less than 4kb, should be 48x48 pixels, and
should be BMP, GIF, or JPEG image data. You must call commit_bud-
dylist for this change to take effect. If "ICONDATA" is the empty
string, the user’s buddy icon will be removed.

When reading the icon data from a file, make sure to call "bin-
mode" on the file handle.

Note that if the user’s buddy icon was previously set with
Net::OSCAR, enough data will be stored in the server-side bud-
dylist that this will not have to be called every time the user
signs on. However, other clients do not store the extra data in
the buddylist, so if the user previously set a buddy icon with a
non-Net::OSCAR-based client, this method will need to be called in
order for the user’s buddy icon to be set properly.

See the file "PROTOCOL", included with the "Net::OSCAR" distribu-
tion, for details of how we’re storing this data.

You should receive a buddy_icon_uploaded callback in response to
this method.

Use "get_icon" to retrieve another user’s icon.

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 informa-
tion 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 instruc-
tions 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.

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.

CALLBACKS

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.

buddy_icon_uploaded (OSCAR)
This is called when the user’s buddy icon is successfully uploaded
to the server.

stealth_changed (OSCAR, NEW_STEALTH_STATE)
This is called when the user’s stealth state changes. See
"is_stealth" and "set_stealth" for information on stealth.

extended_status (OSCAR, STATUS)
Called when the user’s extended status changes. This will nor-
mally be sent in response to a successful set_extended_status
call.

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 trig-
gered 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.

FILE TRANSFER AND DIRECT CONNECTIONS

file_send SCREENNAME MESSAGE FILEREFS
"FILEDATA" can be undef to have Net::OSCAR read the file, a file
handle, or the data to send.

EVENT PROCESSING

METHODS

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.

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::Con-
nection" 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 selector_filenos method for a way to get the necessary bit
vectors to use in your "select".

CALLBACKS

connection_changed (OSCAR, CONNECTION, STATUS)
Called when the status of a connection changes. The status is
"read" if we should call "process_one" on the connection when
"select" indicates that the connection is ready for reading,
"write" if we should call "process_one" when the connection is
ready for writing, "readwrite" if "process_one" should be called
in both cases, or "deleted" if the connection has been deleted.

"CONNECTION" is a "Net::OSCAR::Connection" object.

Users of this callback may also be interested in the "get_filehan-
dle" method of "Net::OSCAR::Connection".

CHATS

METHODS

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 (CHATURL)
Use this to accept an invitation to join a chatroom.

chat_decline (CHATURL)
Use this to decline an invitation to join a chatroom.

CALLBACKS

chat_buddy_in (OSCAR, SCREENNAME, CHAT, BUDDY DATA)
SCREENNAME has entered CHAT. BUDDY DATA is the same as that
returned by the buddy method.

chat_buddy_out (OSCAR, SCREENNAME, CHAT)
Called when someone leaves a chatroom.

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, CHATURL)
Called when someone invites us into a chatroom. MESSAGE is the
message that they specified on the invitation. CHAT is the name
of the chatroom. CHATURL is a chat URL and not a
"Net::OSCAR::Connection::Chat" object. CHATURL 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::Con-
nection::Chat" object for the chatroom.

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

RATE LIMITS

See "RATE LIMIT OVERVIEW" for more information on rate limits.

METHODS

rate_level (OSCAR, METHODNAME[, CHAT])
Returns the rate level (one of "RATE_CLEAR", "RATE_ALERT",
"RATE_LIMIT", "RATE_DISCONNECT") which the OSCAR session is cur-
rently at for the "Net::OSCAR" (or "Net::OSCAR::Connection::Chat")
method named "METHODNAME" right now. This only makes sense for
methods which send information to the OSCAR server, such as
"send_im", but if you pass in a method name which doesn’t make
sense (or isn’t actually a "Net::OSCAR" method, or which isn’t
rate-limited), we’ll gladly an empty list. This method is not
available if your application is using "OSCAR_RATE_MANAGE_NONE".

If "METHODNAME" is "chat_send", you should also pass the
"Net::OSCAR::Connection::Chat" object to get rate information on
(as the "CHAT" parameter.)

rate_limits (OSCAR, METHODNAME[, CHAT])
Similar to "rate_level". This returns the boundaries of the dif-
ferent rate level categories for the given method name, in the
form of a hash with the following keys (this won’t make sense if
you don’t know how the current level is calculated; see below):

window_size
levels
A hashref with keys for each of the levels. Each key is the
name of a level, and the value for that key is the threshold
for that level.

clear
alert
limit
disconnect
last_time
The time at which the last command to affect this rate level
was sent.

current_state
The session’s current rate level.

Every time a command is sent to the OSCAR server, the level is
recalculated according to the formula (from Alexandr Shutko’s
OSCAR documentation, <http://iserverd.khstu.ru/oscar/>:

NewLevel = (Window - 1)/Window * OldLevel + 1/Window * CurrentTimeDiff

"CurrentTimeDiff" is the difference between the current system
time and "last_time".

would_make_rate_level (OSCAR, METHODNAME[, CHAT])
Returns the rate level which your session would be at if "METHOD-
NAME" were sent right now. See "rate_level" for more information.

CALLBACKS

rate_alert (OSCAR, LEVEL, CLEAR, WINDOW, WORRISOME, VIRTUAL)
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.

"WORRISOME" is nonzero if "Net::OSCAR" thinks that the alert is
anything worth worrying about. Otherwise it is zero. This is
very rough, but it’s a good way for the lazy to determine whether
or not to bother passing the alert on to their users.

A "VIRTUAL" rate limit is one which your application would have
incurred, but you’re using automatic rate management, so we
stopped something from being sent out.

MISCELLANEOUS

METHODS

timeout ([NEW TIMEOUT])
Gets or sets the timeout value used by the do_one_loop method.
The default timeout is 0.01 seconds.

loglevel ([LOGLEVEL[, SCREENNAME DEBUG]])
Gets or sets the level of logging verbosity. If this is non-zero,
varing amounts of information will be printed to standard error
(unless you have a "log" callback defined). Higher loglevels will
give you more information. 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
(but only if you don’t have a "log" callback defined). This is
useful when you have multiple "Net::OSCAR" objects.

See the "log" callback for more information.

auth_response (MD5_DIGEST[, PASS_IS_HASHED])
Provide a response to an authentication challenge - see the
"auth_challenge" callback for details.

clone
Clones the object. This creates a new "Net::OSCAR" object whose
callbacks, loglevel, screenname debugging, and timeout are the
same as those of the current object. This is provided as a conve-
nience 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.

buddyhash
Returns a reference to a tied hash which automatically normalizes
its keys upon a fetch. Use this for hashes whose keys are AIM
screennames since AIM screennames with different capitalization
and spacing are considered equivalent.

The keys of the hash as returned by the "keys" and "each" func-
tions will be "Net::OSCAR::Screenname" objects, so you they will
automagically be compared without regards to case and whitespace.

findconn (FILENO)
Finds the connection that is using the specified file number, or
undef if the connection could not be found. Returns a
"Net::OSCAR::Connection" object.

selector_filenos
Returns a list whose first element is a vec of all filehandles
that we care about reading from and whose second element is a vec
of all filehandles that we care about writing to. See the "pro-
cess_connections" method for details.

icon_checksum (ICONDATA)
Returns a checksum of the buddy icon. Use this in conjunction
with the "icon_checksum" buddy info key to cache buddy icons.

get_app_data ([GROUP[, BUDDY]])
Gets application-specific data. Returns a hashref whose keys are
app-data IDs. IDs with high-order byte 0x0001 are reserved for
non-application-specific usage and must be registered with the
"libfaim-aim-protocol@lists.sourceforge.net" list. If you wish to
set application-specific data, you should reserve a high-order
byte for your application by emailing "libfaim-aim-proto-
col@lists.sourceforge.net". This data is stored in your server-
side buddylist and so will be persistent, even across machines.

If "GROUP" is present, a hashref for accessing data specific to
that group is returned.

If "BUDDY" is present, a hashref for accessing data specific to
that buddy is returned.

Call "commit_buddylist" to have the new data saved on the OSCAR
server.

chat_invite (CHAT, MESSAGE, WHO)
Deprecated. Provided for compatibility with "Net::AIM". Use the
appropriate method of the "Net::OSCAR::Connection::Chat" object
instead.

chat_leave (CHAT)
Deprecated. Provided for compatibility with "Net::AIM". Use the
appropriate method of the "Net::OSCAR::Connection::Chat" object
instead.

chat_send (CHAT, MESSAGE)
Deprecated. Provided for compatibility with "Net::AIM". Use the
appropriate method of the "Net::OSCAR::Connection::Chat" object
instead.

CALLBACKS

auth_challenge (OSCAR, CHALLENGE, HASHSTR)
New for Net::OSCAR 2.0: AOL Instant Messenger has changed their
encryption mechanisms; instead of using the password in the hash,
you may now use the MD5 hash of the password. This allows your
application to save the user’s password in hashed form instead of
plaintext if you’re saving passwords. You must pass an extra
parameter to "auth_response" indicating that you are using the new
encryption scheme. See below for an example.

OSCAR uses an MD5-based challenge/response system for authentica-
tion so that the password is never sent in plaintext over the net-
work. When a user wishes to sign on, the OSCAR server sends an
arbitrary number as a challenge. The client must respond with the
MD5 digest of the concatenation of, in this order, the challenge,
the password, and an additional hashing string (currently always
the string "AOL Instant Messenger (SM)", but it is possible that
this might change in the future.)

If password is undefined in "signon", this callback will be trig-
gered when the server sends a challenge during the signon process.
The client must reply with the MD5 digest of CHALLENGE . MD5(pass-
word) . HASHSTR. For instance, using the MD5::Digest module:

my($oscar, $challenge, $hashstr) = @_;
my $md5 = Digest::MD5->new;
$md5->add($challenge);
$md5->add(md5("password"));
$md5->add($hashstr);
$oscar->auth_response($md5->digest, 1);

Note that this functionality is only available for certain ser-
vices. It is available for AIM but not ICQ. Note also that the
MD5 digest must be in binary form, not the more common hex or
base64 forms.

log (OSCAR, LEVEL, MESSAGE)
Use this callback if you don’t want the log_print methods to just
print to STDERR. It is called when even "MESSAGE" of level
"LEVEL" is called. The levels are, in order of increasing impor-
tance:

OSCAR_DBG_NONE
Really only useful for setting in the "loglevel" method. No
information will be logged. The default loglevel.

OSCAR_DBG_PACKETS
Hex dumps of all incoming/outgoing packets.

OSCAR_DBG_DEBUG
Information useful for debugging "Net::OSCAR", and precious
little else.

OSCAR_DBG_SIGNON
Like "OSCAR_DBG_NOTICE", but only for the signon process; this
is where problems are most likely to occur, so we provide this
for the common case of people who only want a lot of informa-
tion during signon. This may be deprecated some-day and be
replaced by a more flexible facility/level system, ala syslog.

OSCAR_DBG_NOTICE
OSCAR_DBG_INFO
OSCAR_DBG_WARN

Note that these symbols are imported into your namespace if and
only if you use the ":loglevels" or ":all" tags when importing the
module (e.g. "use Net::OSCAR qw(:standard :loglevels)".)

Also note that this callback is only triggered for events whose
level is greater than or equal to the loglevel for the OSCAR ses-
sion. The "loglevel" method allows you to get or set the
loglevel.

ERROR HANDLING

CALLBACKS

error (OSCAR, CONNECTION, ERROR, DESCRIPTION, FATAL)
Called when any sort of error occurs (except see admin_error below
and buddylist_error in "BUDDIES AND BUDDYLISTS".)

"CONNECTION" is the particular connection which generated the
error - the "log_print" method of "Net::OSCAR::Connection" may be
useful, as may be getting "$connection->{description}". "DESCRIP-
TION" is a nicely formatted description of the error. "ERROR" is
an error number.

If "FATAL" is non-zero, the error was fatal and the connection to
OSCAR has been closed.

snac_unknown (OSCAR, CONNECTION, SNAC, DATA)
Called when Net::OSCAR receives a message from the OSCAR server
which it doesn’t known how to handle. The default handler for
this callback will print out the unknown SNAC.

"CONNECTION" is the "Net::OSCAR::Connection" object on which the
unknkown message was received. "SNAC" is a hashref with keys such
as "family", "subtype", "flags1", and "flags2".

CHAT CONNECTIONS
Aside from the methods listed here, there are a couple of methods of
the "Net::OSCAR::Connection::Chat" object that are important for
implementing chat functionality. "Net::OSCAR::Connection::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.

url Returns the URL for the chatroom. Use this to associate a chat
invitation with the chat_joined that "Net::OSCAR" sends when
you’ve join the chatroom.

name
Returns the name of the chatroom.

exchange
Returns the exchange of the chatroom. This is normally 4 but can
be 5 for certain chatrooms.

RATE LIMIT OVERVIEW
The OSCAR server has the ability to specify restrictions on the rate
at which the client, your application, can send it commands. These
constraints can be independently set and tracked for different classes
of command, so there might be one limit on how fast you can send IMs
and another on how fast you can request away messages. If your appli-
cation exceeds these limits, the OSCAR server may start ignoring it or
may even disconnect your session.

See also the reference section on rate limits.

RATE MANAGEMENT MODES

"Net::OSCAR" supports three different schemes for managing these lim-
its. Pass the scheme you want to use as the value of the "rate_man-
age" key when you invoke the "new" method.

OSCAR_RATE_MANAGE_NONE

The default. "Net::OSCAR" will not keep track of what the limits are,
much less how close you’re coming to reaching them. If the OSCAR
server complains that you are sending too fast, your "rate_alert"
callback will be triggered.

OSCAR_RATE_MANAGE_AUTO

In this mode, "Net::OSCAR" will prevent your application from exceed-
ing the limits. If you try to send a command which would cause the
limits to be exceeded, your command will be queued. You will be noti-
fied when this happens via the "rate_alert" callback. This mode is
only available if your application implements "Net::OSCAR"’s time-
delayed event system.

OSCAR_RATE_MANAGE_MANUAL

In this mode, "Net::OSCAR" will track what the limits are and how
close you’re coming to reaching them, but won’t do anything about it.
Your application should use the "rate_level", "rate_limits", and
"would_make_rate_level" methods to control its own rate.

TIME-DELAYED EVENTS
CONSTANTS
The following constants are defined when "Net::OSCAR" is imported with
the ":standard" tag. Unless indicated otherwise, the constants are
magical scalars - they return different values in string and numeric
contexts (for instance, an error message and an error number.)

ADMIN_TYPE_PASSWORD_CHANGE
ADMIN_TYPE_EMAIL_CHANGE
ADMIN_TYPE_SCREENNAME_FORMAT
ADMIN_TYPE_ACCOUNT_CONFIRM
ADMIN_ERROR_UNKNOWN
ADMIN_ERROR_BADPASS
ADMIN_ERROR_BADINPUT
ADMIN_ERROR_BADLENGTH
ADMIN_ERROR_TRYLATER
ADMIN_ERROR_REQPENDING
ADMIN_ERROR_CONNREF
VISMODE_PERMITALL
VISMODE_DENYALL
VISMODE_PERMITSOME
VISMODE_DENYSOME
VISMODE_PERMITBUDS
RATE_CLEAR
RATE_ALERT
RATE_LIMIT
RATE_DISCONNECT
OSCAR_RATE_MANAGE_NONE
OSCAR_RATE_MANAGE_AUTO
OSCAR_RATE_MANAGE_MANUAL
GROUPPERM_OSCAR
GROUPPERM_AOL
TYPINGSTATUS_STARTED
TYPINGSTATUS_TYPING
TYPINGSTATUS_FINISHED

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::Utility", but I can’t think of any reason
why it would need to be used outside of the module internals.
"Net::OSCAR" provides the same functionality through the
"Net::OSCAR::Screenname" class.

· Different callbacks with different parameters.

MISCELLANEOUS INFO
There are two programs included with the "Net::OSCAR" distribution.
"oscartest" is half a reference implementation of a "Net::OSCAR"
client and half a tool for testing this library. "snacsnatcher" is a
tool designed for analyzing the OSCAR protocol from libpcap-format
packet captures, but it isn’t particularly well-maintained; the Ethe-
real sniffer does a good job at this nowadays.

There is a class "Net::OSCAR::Screenname". OSCAR screennames are case
and whitespace insensitive, and if you do something like "$buddy = new
Net::OSCAR::Screenname "Matt Sachs"" instead of "$buddy = "Matt
Sachs"", this will be taken care of for you when you use the string
comparison operators (eq, ne, cmp, etc.)

"Net::OSCAR::Connection", the class used for connection objects, has
some methods that may or may not be useful to you.

get_filehandle
Returns the filehandle used for the connection. Note that this is
a method of "Net::OSCAR::Connection", not "Net::OSCAR".

process_one (CAN_READ, CAN_WRITE, HAS_ERROR)
Call this when a "Net::OSCAR::Connection" is ready for reading
and/or writing. You might call this yourself instead of using
"process_connections" when, for instance, using the "connec-
tion_changed" callback in conjunction with "IO::Poll" instead of
"select". The "CAN_READ" and "CAN_WRITE" parameters should be
non-zero if the connection is ready for the respective operations
to be performed and zero otherwise. If and only if there was a
socket error with the connection, set "HAS_ERROR" to non-zero.

session
Returns the "Net::OSCAR" object associated with this
"Net::OSCAR::Connection".

USER INFORMATION
Methods which return information about a user, such as "buddy", will
return the information in the form of a hash. The keys of the hash
are the following -- note that any of these may be absent.

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. This is a "Net::OSCAR::Screenname"
object, so you don’t have to worry about the fact that it’s case
and whitespace insensitive when comparing it.

comment
A user-defined comment associated with the buddy. See
"set_buddy_comment". Note that this key will be present but unde-
fined if there is no comment.

alias
A user-defined alias for the buddy. See "set_buddy_alias". Note
that this key will be present but undefined if there is no alias.

extended_status
The user’s extended status message, if one is set, will be in this
key. This requires that you set the "extended_status" capability
when creating the "Net::OSCAR" object.

trial
The user’s account has trial status.

aol The user is accessing the AOL Instant Messenger service from Amer-
ica OnLine.

free
Opposite of aol.

away
The user is away.

admin
The user is an administrator.

mobile
The user is using a mobile device.

typing_status
The user is known to support typing status notification. We only
find this out if they send us an IM.

capabilities
The user’s capabilities. This is a reference to a hash whose keys
are the user’s capabilities, and whose values are descriptions of
their respective capabilities.

icon
The user’s buddy icon, if available.

icon_checksum
The checksum time of the user’s buddy icon, if available. Use
this, in conjunction with the icon_checksum method, to cache buddy
icons.

icon_timestamp
The modification timestamp of the user’s buddy icon, if available.

icon_length
The length of the user’s buddy icon, if available.

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_since
Time, in seconds since Jan 1st 1970, since which the user has been
idle. This will only be present if the user is idle. To figure
out how long the user has been idle for, subtract this value from
"time()" .

evil
Evil (warning) level for the user.

Some keys; namely, "typing_status" and "icon_checksum", may be avail-
able for people who the user has communicated with but who are not on
the user’s buddylist.

ICQ-SPECIFIC INFORMATION
ICQ support isn’t nearly as well-tested as AIM support, and ICQ-spe-
cific features aren’t being particularly actively developed. Patches
for ICQ-isms are welcome. The initial patch enabling us to sign on to
ICQ was provided by Sam Wong.

ICQ METHODS

get_icq_info (UIN)
Requests ICQ-specific information. See also the "buddy_icq_info"
callback.

ICQ CALLBACKS

buddy_icq_info (OSCAR, UIN, ICQ DATA)
The result of a "get_icq_info" call. Data is a hashref with the
following keys, the value of each key is a either a hashref or
undefined:

basic
nickname
firstname
lastname
email
gmt_offset
authorization
web_aware
direct_connect_permissions
publish_primary_email
home
city
state
phone_num
fax_num
address
cell_phone_num
zip_code
country_code
office
city
state
phone_num
fax_num
address
zip_code
country_code
company
department
position
occupation
office_website
background
age
gender
homepage
birth_year
birth_month
birth_day
spoken_languages
This key is a listref containing the langauges the user
speaks.

origin_city
origin_state
origin_country
marital_status
notes
This key is a simple scalar.

email_addresses
This key is a listref, each element of which is a hashref with
the following keys:

publish
address
interests
This key is a listref, each element of which is a hashref with
the following keys:

category
interest
past_affiliations
This key is a listref, each element of which is a hashref with
the following keys:

category
affiliation
present_affiliations
As per above.

homepage
category
keywords

HIGH-PERFORMANCE EVENT PROCESSING
A second 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 read-
ers, 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 $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.

The third way of doing connection processing uses the "connec-
tion_changed" callback in conjunction with "Net::OSCAR::Connection"’s
"process_one" method. This method, in conjunction with "IO::Poll",
probably offers the highest performance in situations where you have a
long-lived application which creates and destroys many "Net::OSCAR"
sessions; that is, an application whose list of file descriptors to
monitor will likely be sparse. However, this method is the most com-
plicated. What you need to do is call "IO::Poll::mask" inside of the
"connection_changed" callback. That part’s simple. The tricky bit is
figuring out which "Net::OSCAR::Connection::process_one"’s to call and
how to call them. My recommendation for doing this is to use a
hashmap whose keys are the file descriptors of everything you’re moni-
toring in the "IO::Poll" - the FDs can be retrieved by doing
"fileno($connection->get_filehandle)" inside of the "connec-
tion_changed" - and then calling "@handles = $poll->handles(POLLIN │
POLLOUT │ POLLERR │ POLLHUP)" and walking through the handles.

For optimum performance, use the "connection_changed" callback.

HISTORY
· 1.925, 2006-02-06

· Many buddylist performance enhancements and bug fixes.

· Added support for receiving dynamic buddylist changes from the
server ("callback_buddylist_changed".)

· Add support buddylist transfer ("set_callback_buddylist_in".)

· Miscellaneous performance and scalability enhancements.

· Added experimental migration support.

· Added advanced rate limit management API.

· Added "oscarserv" server for testing.

· Audited screennames exposed to application to verify that they
are "Net::OSCAR::Screenname" objects everywhere.

· Began work on file transfer.

· Connection status fix for compatibility with POE.

· 1.907, 2004-09-22

· Fixed assert failure on certain invalid input ("Buddy Trikill"
crash)

· 1.906, 2004-08-28

· Reorganized documentation

· 1.904, 2004-08-26

· Add $Net::OSCAR::XML::NO_XML_CACHE to prevent use of cached
XML parse tree, and skip tests if we can’t load Test::More or
XML::Parser.

· 1.903, 2004-08-26

· Generate XML parse tree at module build time so that users
don’t need to have XML::Parser and expat installed.

· 1.902, 2004-08-26

· Fixes to buddy icon upload and chat invitation decline

· Increase performance by doing lazy generation of certain
debugging info

· 1.901, 2004-08-24

· Lots of buddylist-handling bug fixes; should fix intermittent
buddylist modification errors and errors only seen when modi-
fying certain screennames; Roy C. rocks.

· We now require Perl 5.6.1.

· Workaround for bug in Perl pre-5.8.4 which manifested as a
"’basic OSCAR services’ isn’t numeric" warning followed by the
program freezing.

· "add_group" and "remove_group" methods added.

· Fixed a potential memory leak which could impact programs
which create many transient Net::OSCAR objects.

· 1.900, 2004-08-17

· Wrote new XML-based protocol back-end with reasonably compre-
hensive test-suite. Numerous protocol changes; we now emulate
AOL’s version 5.5 client.

· Rewrote snacsnatcher, an OSCAR protocol analysis tool

· Reorganized documentation

· ICQ meta-info support: get_icq_info method, buddy_icq_info
callback

· Stealth mode support: is_stealth and set_stealth methods,
stealth_changed callback, stealth signon key

· More flexible unknown SNAC handling: snac_unknown callback

· Application can give Net::OSCAR the MD5-hashed password
instead of the cleartext password (pass_is_hashed signon key).
This is useful if your application is storing user passwords.

· Inability to set blocking on Win32 is no longer fatal. Silly
platform.

· Fixed chat functionality.

· 1.11, 2004-02-13

· Fixed presence-related problems modifying some buddylists

· 1.10, 2004-02-10

· Fixed idle time handling; user info hashes now have an
’idle_since’ key, which you should use instead of the old
’idle’ key. Subtract "idle_since" from "time()" to get the
length of time for which the user has been idle.

· Fixed buddylist type 5 handling; this fixes problems modifying
the buddylists of recently-created screennames.

· 1.01, 2004-01-06

· Fixed buddy ID generation (problems adding buddies)

· 1.00, 2004-01-03

· Documented requirement to wait for buddylist_foo callback
between calls to commit_buddylist

· Fixed handling of idle time (zoyboy22)

· More flexible signon method

· Added buddy alias support

· Buddy icon support

· Typing notification support

· mac.com screenname support

· Support for communicating with ICQ users from AIM

· iChat extended status message support

· We now emulate AOL Instant Messenger for Windows 5.2

· We now parse the capabilities of other users

· Attempts at Win32 (non-cygwin) support

· 0.62, 2002-02-25

· Error handling slightly improved; error 29 is no longer
unknown.

· A minor internal buddylist enhancement

· snacsnatcher fixes

· 0.61, 2002-02-17

· Fixed connection handling

· 0.60, 2002-02-17

· Various connection_changed fixes, including the new readwrite
status.

· Added Net::OSCAR::Connection::session method

· Improved Net::OSCAR::Connection::process_one, documented it,
and documented using it

· 0.59, 2002-02-15

· Protocol fixes - solves problem with AOL calling us an unau-
thorized client

· Better handling of socket errors, especially when writing

· Minor POD fixes

· 0.58, 2002-01-20

· Send buddylist deletions before adds - needed for complex BL
mods (loadbuddies)

· Added hooks to allow client do MD5 digestion for authentica-
tion (auth_challenge callback, Net::OSCAR::auth_response
method)

· 0.57, 2002-01-16

· Send callback_chat_joined correctly when joining an existing
chat

· Don’t activate OldPerl fixes for perl 5.6.0

· Ignore chats that we’re already in

· 0.56, 2002-01-16

· Fixed rate handling

· Send multiple buddylist modifications per SNAC

· Detect when someone else signs on with your screenname

· Corrected attribution of ICQ support

· 0.55, 2001-12-29

· Preliminary ICQ support, courtesy of SDiZ Chen (actually, Sam
Wong).

· Restored support for pre-5.6 perls - reverted from
"IO::Socket" to "Socket".

· Corrected removal of buddylist entries and other buddylist-
handling improvements

· Improved rate handling - new "worrisome" parameter to
rate_alert callback

· Removed remaining "croak" from "OSCAR::Connection"

· Added is_on method

· 0.50, 2001-12-23

· Fixes for the "crap out on ’connection reset by peer’" and
"get stuck and slow down in Perl_sv_2bool" bugs!

· Correct handling of very large (over 100 items) buddylists.

· We can now join exchange 5 chats.

· Fixes in modifying permit mode.

· Updated copyright notice courtesy of AOL’s lawyers.

· Switch to IO::Socket for portability in set_blocking.

· 0.25, 2001-11-26

· Net::OSCAR is now in beta!

· We now work with perl 5.005 and even 5.004

· Try to prevent weird Net::OSCAR::Screenname bug where perl
gets stuck in Perl_sv_2bool

· Fixed problems with setting visibility mode and adding to deny
list (thanks, Philip)

· Added some methods to allow us to be POE-ified

· Added guards around a number of methods to prevent the user
from trying to do stuff before s/he’s finished signing on.

· Fix *incredibly* stupid error in NO_to_BLI that ate group
names

· Fixed bad bug in log_printf

· Buddylist error handling changes

· Added chat_decline command

· Signon, signoff fixes

· Allow AOL screennames to sign on

· flap_get crash fixes

· 0.09, 2001-10-01

· Crash and undefined value fixes

· New method: im_ok

· New method: rename_group, should fix "Couldn’t get group name"
error.

· Fix for buddy_in callback and data

· Better error handling when we can’t resolve a host

· Vastly improved logging infrastructure - debug_print(f)
replaced with log_print(f). debug_print callback is now called
log and has an extra parameter.

· Fixed MANIFEST - we don’t actually use Changes (and we do use
Screenname.pm)

· blinternal now automagically enforces the proper structure
(the right things become Net::OSCAR::TLV tied hashes and the
name and data keys are automatically created) upon
vivification. So, you can do
$bli->{0}->{1}->{2}->{data}->{0x3} = "foo" without worrying if
0, 1, 2, or data have been tied. Should close bug #47.

· 0.08, 2001-09-07

· Totally rewritten buddylist handling. It is now much cleaner,
bug-resistant, and featureful.

· Many, many internal changes that I don’t feel like enumerat-
ing. Hey, there’s a reason that I haven’t declared the inter-
face stable yet! ;)

· New convenience object: Net::OSCAR::Screenname

· Makefile.PL: Fixed perl version test and compatibility with
BSD make

· 0.07, 2001-08-13

· A bunch of Makefile.PL fixes

· Fixed spurious admin_error callback and prevent user from hav-
ing multiple pending requests of the same type. (closes #39)

· Head off some potential problems with set_visibility. (closes
#34)

· Removed connections method, added selector_filenos

· Added error number 29 (too many recent signons from your site)
to Net::OSCAR::Common.

· We now explicitly perl 5.6.0 or newer.

· 0.06, 2001-08-12

· Prevent sending duplicate signon_done messages

· Don’t addconn after crapping out!

· Don’t try to delconn unless we have connections.

· delete returns the correct value now in Net::OSCAR::Buddylist.

· Don’t use warnings if $] <= 5.005

· evil is a method, not a manpage (doc fix)

· Added buddyhash method.

· Added a debug_print callback.

· Clarified process_connections method in documentation

· You can now specify an alternate host/port in signon

· Added name method to Chat.

· permit list and deny list are no longer part of buddylist

· Rewrote buddylist parsing (again!)

· No more default profile.

· Fix bug when storing into an already-existing key in
Net::OSCAR::Buddylist.

· snacsnatcher: Remove spurious include of Net::OSCAR::Common

· We don’t need to handle VISMODE_PERMITBUDS ourself - the
server takes care of it. Thanks, VB!

· Makefile.PL: Lots of way cool enhancements to make dist:

- It modifies the version number for us

- It does a CVS rtag

- It updates the HTML documentation on zevils and the
README.

· Added HISTORY and INSTALLATION section to POD.

· 0.05, 2001-08-08

· Don’t send signon_done until after we get buddylist.

· Added signoff method.

· Fixed typo in documentation

· Fixed chat_invite parm count

· Added Scalar::Utils::dualvar variables, especially to Com-
mon.pm. dualvar variables return different values in numeric
and string context.

· Added url method for Net::OSCAR::Chat (closes #31)

· Divide evil by 10 in extract_userinfo (closes #30)

· chat_invite now exposes chatname (closes #32)

· Removed unnecessary and warning-generating session length from
extract_userinfo

· 0.01, 2001-08-02

· Initial release.

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
AOL, for creating the AOL Instant Messenger service, even though they
aren’t terribly helpful to developers of third-party clients.

Apple Computer for help with mac.com support.

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

Bill Atkins for typing status notification and mobile user support.
<http://www.milkbone.org/>

Jayson Baker for some last-minute debugging help.

Roy Camp for loads of bug reports and ideas and helping with user sup-
port.

Rocco Caputo for helping to work out the hooks that let use be used
with POE. <http://poe.perl.org/>

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

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/>

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

Nick Gray for sponsoring scalability work.

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

Jonathon Wodnicki for additional help with typing status notification.

Sam Wong <sam@uhome.net> for a patch implementing ICQ2000 support.

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 and AMERICA ONLINE are registered
trademarks owned by America Online, Inc. The INSTANT MESSENGER mark
is owned by America Online, Inc. ICQ is a trademark and/or service-
mark of ICQ. "Net::OSCAR" is not endorsed by, or affiliated with,
America Online, Inc or ICQ. iChat and Apple Computer are registered
trademarks of Apple Computer, Inc. "Net::OSCAR" is not endorsed by,
or affiliated with, Apple Computer, Inc or iChat.

perl v5.8.8 2007-10-23 Net::OSCAR(3)