.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::OSCAR 3"
.TH Net::OSCAR 3 "2010-10-07" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::OSCAR \- Implementation of AOL's OSCAR protocol for instant messaging (for interacting with AIM a.k.a. AOL IM a.k.a. AOL Instant Messenger \- and ICQ, too!)
.SH "VERSION"
.IX Header "VERSION"
version 1.928
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use Net::OSCAR qw(:standard);
\&
\&        sub im_in {
\&                my($oscar, $sender, $message, $is_away) = @_;
\&                print "[AWAY] " if $is_away;
\&                print "$sender: $message\en";
\&        }
\&
\&        $oscar = Net::OSCAR\->new();
\&        $oscar\->set_callback_im_in(\e&im_in);
\&        $oscar\->signon($screenname, $password);
\&        while(1) {
\&                $oscar\->do_one_loop();
\&                # Do stuff
\&        }
.Ve
.SH "INSTALLATION"
.IX Header "INSTALLATION"
.SS "\s-1HOW TO INSTALL\s0"
.IX Subsection "HOW TO INSTALL"
.Vb 4
\&        perl Build.PL
\&        perl Build
\&        perl Build test
\&        perl Build install
.Ve
.PP
See \f(CW\*(C`perldoc Module::Build\*(C'\fR for details.
Note that this requires that you have the perl module Module::Build installed.
If you don't, the traditional \f(CW\*(C`perl Makefile.PL ; make ; make test ; make install\*(C'\fR
should still work.
.SS "\s-1DEPENDENCIES\s0"
.IX Subsection "DEPENDENCIES"
This modules requires \f(CW\*(C`Digest::MD5\*(C'\fR and \f(CW\*(C`Scalar::Util\*(C'\fR.  \f(CW\*(C`Test::More\*(C'\fR is needed
to run the test suite, and \f(CW\*(C`XML::Parser\*(C'\fR is needed to generate the \s-1XML\s0 parse tree
which is shipped with released versions.
.SH "INTRODUCTION"
.IX Header "INTRODUCTION"
.SS "\s-1ABSTRACT\s0"
.IX Subsection "ABSTRACT"
\&\f(CW\*(C`Net::OSCAR\*(C'\fR implements the \s-1OSCAR\s0 protocol which is used by \s-1AOL\s0's \s-1AOL\s0 Instant
Messenger service.  To use the module, you create a \f(CW\*(C`Net::OSCAR\*(C'\fR 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.
.PP
You probably want to use the \f(CW\*(C`:standard\*(C'\fR parameter when importing this module
in order to have a few important constants added to your namespace.  See
\&\*(L"\s-1CONSTANTS\*(R"\s0 below for a list of the constants exported by the \f(CW\*(C`:standard\*(C'\fR tag.
.PP
No official documentation exists for the \s-1OSCAR\s0 protocol, so it had to be figured
out by analyzing traffic generated by \s-1AOL\s0's official \s-1AOL\s0 Instant Messenger client.
Source code from the Gaim client, the protocol analysis provided by the Ethereal
network sniffer, and the Alexander Shutko's website
<http://iserverd1.khstu.ru/oscar/> were also used as references.
.PP
This module strives to be as compatible with \f(CW\*(C`Net::AIM\*(C'\fR as possible at the \s-1API\s0 level, but some
protocol-level differences prevent total compatibility.  The \s-1TOC\s0 protocol implemented
by \f(CW\*(C`Net::AIM\*(C'\fR is simpler than \s-1OSCAR\s0 and has official reference documentation from \s-1AOL,\s0
but it only provides a small subset of the full \f(CW\*(C`OSCAR\*(C'\fR functionality.
See the section on \*(L"Net::AIM Compatibility\*(R" for more information.
.SS "\s-1EVENT PROCESSING OVERVIEW\s0"
.IX Subsection "EVENT PROCESSING OVERVIEW"
Event processing is the implementation of \f(CW\*(C`Net::OSCAR\*(C'\fR within the framework of your
program, so that your program can respond to things happening on the \s-1OSCAR\s0 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 \f(CW\*(C`select\*(C'\fR call on all the object's
sockets and reads incoming commands from the \s-1OSCAR\s0 server on any connections which
have them.  The \f(CW\*(C`select\*(C'\fR 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 \s-1OSCAR\s0 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 \*(L"HIGH-PERFORMANCE \s-1EVENT PROCESSING\*(R"\s0 below.
.SS "\s-1FUNCTIONALITY\s0"
.IX Subsection "FUNCTIONALITY"
\&\f(CW\*(C`Net::OSCAR\*(C'\fR pretends to be WinAIM 5.5.3595.  It supports remote buddylists
including permit and deny settings.  It also supports chat, buddy icons,
and extended status messages.  At the present time, setting and retrieving of
directory information is not supported; nor are email privacy settings,
voice chat, stock ticker, file transfer, direct \s-1IM,\s0 and many other of the
official \s-1AOL\s0 Instant Messenger client's features.
.SS "\s-1TERMINOLOGY\s0"
.IX Subsection "TERMINOLOGY"
When you sign on with the \s-1OSCAR\s0 service, you are establishing an \s-1OSCAR\s0 session.
.SS "\s-1CALLBACKS\s0"
.IX Subsection "CALLBACKS"
\&\f(CW\*(C`Net::OSCAR\*(C'\fR uses a callback mechanism to notify you about different events.
A callback is a function provided by you which \f(CW\*(C`Net::OSCAR\*(C'\fR will call
when a certain event occurs.  To register a callback, calling the \f(CW\*(C`set_callback_callbackname\*(C'\fR method
with a code reference as a parameter.  For instance, you might call
\&\f(CW\*(C`$oscar\->set_callback_error(\e&got_error);\*(C'\fR.  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 \f(CW\*(C`Net::OSCAR\*(C'\fR object which generated the callback.  This is useful
when using multiple \f(CW\*(C`Net::OSCAR\*(C'\fR objects.
.SH "REFERENCE"
.IX Header "REFERENCE"
.SS "\s-1BASIC FUNCTIONALITY\s0"
.IX Subsection "BASIC FUNCTIONALITY"
\fI\s-1METHODS\s0\fR
.IX Subsection "METHODS"
.IP "new ([capabilities => \s-1CAPABILITIES\s0], [rate_manage => \s-1RATE_MANAGE_MODE\s0])" 4
.IX Item "new ([capabilities => CAPABILITIES], [rate_manage => RATE_MANAGE_MODE])"
Creates a new \f(CW\*(C`Net::OSCAR\*(C'\fR object.  You may optionally
pass a hash to set some parameters for the object.
.RS 4
.IP "capabilities" 4
.IX Item "capabilities"
A listref of optional features that your client supports.
Valid capabilities are:
.RS 4
.IP "extended_status" 4
.IX Item "extended_status"
iChat-style extended status messages
.IP "buddy_icons" 4
.IX Item "buddy_icons"
.PD 0
.IP "file_transfer" 4
.IX Item "file_transfer"
.IP "file_sharing" 4
.IX Item "file_sharing"
.IP "typing_status" 4
.IX Item "typing_status"
.PD
Typing status notification
.IP "buddy_list_transfer" 4
.IX Item "buddy_list_transfer"
.RE
.RS 4
.RE
.PD 0
.IP "rate_manage" 4
.IX Item "rate_manage"
.PD
Which mechanism will your application be using to deal with
the sending rates which the server enforces on the client?
See \*(L"\s-1RATE LIMIT OVERVIEW\*(R"\s0 for more information on the subject.
.RS 4
.IP "\s-1OSCAR_RATE_MANAGE_NONE\s0" 4
.IX Item "OSCAR_RATE_MANAGE_NONE"
.PD 0
.IP "\s-1OSCAR_RATE_MANAGE_AUTO\s0" 4
.IX Item "OSCAR_RATE_MANAGE_AUTO"
.IP "\s-1OSCAR_RATE_MANAGE_MANUAL\s0" 4
.IX Item "OSCAR_RATE_MANAGE_MANUAL"
.RE
.RS 4
.RE
.RE
.RS 4
.PD
.Sp
.Vb 1
\&        $oscar = Net::OSCAR\->new(capabilities => [qw(extended_status typing_status)], rate_manage => OSCAR_RATE_MANAGE_AUTO);
.Ve
.RE
.IP "signon (\s-1HASH\s0)" 4
.IX Item "signon (HASH)"
.PD 0
.IP "signon (\s-1SCREENNAME,\s0 PASSWORD[, \s-1HOST, PORT\s0]" 4
.IX Item "signon (SCREENNAME, PASSWORD[, HOST, PORT]"
.PD
Sign on to the \s-1OSCAR\s0 service.  You can specify an
alternate host/port to connect to.  The default is
login.oscar.aol.com port 5190.
.Sp
The non-hash form of \f(CW\*(C`signon\*(C'\fR is obsolete and is only provided for compatibility with \f(CW\*(C`Net::AIM\*(C'\fR.
If you use a hash to pass parameters to this function, here are the valid keys:
.RS 4
.IP "screenname" 4
.IX Item "screenname"
.PD 0
.IP "password" 4
.IX Item "password"
.PD
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 \*(L"auth_challenge\*(R" for details.
.IP "stealth" 4
.IX Item "stealth"
Use this to sign on with stealth mode activated.  Using this, as opposed
to signon on without this setting and then calling \*(L"set_stealth\*(R", will prevent
the user from showing as online for a brief interval after signon.  See \*(L"set_stealth\*(R"
for information about stealth mode.
.IP "pass_is_hashed" 4
.IX Item "pass_is_hashed"
If you want to give Net::OSCAR the \s-1MD5\s0 hash of the password instead of the password
itself, use the \s-1MD5\s0'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.
.IP "local_ip" 4
.IX Item "local_ip"
If you have more than one \s-1IP\s0 address with a route to the internet, this
parameter can be used to specify which to use as the source \s-1IP\s0 for outgoing
connections.
.IP "local_port" 4
.IX Item "local_port"
This controls which port Net::OSCAR will listen on for incoming direct connections.
If not specified, a random port will be selected.
.IP "host" 4
.IX Item "host"
.PD 0
.IP "port" 4
.IX Item "port"
.IP "proxy_type" 4
.IX Item "proxy_type"
.PD
Either \*(L"\s-1SOCKS4\*(R", \*(L"SOCKS5\*(R", \*(L"HTTP\*(R",\s0 or \s-1HTTPS. \s0 This and \f(CW\*(C`proxy_host\*(C'\fR must be specified if you wish to use a proxy.
\&\f(CW\*(C`proxy_port\*(C'\fR, \f(CW\*(C`proxy_username\*(C'\fR, \f(CW\*(C`proxy_password\*(C'\fR are optional.  Note that proxy support
is considered experimental.  You will need to have the \f(CW\*(C`Net::SOCKS\*(C'\fR module installed for
\&\s-1SOCKS\s0 proxying or the \f(CW\*(C`LWP::UserAgent\*(C'\fR module installed for \s-1HTTP\s0 proxying.
.IP "proxy_host" 4
.IX Item "proxy_host"
.PD 0
.IP "proxy_port" 4
.IX Item "proxy_port"
.IP "proxy_username" 4
.IX Item "proxy_username"
.IP "proxy_password" 4
.IX Item "proxy_password"
.RE
.RS 4
.PD
.Sp
If the screenname is all-numeric, it will automatically be treated
as an \s-1ICQ UIN\s0 instead of an \s-1AIM\s0 screenname.
.RE
.IP "signoff" 4
.IX Item "signoff"
Sign off from the \s-1OSCAR\s0 service.
.PP
\fI\s-1CALLBACKS\s0\fR
.IX Subsection "CALLBACKS"
.IP "signon_done (\s-1OSCAR\s0)" 4
.IX Item "signon_done (OSCAR)"
Called when the user is completely signed on to the service.
.SS "\s-1BUDDIES AND BUDDYLISTS\s0"
.IX Subsection "BUDDIES AND BUDDYLISTS"
See also \*(L"\s-1OTHER USERS\*(R"\s0 for methods which pertain to any other user, regardless of
whether they're on the buddylist or not.
.PP
\fI\s-1METHODS\s0\fR
.IX Subsection "METHODS"
.IP "findbuddy (\s-1BUDDY\s0)" 4
.IX Item "findbuddy (BUDDY)"
In scalar context, returns the name of the group that \s-1BUDDY\s0 is in, or undef if
\&\s-1BUDDY\s0 could not be found in any group.  If \s-1BUDDY\s0 is in multiple
groups, will return the first one we find.
.Sp
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.)
.IP "commit_buddylist" 4
.IX Item "commit_buddylist"
Sends your modified buddylist to the \s-1OSCAR\s0 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 \fB\s-1MUST\s0\fR not call
it again until either the buddylist_ok or buddylist_error callbacks
are received.
.IP "rollback_buddylist" 4
.IX Item "rollback_buddylist"
Revert changes you've made to the buddylist, assuming you haven't called
\&\*(L"commit_buddylist\*(R" since making them.
.IP "reorder_groups (\s-1GROUPS\s0)" 4
.IX Item "reorder_groups (GROUPS)"
Changes the ordering of the groups in your buddylist.  Call \*(L"commit_buddylist\*(R" to
save the
new order on the \s-1OSCAR\s0 server.
.IP "reorder_buddies (\s-1GROUP, BUDDIES\s0)" 4
.IX Item "reorder_buddies (GROUP, BUDDIES)"
Changes the ordering of the buddies in a group on your buddylist.
Call \*(L"commit_buddylist\*(R" to save the new order on the \s-1OSCAR\s0 server.
.IP "rename_group (\s-1OLDNAME, NEWNAME\s0)" 4
.IX Item "rename_group (OLDNAME, NEWNAME)"
Renames a group.  Call \*(L"commit_buddylist\*(R" for the change to take effect.
.IP "add_buddy (\s-1GROUP, BUDDIES\s0)" 4
.IX Item "add_buddy (GROUP, BUDDIES)"
Adds buddies to the given group on your buddylist.  If the group does not exist,
it will be created.  Call \*(L"commit_buddylist\*(R" for the change to take effect.
.IP "remove_buddy (\s-1GROUP, BUDDIES\s0)" 4
.IX Item "remove_buddy (GROUP, BUDDIES)"
See add_buddy.
.IP "add_group (\s-1GROUP\s0)" 4
.IX Item "add_group (GROUP)"
Creates a new, empty group.  Call \*(L"commit_buddylist\*(R" for the change to take effect.
.IP "remove_group (\s-1GROUP\s0)" 4
.IX Item "remove_group (GROUP)"
See add_group.  Any buddies in the group will be removed from the group first.
.IP "groups" 4
.IX Item "groups"
Returns a list of groups in the user's buddylist.
.IP "buddies (\s-1GROUP\s0)" 4
.IX Item "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 \f(CW\*(C`Net::OSCAR::Screenname\*(C'\fR objects, so you don't have to
worry that they're case and whitespace insensitive when using them for comparison.
.IP "buddy (BUDDY[, \s-1GROUP\s0])" 4
.IX Item "buddy (BUDDY[, GROUP])"
Returns information about a buddy on the user's buddylist.  This information is
a hashref as per \*(L"\s-1USER INFORMATION\*(R"\s0 below.
.IP "set_buddy_comment (\s-1GROUP,\s0 BUDDY[, \s-1COMMENT\s0])" 4
.IX Item "set_buddy_comment (GROUP, BUDDY[, COMMENT])"
Set a brief comment about a buddy.  You must call \*(L"commit_buddylist\*(R" to save
the comment to the server.  If \s-1COMMENT\s0 is undefined, the comment is
deleted.
.IP "set_buddy_alias (\s-1GROUP,\s0 BUDDY[, \s-1ALIAS\s0])" 4
.IX Item "set_buddy_alias (GROUP, BUDDY[, ALIAS])"
Set an alias for a buddy.  You must call \*(L"commit_buddylist\*(R" to save
the comment to the server.  If \s-1ALIAS\s0 is undefined, the alias is
deleted.
.IP "buddylist_limits" 4
.IX Item "buddylist_limits"
Returns a hash containing the maximum number of buddylist entries
of various types.  The keys in the hash are:
.RS 4
.IP "\(bu" 4
buddies
.IP "\(bu" 4
groups
.IP "\(bu" 4
permits
.IP "\(bu" 4
denies
.RE
.RS 4
.Sp
So, the maximum number of buddies allowed on a buddylist is stored in the \f(CW\*(C`buddies\*(C'\fR key.
Please note that buddylist storage has some overhead, so the actual number of items you
can have on a buddylist may be slightly less than advertised.
.Sp
If the \s-1OSCAR\s0 server did not inform us of the limits, values of 0 will be used.
.RE
.PP
\fI\s-1CALLBACKS\s0\fR
.IX Subsection "CALLBACKS"
.IP "buddy_in (\s-1OSCAR, SCREENNAME, GROUP, BUDDY DATA\s0)" 4
.IX Item "buddy_in (OSCAR, SCREENNAME, GROUP, BUDDY DATA)"
\&\s-1SCREENNAME \s0(in buddy group \s-1GROUP\s0) has signed on, or their information has
changed.  \s-1BUDDY DATA\s0 is the same as that returned by the buddy method.
.IP "buddy_out (\s-1OSCAR, SCREENNAME, GROUP\s0)" 4
.IX Item "buddy_out (OSCAR, SCREENNAME, GROUP)"
Called when a buddy has signed off (or added us to their deny list.)
.IP "buddylist_error (\s-1OSCAR, ERROR, WHAT\s0)" 4
.IX Item "buddylist_error (OSCAR, ERROR, WHAT)"
This is called when there is an error commiting changes to the buddylist.
\&\f(CW\*(C`ERROR\*(C'\fR is the error number.  \f(CW\*(C`WHAT\*(C'\fR is a string describing which buddylist
change failed.  \f(CW\*(C`Net::OSCAR\*(C'\fR will revert the failed change to
its state before \f(CW\*(C`commit_buddylist\*(C'\fR was called.  Note that the
buddylist contains information other than the user's buddies \- see 
any method which says you need to call \f(CW\*(C`commit_buddylist\*(C'\fR to have its
changes take effect.
.IP "buddylist_ok (\s-1OSCAR\s0)" 4
.IX Item "buddylist_ok (OSCAR)"
This is called when your changes to the buddylist have been successfully commited.
.IP "buddylist_changed (\s-1OSCAR, CHANGES\s0)" 4
.IX Item "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.
.Sp
Currently, only changes to buddies and groups will be listed in \f(CW\*(C`CHANGES\*(C'\fR.
Changes to privacy settings and any other portions of the buddylist will
not be included in the list in the current version of \f(CW\*(C`Net::OSCAR\*(C'\fR.
.Sp
\&\f(CW\*(C`CHANGES\*(C'\fR is a list of hash references, one for each change to the buddylist,
with the following keys:
.RS 4
.IP "\(bu" 4
type: Either \f(CW\*(C`MODBL_WHAT_BUDDY\*(C'\fR or \f(CW\*(C`MODBL_WHAT_GROUP\*(C'\fR.  This indicates
if the change was to a buddy or a group.
.IP "\(bu" 4
action: Either \f(CW\*(C`MODBL_ACTION_DEL\*(C'\fR or \f(CW\*(C`MODBL_ACTION_ADD\*(C'\fR.  This indicates
whether the change was an addition/modification or a deletion.
.IP "\(bu" 4
group: The name of the group which the modification took place in.  For
\&\f(CW\*(C`MODBL_WHAT_BUDDY\*(C'\fR, this will be the name of the group which the
changed buddy was changed in; for \f(CW\*(C`MODBL_WHAT_GROUP\*(C'\fR, this will
be the name of the group which was changed.
.IP "\(bu" 4
buddy: This key is only present for \f(CW\*(C`MODBL_WHAT_BUDDY\*(C'\fR.  It's the name
of the buddy which was changed.
.RE
.RS 4
.Sp
The \f(CW\*(C`MODBL_*\*(C'\fR constants come from \f(CW\*(C`Net::OSCAR::Common\*(C'\fR, and
are included in the \f(CW\*(C`:standard\*(C'\fR export list.
.RE
.SS "\s-1PRIVACY\s0"
.IX Subsection "PRIVACY"
\&\f(CW\*(C`Net::OSCAR\*(C'\fR 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.
.PP
\fI\s-1METHODS\s0\fR
.IX Subsection "METHODS"
.IP "add_permit (\s-1BUDDIES\s0)" 4
.IX Item "add_permit (BUDDIES)"
Add buddies to your permit list.  Call \*(L"commit_buddylist\*(R" for the
change to take effect.
.IP "add_deny (\s-1BUDDIES\s0)" 4
.IX Item "add_deny (BUDDIES)"
See add_permit.
.IP "remove_permit (\s-1BUDDIES\s0)" 4
.IX Item "remove_permit (BUDDIES)"
See add_permit.
.IP "remove_deny (\s-1BUDDIES\s0)" 4
.IX Item "remove_deny (BUDDIES)"
See add_permit.
.IP "get_permitlist" 4
.IX Item "get_permitlist"
Returns a list of all members of the permit list.
.IP "get_denylist" 4
.IX Item "get_denylist"
Returns a list of all members of the deny list.
.IP "visibility" 4
.IX Item "visibility"
Returns the user's current visibility setting.  See set_visibility.
.IP "set_visibility (\s-1MODE\s0)" 4
.IX Item "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 feature 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 \*(L"is_stealth\*(R"/\*(L"set_stealth\*(R".
.Sp
The visibility mode may be:
.RS 4
.IP "\(bu" 4
\&\s-1VISMODE_PERMITALL:\s0 Permit everybody.
.IP "\(bu" 4
\&\s-1VISMODE_DENYALL:\s0 Deny everybody.
.IP "\(bu" 4
\&\s-1VISMODE_PERMITSOME:\s0 Permit only those on your permit list.
.IP "\(bu" 4
\&\s-1VISMODE_DENYSOME:\s0 Deny only those on your deny list.
.IP "\(bu" 4
\&\s-1VISMODE_PERMITBUDS:\s0 Same as \s-1VISMODE_PERMITSOME,\s0 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.
.RE
.RS 4
.Sp
These constants are contained in the \f(CW\*(C`Net::OSCAR::Common\*(C'\fR package,
and will be imported into your namespace if you import \f(CW\*(C`Net::OSCAR\*(C'\fR
with the \f(CW\*(C`:standard\*(C'\fR parameter.
.Sp
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.
.Sp
Call \*(L"commit_buddylist\*(R" for the change to take effect.
.RE
.IP "is_stealth" 4
.IX Item "is_stealth"
.PD 0
.IP "set_stealth \s-1STEALTH_STATUS\s0" 4
.IX Item "set_stealth STEALTH_STATUS"
.PD
These methods deal with \*(L"stealth mode\*(R".  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 \*(L"set_visibility\*(R"), 
on who can communicate with her will remain in effect.
.Sp
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,
\&\f(CW\*(C`is_stealth\*(C'\fR won't cut it; there's a \*(L"stealth_changed\*(R" callback which will serve
nicely.
.IP "set_group_permissions (\s-1NEWPERMS\s0)" 4
.IX Item "set_group_permissions (NEWPERMS)"
Set group permissions.  This lets you block any \s-1OSCAR\s0 users or any \s-1AOL\s0 users.
\&\f(CW\*(C`NEWPERMS\*(C'\fR should be a list of zero or more of the following constants:
.RS 4
.IP "\s-1GROUPPERM_OSCAR\s0" 4
.IX Item "GROUPPERM_OSCAR"
Permit \s-1AOL\s0 Instant Messenger users to contact you.
.IP "\s-1GROUPPERM_AOL\s0" 4
.IX Item "GROUPPERM_AOL"
Permit \s-1AOL\s0 subscribers to contact you.
.RE
.RS 4
.Sp
Call \*(L"commit_buddylist\*(R" for the change to take effect.
.RE
.IP "group_permissions" 4
.IX Item "group_permissions"
Returns current group permissions.  The return value is a list like the one
that \*(L"set_group_permissions\*(R" wants.
.SS "\s-1OTHER USERS\s0"
.IX Subsection "OTHER USERS"
See also \*(L"\s-1BUDDIES AND BUDDYLISTS\*(R"\s0.
.PP
\fI\s-1METHODS\s0\fR
.IX Subsection "METHODS"
.IP "get_info (\s-1WHO\s0)" 4
.IX Item "get_info (WHO)"
Requests a user's information, which includes their profile and idle time.
See the buddy_info callback for more information.
.IP "get_away (\s-1WHO\s0)" 4
.IX Item "get_away (WHO)"
Similar to get_info, except requests the user's away message instead of
their profile.
.IP "send_im (\s-1WHO,\s0 MESSAGE[, \s-1AWAY\s0])" 4
.IX Item "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 \s-1AWAY\s0 parameter a non-zero
value.  Note that \f(CW\*(C`Net::OSCAR\*(C'\fR 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.
.Sp
Returns a \*(L"request \s-1ID\*(R"\s0 that you can use in the \f(CW\*(C`im_ok\*(C'\fR callback to identify the message.
If the message was too long to send, returns zero.
.IP "send_typing_status (\s-1RECIPIENT, STATUS\s0)" 4
.IX Item "send_typing_status (RECIPIENT, STATUS)"
Send a typing status change to another user.  Send these messages
to implement typing status notification.  Valid values for \f(CW\*(C`STATUS\*(C'\fR are:
.RS 4
.IP "\(bu" 4
\&\s-1TYPINGSTATUS_STARTED:\s0 The user has started typing to the recipient.
This indicates that typing is actively taking place.
.IP "\(bu" 4
\&\s-1TYPINGSTATUS_TYPING:\s0 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.
.IP "\(bu" 4
\&\s-1TYPINGSTATUS_FINISHED:\s0 The user has finished typing to the recipient.
This should be sent when the user starts to compose a message, but
then erases all of the text in the message input area.
.RE
.RS 4
.RE
.IP "evil (WHO[, \s-1ANONYMOUSLY\s0])" 4
.IX Item "evil (WHO[, ANONYMOUSLY])"
\&\f(CW\*(C`Evils\*(C'\fR, or \f(CW\*(C`warns\*(C'\fR, 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.
.Sp
You can't always evil someone.  You can only do it when they do something
like send you an instant message.
.IP "get_icon (\s-1SCREENNAME, MD5SUM\s0)" 4
.IX Item "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
\&\f(CW\*(C`icon_checksum\*(C'\fR and \f(CW\*(C`icon_timestamp\*(C'\fR data, which are available
via the buddy method (even for people not on the user's buddy
list.)  The \s-1MD5\s0 checksum of a user's icon will be in the
\&\f(CW\*(C`icon_md5sum\*(C'\fR key returned by buddy.
.Sp
You should receive a buddy_icon_downloaded callback in
response to this method.
.PP
\fI\s-1CALLBACKS\s0\fR
.IX Subsection "CALLBACKS"
.IP "new_buddy_icon (\s-1OSCAR, SCREENNAME, BUDDY DATA\s0)" 4
.IX Item "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 \f(CW\*(C`icon_checksum\*(C'\fR available; \f(CW\*(C`icon_timestamp\*(C'\fR and \f(CW\*(C`icon_length\*(C'\fR
may not be.  Specifically, if \f(CW\*(C`Net::OSCAR\*(C'\fR found out about the buddy icon
through a buddy status update (the sort that triggers a buddy_in callback),
these data will \fBnot\fR be available; if \f(CW\*(C`Net::OSCAR\*(C'\fR found out about the
icon via an incoming \s-1IM\s0 from the person, these data \fBwill\fR be available.
.Sp
Upon receiving this callback, an application should use the \f(CW\*(C`icon_checksum\*(C'\fR
to search for the icon in its cache, and call get_icon if it can't find it.
If the \f(CW\*(C`icon_md5sum\*(C'\fR, 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.
.IP "buddy_icon_downloaded (\s-1OSCAR, SCREENNAME, ICONDATA\s0)" 4
.IX Item "buddy_icon_downloaded (OSCAR, SCREENNAME, ICONDATA)"
This is called when a user's buddy icon is successfully downloaded from the server.
.IP "typing_status (\s-1OSCAR, SCREENNAME, STATUS\s0)" 4
.IX Item "typing_status (OSCAR, SCREENNAME, STATUS)"
Called when someone has sent us a typing status notification message.
See send_typing_status for a description of the different statuses.
.IP "im_ok (\s-1OSCAR, TO, REQID\s0)" 4
.IX Item "im_ok (OSCAR, TO, REQID)"
Called when an \s-1IM\s0 to \f(CW\*(C`TO\*(C'\fR is successfully sent.
\&\s-1REQID\s0 is the request \s-1ID\s0 of the \s-1IM\s0 as returned by \f(CW\*(C`send_im\*(C'\fR.
.IP "im_in (\s-1OSCAR, FROM,\s0 MESSAGE[, \s-1AWAY\s0])" 4
.IX Item "im_in (OSCAR, FROM, MESSAGE[, AWAY])"
Called when someone sends you an instant message.  If the \s-1AWAY\s0 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.
.IP "buddylist_in (\s-1OSCAR, FROM, BUDDYLIST\s0)" 4
.IX Item "buddylist_in (OSCAR, FROM, BUDDYLIST)"
Called when someone sends you a buddylist.  You must set the \*(L"buddy_list_transfer\*(R"
capability for buddylists to be sent to you.  The buddylist will be a \f(CW\*(C`Net::OSCAR::Buddylist\*(C'\fR
hashref whose keys are the groups and whose values are listrefs of \f(CW\*(C`Net::OSCAR::Screenname\*(C'\fR
strings for the buddies in the group.
.IP "buddy_info (\s-1OSCAR, SCREENNAME, BUDDY DATA\s0)" 4
.IX Item "buddy_info (OSCAR, SCREENNAME, BUDDY DATA)"
Called in response to a get_info or get_away request.
\&\s-1BUDDY DATA\s0 is the same as that returned by the buddy method,
except that one of two additional keys, \f(CW\*(C`profile\*(C'\fR and \f(CW\*(C`awaymsg\*(C'\fR,
may be present.
.SS "\s-1THE\s0 SIGNED-ON \s-1USER\s0"
.IX Subsection "THE SIGNED-ON USER"
These methods deal with the user who is currently signed on using a particular
\&\f(CW\*(C`Net::OSCAR\*(C'\fR object.
.PP
\fI\s-1METHODS\s0\fR
.IX Subsection "METHODS"
.IP "email" 4
.IX Item "email"
Returns the email address currently assigned to the user's account.
.IP "screenname" 4
.IX Item "screenname"
Returns the user's current screenname, including all capitalization and spacing.
.IP "is_on" 4
.IX Item "is_on"
Returns true if the user is signed on to the \s-1OSCAR\s0 service.  Otherwise,
returns false.
.IP "profile" 4
.IX Item "profile"
Returns your current profile.
.IP "set_away (\s-1MESSAGE\s0)" 4
.IX Item "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 \*(L"get_away\*(R".
.IP "set_extended_status (\s-1MESSAGE\s0)" 4
.IX Item "set_extended_status (MESSAGE)"
Sets the user's extended status message.  This requires the
\&\f(CW\*(C`Net::OSCAR\*(C'\fR object to have been created with the \f(CW\*(C`extended_status\*(C'\fR
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 \*(L"get_info\*(R" to get another
user's extended status.
.IP "set_info (\s-1PROFILE\s0)" 4
.IX Item "set_info (PROFILE)"
Sets the user's profile.  Call \*(L"commit_buddylist\*(R" 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.)
.Sp
Note that Net::OSCAR stores the user's profile in the server-side buddylist, so
if \*(L"commit_buddylist\*(R" 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 \f(CW\*(C`PROTOCOL\*(C'\fR, included with the \f(CW\*(C`Net::OSCAR\*(C'\fR distribution,
for details of how we're storing this data.
.Sp
Use \*(L"get_info\*(R" to retrieve another user's profile.
.IP "set_icon (\s-1ICONDATA\s0)" 4
.IX Item "set_icon (ICONDATA)"
Sets the user's buddy icon.  The \f(CW\*(C`Net::OSCAR\*(C'\fR object must have been created
with the \f(CW\*(C`buddy_icons\*(C'\fR capability to use this.  \f(CW\*(C`ICONDATA\*(C'\fR must be less
than 4kb, should be 48x48 pixels, and should be \s-1BMP, GIF,\s0 or \s-1JPEG\s0 image data.
You must call commit_buddylist for this change to take effect.  If
\&\f(CW\*(C`ICONDATA\*(C'\fR is the empty string, the user's buddy icon will be removed.
.Sp
When reading the icon data from a file, make sure to call \f(CW\*(C`binmode\*(C'\fR
on the file handle.
.Sp
Note that if the user's buddy icon was previously set with Net::OSCAR,
enough data will be stored in the server-side buddylist 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.
.Sp
See the file \f(CW\*(C`PROTOCOL\*(C'\fR, included with the \f(CW\*(C`Net::OSCAR\*(C'\fR distribution,
for details of how we're storing this data.
.Sp
You should receive a buddy_icon_uploaded callback in response to this
method.
.Sp
Use \*(L"get_icon\*(R" to retrieve another user's icon.
.IP "change_password (\s-1CURRENT PASSWORD, NEW PASSWORD\s0)" 4
.IX Item "change_password (CURRENT PASSWORD, NEW PASSWORD)"
Changes the user's password.
.IP "confirm_account" 4
.IX Item "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 \f(CW\*(C`trial\*(C'\fR key in the information given when the user's
information is requested.
.IP "change_email (\s-1NEW EMAIL\s0)" 4
.IX Item "change_email (NEW EMAIL)"
Requests that the email address registered to the user's account be changed.
This causes the \s-1OSCAR\s0 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 \s-1OSCAR\s0 server so that it may email the account password if the
user forgets it.
.IP "format_screenname (\s-1NEW FORMAT\s0)" 4
.IX Item "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.
.IP "set_idle (\s-1TIME\s0)" 4
.IX Item "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 \s-1OSCAR\s0
server will automatically increment the user's idle time once you mark
the user as being idle.
.PP
\fI\s-1CALLBACKS\s0\fR
.IX Subsection "CALLBACKS"
.IP "admin_error (\s-1OSCAR, REQTYPE, ERROR, ERRURL\s0)" 4
.IX Item "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.  \s-1REQTYPE\s0 is a string describing the type of request which generated the error.
\&\s-1ERROR\s0 is an error message.  \s-1ERRURL\s0 is an http \s-1URL\s0 which the user may visit for more
information about the error.
.IP "admin_ok (\s-1OSCAR, REQTYPE\s0)" 4
.IX Item "admin_ok (OSCAR, REQTYPE)"
This is called when an administrative function succeeds.  See admin_error for more info.
.IP "buddy_icon_uploaded (\s-1OSCAR\s0)" 4
.IX Item "buddy_icon_uploaded (OSCAR)"
This is called when the user's buddy icon is successfully uploaded to the server.
.IP "stealth_changed (\s-1OSCAR, NEW_STEALTH_STATE\s0)" 4
.IX Item "stealth_changed (OSCAR, NEW_STEALTH_STATE)"
This is called when the user's stealth state changes.  See \*(L"is_stealth\*(R" and \*(L"set_stealth\*(R"
for information on stealth.
.IP "extended_status (\s-1OSCAR, STATUS\s0)" 4
.IX Item "extended_status (OSCAR, STATUS)"
Called when the user's extended status changes.  This will normally
be sent in response to a successful set_extended_status call.
.IP "evil (\s-1OSCAR,\s0 NEWEVIL[, \s-1FROM\s0])" 4
.IX Item "evil (OSCAR, NEWEVIL[, FROM])"
Called when your evil level changes.  \s-1NEWEVIL\s0 is your new evil level,
as a percentage (accurate to tenths of a percent.)  \s-1ENEMY\s0 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 \*(L"evil\*(R" method for
more information on evils.
.SS "\s-1FILE TRANSFER AND DIRECT CONNECTIONS\s0"
.IX Subsection "FILE TRANSFER AND DIRECT CONNECTIONS"
.IP "file_send \s-1SCREENNAME MESSAGE FILEREFS\s0" 4
.IX Item "file_send SCREENNAME MESSAGE FILEREFS"
\&\f(CW\*(C`FILEDATA\*(C'\fR can be undef to have Net::OSCAR read the file,
a file handle, or the data to send.
.SS "\s-1EVENT PROCESSING\s0"
.IX Subsection "EVENT PROCESSING"
\fI\s-1METHODS\s0\fR
.IX Subsection "METHODS"
.IP "do_one_loop" 4
.IX Item "do_one_loop"
Processes incoming data from our connections to the various
\&\s-1OSCAR\s0 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.
.IP "process_connections (\s-1READERSREF, WRITERSREF, ERRORSREF\s0)" 4
.IX Item "process_connections (READERSREF, WRITERSREF, ERRORSREF)"
Use this method when you want to implement your own \f(CW\*(C`select\*(C'\fR
statement for event processing instead of using \f(CW\*(C`Net::OSCAR\*(C'\fR'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 \f(CW\*(C`Net::OSCAR::Connection\*(C'\fR objects or which are
\&\f(CW\*(C`Net::OSCAR::Connection\*(C'\fR objects from a different \f(CW\*(C`Net::OSCAR\*(C'\fR
object.  It modifies its arguments so that its connections
are removed from the connection lists.  This makes it very
convenient for use with multiple \f(CW\*(C`Net::OSCAR\*(C'\fR objects or
use with a \f(CW\*(C`select\*(C'\fR\-based event loop that you are also
using for other purposes.
.Sp
See the selector_filenos method for a way to get the necessary
bit vectors to use in your \f(CW\*(C`select\*(C'\fR.
.PP
\fI\s-1CALLBACKS\s0\fR
.IX Subsection "CALLBACKS"
.IP "connection_changed (\s-1OSCAR, CONNECTION, STATUS\s0)" 4
.IX Item "connection_changed (OSCAR, CONNECTION, STATUS)"
Called when the status of a connection changes.  The status is \*(L"read\*(R" if we
should call \*(L"process_one\*(R" on the connection when \f(CW\*(C`select\*(C'\fR indicates that
the connection is ready for reading, \*(L"write\*(R" if we should call
\&\*(L"process_one\*(R" when the connection is ready for writing, \*(L"readwrite\*(R" if \*(L"process_one\*(R"
should be called in both cases, or \*(L"deleted\*(R" if the connection has been deleted.
.Sp
\&\f(CW\*(C`CONNECTION\*(C'\fR is a \f(CW\*(C`Net::OSCAR::Connection\*(C'\fR object.
.Sp
Users of this callback may also be interested in the \*(L"get_filehandle\*(R"
method of \f(CW\*(C`Net::OSCAR::Connection\*(C'\fR.
.SS "\s-1CHATS\s0"
.IX Subsection "CHATS"
\fI\s-1METHODS\s0\fR
.IX Subsection "METHODS"
.IP "chat_join (NAME[, \s-1EXCHANGE\s0])" 4
.IX Item "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 \*(L"chat_accept\*(R" method
for that.
.IP "chat_accept (\s-1CHATURL\s0)" 4
.IX Item "chat_accept (CHATURL)"
Use this to accept an invitation to join a chatroom.
.IP "chat_decline (\s-1CHATURL\s0)" 4
.IX Item "chat_decline (CHATURL)"
Use this to decline an invitation to join a chatroom.
.PP
\fI\s-1CALLBACKS\s0\fR
.IX Subsection "CALLBACKS"
.IP "chat_buddy_in (\s-1OSCAR, SCREENNAME, CHAT, BUDDY DATA\s0)" 4
.IX Item "chat_buddy_in (OSCAR, SCREENNAME, CHAT, BUDDY DATA)"
\&\s-1SCREENNAME\s0 has entered \s-1CHAT.  BUDDY DATA\s0 is the same as that returned by
the buddy method.
.IP "chat_buddy_out (\s-1OSCAR, SCREENNAME, CHAT\s0)" 4
.IX Item "chat_buddy_out (OSCAR, SCREENNAME, CHAT)"
Called when someone leaves a chatroom.
.IP "chat_im_in (\s-1OSCAR, FROM, CHAT, MESSAGE\s0)" 4
.IX Item "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
\&\s-1NOREFLECT\s0 parameter in chat_send.
.IP "chat_invite (\s-1OSCAR, WHO, MESSAGE, CHAT, CHATURL\s0)" 4
.IX Item "chat_invite (OSCAR, WHO, MESSAGE, CHAT, CHATURL)"
Called when someone invites us into a chatroom.  \s-1MESSAGE\s0 is the message
that they specified on the invitation.  \s-1CHAT\s0 is the name of the chatroom.
\&\s-1CHATURL\s0 is a chat \s-1URL\s0 and not a \f(CW\*(C`Net::OSCAR::Connection::Chat\*(C'\fR object.  \s-1CHATURL\s0 can
be passed to the chat_accept method to accept the invitation.
.IP "chat_joined (\s-1OSCAR, CHATNAME, CHAT\s0)" 4
.IX Item "chat_joined (OSCAR, CHATNAME, CHAT)"
Called when you enter a chatroom.  \s-1CHAT\s0 is the \f(CW\*(C`Net::OSCAR::Connection::Chat\*(C'\fR
object for the chatroom.
.IP "chat_closed (\s-1OSCAR, CHAT, ERROR\s0)" 4
.IX Item "chat_closed (OSCAR, CHAT, ERROR)"
Your connection to \s-1CHAT \s0(a \f(CW\*(C`Net::OSCAR::Connection::Chat\*(C'\fR object) was severed due to \s-1ERROR.\s0
.SS "\s-1RATE LIMITS\s0"
.IX Subsection "RATE LIMITS"
See \*(L"\s-1RATE LIMIT OVERVIEW\*(R"\s0 for more information on rate limits.
.PP
\fI\s-1METHODS\s0\fR
.IX Subsection "METHODS"
.IP "rate_level (\s-1OSCAR,\s0 METHODNAME[, \s-1CHAT\s0])" 4
.IX Item "rate_level (OSCAR, METHODNAME[, CHAT])"
Returns the rate level (one of \f(CW\*(C`RATE_CLEAR\*(C'\fR, \f(CW\*(C`RATE_ALERT\*(C'\fR, \f(CW\*(C`RATE_LIMIT\*(C'\fR, \f(CW\*(C`RATE_DISCONNECT\*(C'\fR)
which the \s-1OSCAR\s0 session is currently at for the \f(CW\*(C`Net::OSCAR\*(C'\fR (or \f(CW\*(C`Net::OSCAR::Connection::Chat\*(C'\fR) method named
\&\f(CW\*(C`METHODNAME\*(C'\fR right now.  This only makes sense for methods which send information to the \s-1OSCAR\s0
server, such as \f(CW\*(C`send_im\*(C'\fR, but if you pass in a method name which doesn't make sense (or isn't
actually a \f(CW\*(C`Net::OSCAR\*(C'\fR method, or which isn't rate-limited), we'll gladly an empty list.  \fBThis method is
not available if your application is using \*(L"\s-1OSCAR_RATE_MANAGE_NONE\*(R"\s0.\fR
.Sp
If \f(CW\*(C`METHODNAME\*(C'\fR is \f(CW\*(C`chat_send\*(C'\fR, you should also pass the \f(CW\*(C`Net::OSCAR::Connection::Chat\*(C'\fR
object to get rate information on (as the \f(CW\*(C`CHAT\*(C'\fR parameter.)
.IP "rate_limits (\s-1OSCAR,\s0 METHODNAME[, \s-1CHAT\s0])" 4
.IX Item "rate_limits (OSCAR, METHODNAME[, CHAT])"
Similar to \*(L"rate_level\*(R".  This returns the boundaries of the different 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):
.RS 4
.IP "window_size" 4
.IX Item "window_size"
.PD 0
.IP "levels" 4
.IX Item "levels"
.PD
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.
.RS 4
.IP "clear" 4
.IX Item "clear"
.PD 0
.IP "alert" 4
.IX Item "alert"
.IP "limit" 4
.IX Item "limit"
.IP "disconnect" 4
.IX Item "disconnect"
.RE
.RS 4
.RE
.IP "last_time" 4
.IX Item "last_time"
.PD
The time at which the last command to affect this rate level was sent.
.IP "current_state" 4
.IX Item "current_state"
The session's current rate level.
.RE
.RS 4
.Sp
Every time a command is sent to the \s-1OSCAR\s0 server, the level is recalculated according to the formula
(from Alexandr Shutko's \s-1OSCAR\s0 documentation, <http://iserverd.khstu.ru/oscar/>:
.Sp
.Vb 1
\&        NewLevel = (Window \- 1)/Window * OldLevel + 1/Window * CurrentTimeDiff
.Ve
.Sp
\&\f(CW\*(C`CurrentTimeDiff\*(C'\fR is the difference between the current system time and \f(CW\*(C`last_time\*(C'\fR.
.RE
.IP "would_make_rate_level (\s-1OSCAR,\s0 METHODNAME[, \s-1CHAT\s0])" 4
.IX Item "would_make_rate_level (OSCAR, METHODNAME[, CHAT])"
Returns the rate level which your session would be at if \f(CW\*(C`METHODNAME\*(C'\fR were sent right now.
See \*(L"rate_level\*(R" for more information.
.PP
\fI\s-1CALLBACKS\s0\fR
.IX Subsection "CALLBACKS"
.IP "rate_alert (\s-1OSCAR, LEVEL, CLEAR, WINDOW, WORRISOME, VIRTUAL\s0)" 4
.IX Item "rate_alert (OSCAR, LEVEL, CLEAR, WINDOW, WORRISOME, VIRTUAL)"
This is called when you are sending commands to \s-1OSCAR\s0 too quickly.
.Sp
\&\f(CW\*(C`LEVEL\*(C'\fR is one of \f(CW\*(C`RATE_CLEAR\*(C'\fR, \f(CW\*(C`RATE_ALERT\*(C'\fR, \f(CW\*(C`RATE_LIMIT\*(C'\fR, or \f(CW\*(C`RATE_DISCONNECT\*(C'\fR from the \f(CW\*(C`Net::OSCAR::Common\*(C'\fR
package (they are imported into your namespace if you import \f(CW\*(C`Net::OSCAR\*(C'\fR with the \f(CW\*(C`:standard\*(C'\fR
parameter.)  \f(CW\*(C`RATE_CLEAR\*(C'\fR means that you're okay.  \f(CW\*(C`RATE_ALERT\*(C'\fR means you should slow down.  \f(CW\*(C`RATE_LIMIT\*(C'\fR
means that the server is ignoring messages from you until you slow down.  \f(CW\*(C`RATE_DISCONNECT\*(C'\fR means you're
about to be disconnected.
.Sp
\&\f(CW\*(C`CLEAR\*(C'\fR and \f(CW\*(C`WINDOW\*(C'\fR tell you the maximum speed you can send in order to maintain \f(CW\*(C`RATE_CLEAR\*(C'\fR standing.
You must send no more than \f(CW\*(C`WINDOW\*(C'\fR commands in \f(CW\*(C`CLEAR\*(C'\fR milliseconds.  If you just want to keep it
simple, you can just not send any commands for \f(CW\*(C`CLEAR\*(C'\fR milliseconds and you'll be fine.
.Sp
\&\f(CW\*(C`WORRISOME\*(C'\fR is nonzero if \f(CW\*(C`Net::OSCAR\*(C'\fR 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.
.Sp
A \f(CW\*(C`VIRTUAL\*(C'\fR 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.
.SS "\s-1MISCELLANEOUS\s0"
.IX Subsection "MISCELLANEOUS"
\fI\s-1METHODS\s0\fR
.IX Subsection "METHODS"
.IP "timeout ([\s-1NEW TIMEOUT\s0])" 4
.IX Item "timeout ([NEW TIMEOUT])"
Gets or sets the timeout value used by the do_one_loop method.
The default timeout is 0.01 seconds.
.IP "loglevel ([LOGLEVEL[, \s-1SCREENNAME DEBUG\s0]])" 4
.IX Item "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 \*(L"log\*(R" 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 \s-1OSCAR\s0 session which is generating
the message (but only if you don't have a \*(L"log\*(R" callback defined).  This is useful when you have multiple \f(CW\*(C`Net::OSCAR\*(C'\fR objects.
.Sp
See the \*(L"log\*(R" callback for more information.
.IP "auth_response (MD5_DIGEST[, \s-1PASS_IS_HASHED\s0])" 4
.IX Item "auth_response (MD5_DIGEST[, PASS_IS_HASHED])"
Provide a response to an authentication challenge \- see the \*(L"auth_challenge\*(R"
callback for details.
.IP "clone" 4
.IX Item "clone"
Clones the object.  This creates a new \f(CW\*(C`Net::OSCAR\*(C'\fR object whose callbacks,
loglevel, screenname debugging, and timeout are the same as those of the
current object.  This is provided as a convenience when using multiple
\&\f(CW\*(C`Net::OSCAR\*(C'\fR objects in order to allow you to set those parameters once
and then call the signon method on the object returned by clone.
.IP "buddyhash" 4
.IX Item "buddyhash"
Returns a reference to a tied hash which automatically normalizes its keys upon a fetch.
Use this for hashes whose keys are \s-1AIM\s0 screennames since \s-1AIM\s0 screennames with different
capitalization and spacing are considered equivalent.
.Sp
The keys of the hash as returned by the \f(CW\*(C`keys\*(C'\fR and \f(CW\*(C`each\*(C'\fR functions will be
\&\f(CW\*(C`Net::OSCAR::Screenname\*(C'\fR objects, so you they will automagically be compared
without regards to case and whitespace.
.IP "findconn (\s-1FILENO\s0)" 4
.IX Item "findconn (FILENO)"
Finds the connection that is using the specified file number, or undef
if the connection could not be found.  Returns a \f(CW\*(C`Net::OSCAR::Connection\*(C'\fR
object.
.IP "selector_filenos" 4
.IX Item "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 \*(L"process_connections\*(R" method for details.
.IP "icon_checksum (\s-1ICONDATA\s0)" 4
.IX Item "icon_checksum (ICONDATA)"
Returns a checksum of the buddy icon.  Use this in conjunction with the
\&\f(CW\*(C`icon_checksum\*(C'\fR buddy info key to cache buddy icons.
.IP "get_app_data ([GROUP[, \s-1BUDDY\s0]])" 4
.IX Item "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 \f(CW\*(C`libfaim\-aim\-protocol@lists.sourceforge.net\*(C'\fR list.
If you wish to set application-specific data, you should reserve a high-order
byte for your application by emailing \f(CW\*(C`libfaim\-aim\-protocol@lists.sourceforge.net\*(C'\fR.
This data is stored in your server-side buddylist and so will be persistent,
even across machines.
.Sp
If \f(CW\*(C`GROUP\*(C'\fR is present, a hashref for accessing data specific to that group
is returned.
.Sp
If \f(CW\*(C`BUDDY\*(C'\fR is present, a hashref for accessing data specific to that buddy
is returned.
.Sp
Call \*(L"commit_buddylist\*(R" to have the new data saved on the \s-1OSCAR\s0 server.
.IP "chat_invite (\s-1CHAT, MESSAGE, WHO\s0)" 4
.IX Item "chat_invite (CHAT, MESSAGE, WHO)"
Deprecated.  Provided for compatibility with \f(CW\*(C`Net::AIM\*(C'\fR.
Use the appropriate method of the \f(CW\*(C`Net::OSCAR::Connection::Chat\*(C'\fR object
instead.
.IP "chat_leave (\s-1CHAT\s0)" 4
.IX Item "chat_leave (CHAT)"
Deprecated.  Provided for compatibility with \f(CW\*(C`Net::AIM\*(C'\fR.
Use the appropriate method of the \f(CW\*(C`Net::OSCAR::Connection::Chat\*(C'\fR object
instead.
.IP "chat_send (\s-1CHAT, MESSAGE\s0)" 4
.IX Item "chat_send (CHAT, MESSAGE)"
Deprecated.  Provided for compatibility with \f(CW\*(C`Net::AIM\*(C'\fR.
Use the appropriate method of the \f(CW\*(C`Net::OSCAR::Connection::Chat\*(C'\fR object
instead.
.PP
\fI\s-1CALLBACKS\s0\fR
.IX Subsection "CALLBACKS"
.IP "auth_challenge (\s-1OSCAR, CHALLENGE, HASHSTR\s0)" 4
.IX Item "auth_challenge (OSCAR, CHALLENGE, HASHSTR)"
\&\fBNew for Net::OSCAR 2.0\fR: \s-1AOL\s0 Instant Messenger has changed their encryption
mechanisms; instead of using the password in the hash, you \fBmay\fR now use
the \s-1MD5\s0 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 \f(CW\*(C`auth_response\*(C'\fR indicating that you are
using the new encryption scheme.  See below for an example.
.Sp
\&\s-1OSCAR\s0 uses an MD5\-based challenge/response system for authentication so that the
password is never sent in plaintext over the network.  When a user wishes to sign on,
the \s-1OSCAR\s0 server sends an arbitrary number as a challenge.  The client must respond
with the \s-1MD5\s0 digest of the concatenation of, in this order, the challenge, the password,
and an additional hashing string (currently always the string
\&\*(L"\s-1AOL\s0 Instant Messenger (\s-1SM\s0)\*(R", but it is possible that this might change in the future.)
.Sp
If password is undefined in \*(L"signon\*(R", this callback will be triggered when the
server sends a challenge during the signon process.  The client must reply with 
the \s-1MD5\s0 digest of \s-1CHALLENGE . MD5\s0(password) . \s-1HASHSTR. \s0 For instance, using the
MD5::Digest module:
.Sp
.Vb 6
\&        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);
.Ve
.Sp
Note that this functionality is only available for certain services.  It is
available for \s-1AIM\s0 but not \s-1ICQ. \s0 Note also that the \s-1MD5\s0 digest must be in binary
form, not the more common hex or base64 forms.
.IP "log (\s-1OSCAR, LEVEL, MESSAGE\s0)" 4
.IX Item "log (OSCAR, LEVEL, MESSAGE)"
Use this callback if you don't want the log_print methods to just print to \s-1STDERR.\s0
It is called when even \f(CW\*(C`MESSAGE\*(C'\fR of level \f(CW\*(C`LEVEL\*(C'\fR is called.  The levels are,
in order of increasing importance:
.RS 4
.IP "\s-1OSCAR_DBG_NONE\s0" 4
.IX Item "OSCAR_DBG_NONE"
Really only useful for setting in the \*(L"loglevel\*(R" method.  No information will
be logged.  The default loglevel.
.IP "\s-1OSCAR_DBG_PACKETS\s0" 4
.IX Item "OSCAR_DBG_PACKETS"
Hex dumps of all incoming/outgoing packets.
.IP "\s-1OSCAR_DBG_DEBUG\s0" 4
.IX Item "OSCAR_DBG_DEBUG"
Information useful for debugging \f(CW\*(C`Net::OSCAR\*(C'\fR, and precious little else.
.IP "\s-1OSCAR_DBG_SIGNON\s0" 4
.IX Item "OSCAR_DBG_SIGNON"
Like \f(CW\*(C`OSCAR_DBG_NOTICE\*(C'\fR, 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 information during signon.  This may be deprecated
some-day and be replaced by a more flexible facility/level system, ala syslog.
.IP "\s-1OSCAR_DBG_NOTICE\s0" 4
.IX Item "OSCAR_DBG_NOTICE"
.PD 0
.IP "\s-1OSCAR_DBG_INFO\s0" 4
.IX Item "OSCAR_DBG_INFO"
.IP "\s-1OSCAR_DBG_WARN\s0" 4
.IX Item "OSCAR_DBG_WARN"
.RE
.RS 4
.PD
.Sp
Note that these symbols are imported into your namespace if and only if you use
the \f(CW\*(C`:loglevels\*(C'\fR or \f(CW\*(C`:all\*(C'\fR tags when importing the module (e.g. \f(CW\*(C`use Net::OSCAR qw(:standard :loglevels)\*(C'\fR.)
.Sp
Also note that this callback is only triggered for events whose level is greater
than or equal to the loglevel for the \s-1OSCAR\s0 session.  The \*(L"loglevel\*(R" method
allows you to get or set the loglevel.
.RE
.SS "\s-1ERROR HANDLING\s0"
.IX Subsection "ERROR HANDLING"
\fI\s-1CALLBACKS\s0\fR
.IX Subsection "CALLBACKS"
.IP "error (\s-1OSCAR, CONNECTION, ERROR, DESCRIPTION, FATAL\s0)" 4
.IX Item "error (OSCAR, CONNECTION, ERROR, DESCRIPTION, FATAL)"
Called when any sort of error occurs (except see admin_error below and
buddylist_error in \*(L"\s-1BUDDIES AND BUDDYLISTS\*(R"\s0.)
.Sp
\&\f(CW\*(C`CONNECTION\*(C'\fR is the particular connection which generated the error \- the \f(CW\*(C`log_print\*(C'\fR method of
\&\f(CW\*(C`Net::OSCAR::Connection\*(C'\fR may be useful, as may be getting \f(CW\*(C`$connection\->{description}\*(C'\fR.
\&\f(CW\*(C`DESCRIPTION\*(C'\fR is a nicely formatted description of the error.  \f(CW\*(C`ERROR\*(C'\fR is an error number.
.Sp
If \f(CW\*(C`FATAL\*(C'\fR is non-zero, the error was fatal and the connection to \s-1OSCAR\s0 has been
closed.
.IP "snac_unknown (\s-1OSCAR, CONNECTION, SNAC, DATA\s0)" 4
.IX Item "snac_unknown (OSCAR, CONNECTION, SNAC, DATA)"
Called when Net::OSCAR receives a message from the \s-1OSCAR\s0 server which
it doesn't known how to handle.  The default handler for this callback
will print out the unknown \s-1SNAC.\s0
.Sp
\&\f(CW\*(C`CONNECTION\*(C'\fR is the \f(CW\*(C`Net::OSCAR::Connection\*(C'\fR object on which the unknkown
message was received.  \f(CW\*(C`SNAC\*(C'\fR is a hashref with keys such as \f(CW\*(C`family\*(C'\fR, \f(CW\*(C`subtype\*(C'\fR, \f(CW\*(C`flags1\*(C'\fR, and
\&\f(CW\*(C`flags2\*(C'\fR.
.SH "CHAT CONNECTIONS"
.IX Header "CHAT CONNECTIONS"
Aside from the methods listed here, there are a couple of methods of the
\&\f(CW\*(C`Net::OSCAR::Connection::Chat\*(C'\fR object that are important for implementing chat
functionality.  \f(CW\*(C`Net::OSCAR::Connection::Chat\*(C'\fR is a descendent of \f(CW\*(C`Net::OSCAR::Connection\*(C'\fR.
.IP "invite (\s-1WHO, MESSAGE\s0)" 4
.IX Item "invite (WHO, MESSAGE)"
Invite somebody into the chatroom.
.IP "chat_send (MESSAGE[, NOREFLECT[, \s-1AWAY\s0]])" 4
.IX Item "chat_send (MESSAGE[, NOREFLECT[, AWAY]])"
Sends a message to the chatroom.  If the \s-1NOREFLECT\s0 parameter is
present, you will not receive the message as an incoming message
from the chatroom.  If \s-1AWAY\s0 is present, the message was generated
as an automatic reply, perhaps because you have an away message set.
.IP "part" 4
.IX Item "part"
Leave the chatroom.
.IP "url" 4
.IX Item "url"
Returns the \s-1URL\s0 for the chatroom.  Use this to associate a chat invitation
with the chat_joined that \f(CW\*(C`Net::OSCAR\*(C'\fR sends when you've join the chatroom.
.IP "name" 4
.IX Item "name"
Returns the name of the chatroom.
.IP "exchange" 4
.IX Item "exchange"
Returns the exchange of the chatroom.
This is normally 4 but can be 5 for certain chatrooms.
.SH "RATE LIMIT OVERVIEW"
.IX Header "RATE LIMIT OVERVIEW"
The \s-1OSCAR\s0 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 application exceeds these limits, the \s-1OSCAR\s0 server may start ignoring it or
may even disconnect your session.
.PP
See also the reference section on rate limits.
.SS "\s-1RATE MANAGEMENT MODES\s0"
.IX Subsection "RATE MANAGEMENT MODES"
\&\f(CW\*(C`Net::OSCAR\*(C'\fR supports three different schemes for managing these limits.  Pass the
scheme you want to use as the value of the \f(CW\*(C`rate_manage\*(C'\fR key when you invoke the
\&\*(L"new\*(R" method.
.PP
\fI\s-1OSCAR_RATE_MANAGE_NONE\s0\fR
.IX Subsection "OSCAR_RATE_MANAGE_NONE"
.PP
The default.  \f(CW\*(C`Net::OSCAR\*(C'\fR will not keep track of what the limits are,
much less how close you're coming to reaching them.  If the \s-1OSCAR\s0 server complains
that you are sending too fast, your \*(L"rate_alert\*(R" callback will be triggered.
.PP
\fI\s-1OSCAR_RATE_MANAGE_AUTO\s0\fR
.IX Subsection "OSCAR_RATE_MANAGE_AUTO"
.PP
In this mode, \f(CW\*(C`Net::OSCAR\*(C'\fR will prevent your application from exceeding 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 notified when this happens via the \*(L"rate_alert\*(R"
callback.  \fBThis mode is only available if your application implements \f(CB\*(C`Net::OSCAR\*(C'\fB's
time-delayed event system.\fR
.PP
\fI\s-1OSCAR_RATE_MANAGE_MANUAL\s0\fR
.IX Subsection "OSCAR_RATE_MANAGE_MANUAL"
.PP
In this mode, \f(CW\*(C`Net::OSCAR\*(C'\fR 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
\&\*(L"rate_level\*(R", \*(L"rate_limits\*(R", and \*(L"would_make_rate_level\*(R" methods to
control its own rate.
.SH "TIME-DELAYED EVENTS"
.IX Header "TIME-DELAYED EVENTS"
.SH "CONSTANTS"
.IX Header "CONSTANTS"
The following constants are defined when \f(CW\*(C`Net::OSCAR\*(C'\fR is imported with the
\&\f(CW\*(C`:standard\*(C'\fR 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.)
.IP "\s-1ADMIN_TYPE_PASSWORD_CHANGE\s0" 4
.IX Item "ADMIN_TYPE_PASSWORD_CHANGE"
.PD 0
.IP "\s-1ADMIN_TYPE_EMAIL_CHANGE\s0" 4
.IX Item "ADMIN_TYPE_EMAIL_CHANGE"
.IP "\s-1ADMIN_TYPE_SCREENNAME_FORMAT\s0" 4
.IX Item "ADMIN_TYPE_SCREENNAME_FORMAT"
.IP "\s-1ADMIN_TYPE_ACCOUNT_CONFIRM\s0" 4
.IX Item "ADMIN_TYPE_ACCOUNT_CONFIRM"
.IP "\s-1ADMIN_ERROR_UNKNOWN\s0" 4
.IX Item "ADMIN_ERROR_UNKNOWN"
.IP "\s-1ADMIN_ERROR_BADPASS\s0" 4
.IX Item "ADMIN_ERROR_BADPASS"
.IP "\s-1ADMIN_ERROR_BADINPUT\s0" 4
.IX Item "ADMIN_ERROR_BADINPUT"
.IP "\s-1ADMIN_ERROR_BADLENGTH\s0" 4
.IX Item "ADMIN_ERROR_BADLENGTH"
.IP "\s-1ADMIN_ERROR_TRYLATER\s0" 4
.IX Item "ADMIN_ERROR_TRYLATER"
.IP "\s-1ADMIN_ERROR_REQPENDING\s0" 4
.IX Item "ADMIN_ERROR_REQPENDING"
.IP "\s-1ADMIN_ERROR_CONNREF\s0" 4
.IX Item "ADMIN_ERROR_CONNREF"
.IP "\s-1VISMODE_PERMITALL\s0" 4
.IX Item "VISMODE_PERMITALL"
.IP "\s-1VISMODE_DENYALL\s0" 4
.IX Item "VISMODE_DENYALL"
.IP "\s-1VISMODE_PERMITSOME\s0" 4
.IX Item "VISMODE_PERMITSOME"
.IP "\s-1VISMODE_DENYSOME\s0" 4
.IX Item "VISMODE_DENYSOME"
.IP "\s-1VISMODE_PERMITBUDS\s0" 4
.IX Item "VISMODE_PERMITBUDS"
.IP "\s-1RATE_CLEAR\s0" 4
.IX Item "RATE_CLEAR"
.IP "\s-1RATE_ALERT\s0" 4
.IX Item "RATE_ALERT"
.IP "\s-1RATE_LIMIT\s0" 4
.IX Item "RATE_LIMIT"
.IP "\s-1RATE_DISCONNECT\s0" 4
.IX Item "RATE_DISCONNECT"
.IP "\s-1OSCAR_RATE_MANAGE_NONE\s0" 4
.IX Item "OSCAR_RATE_MANAGE_NONE"
.IP "\s-1OSCAR_RATE_MANAGE_AUTO\s0" 4
.IX Item "OSCAR_RATE_MANAGE_AUTO"
.IP "\s-1OSCAR_RATE_MANAGE_MANUAL\s0" 4
.IX Item "OSCAR_RATE_MANAGE_MANUAL"
.IP "\s-1GROUPPERM_OSCAR\s0" 4
.IX Item "GROUPPERM_OSCAR"
.IP "\s-1GROUPPERM_AOL\s0" 4
.IX Item "GROUPPERM_AOL"
.IP "\s-1TYPINGSTATUS_STARTED\s0" 4
.IX Item "TYPINGSTATUS_STARTED"
.IP "\s-1TYPINGSTATUS_TYPING\s0" 4
.IX Item "TYPINGSTATUS_TYPING"
.IP "\s-1TYPINGSTATUS_FINISHED\s0" 4
.IX Item "TYPINGSTATUS_FINISHED"
.PD
.SH "Net::AIM Compatibility"
.IX Header "Net::AIM Compatibility"
Here are the major differences between the \f(CW\*(C`Net::OSCAR\*(C'\fR interface
and the \f(CW\*(C`Net::AIM\*(C'\fR interface:
.IP "\(bu" 4
No get/set method.
.IP "\(bu" 4
No newconn/getconn method.
.IP "\(bu" 4
No group parameter for add_permit or add_deny.
.IP "\(bu" 4
Many differences in chat handling.
.IP "\(bu" 4
No chat_whisper.
.IP "\(bu" 4
No encode method \- it isn't needed.
.IP "\(bu" 4
No send_config method \- it isn't needed.
.IP "\(bu" 4
No send_buddies method \- we don't keep a separate local buddylist.
.IP "\(bu" 4
No normalize method \- it isn't needed.  Okay, there is a normalize
function in \f(CW\*(C`Net::OSCAR::Utility\*(C'\fR, but I can't think of any reason
why it would need to be used outside of the module internals.  \f(CW\*(C`Net::OSCAR\*(C'\fR
provides the same functionality through the \f(CW\*(C`Net::OSCAR::Screenname\*(C'\fR class.
.IP "\(bu" 4
Different callbacks with different parameters.
.SH "MISCELLANEOUS INFO"
.IX Header "MISCELLANEOUS INFO"
There are two programs included with the \f(CW\*(C`Net::OSCAR\*(C'\fR distribution.
\&\f(CW\*(C`oscartest\*(C'\fR is half a reference implementation of a \f(CW\*(C`Net::OSCAR\*(C'\fR client
and half a tool for testing this library.  \f(CW\*(C`snacsnatcher\*(C'\fR is a tool designed
for analyzing the \s-1OSCAR\s0 protocol from libpcap-format packet captures, but
it isn't particularly well-maintained; the Ethereal sniffer does a good
job at this nowadays.
.PP
There is a class \f(CW\*(C`Net::OSCAR::Screenname\*(C'\fR.  \s-1OSCAR\s0 screennames
are case and whitespace insensitive, and if you do something like
\&\f(CW\*(C`$buddy = new Net::OSCAR::Screenname "Matt Sachs"\*(C'\fR instead of
\&\f(CW\*(C`$buddy = "Matt Sachs"\*(C'\fR, this will be taken care of for you when
you use the string comparison operators (eq, ne, cmp, etc.)
.PP
\&\f(CW\*(C`Net::OSCAR::Connection\*(C'\fR, the class used for connection objects,
has some methods that may or may not be useful to you.
.IP "get_filehandle" 4
.IX Item "get_filehandle"
Returns the filehandle used for the connection.  Note that this is a method
of \f(CW\*(C`Net::OSCAR::Connection\*(C'\fR, not \f(CW\*(C`Net::OSCAR\*(C'\fR.
.IP "process_one (\s-1CAN_READ, CAN_WRITE, HAS_ERROR\s0)" 4
.IX Item "process_one (CAN_READ, CAN_WRITE, HAS_ERROR)"
Call this when a \f(CW\*(C`Net::OSCAR::Connection\*(C'\fR is ready for reading and/or
writing.  You might call this yourself instead of using \*(L"process_connections\*(R"
when, for instance, using the \*(L"connection_changed\*(R" callback in conjunction with
\&\f(CW\*(C`IO::Poll\*(C'\fR instead of \f(CW\*(C`select\*(C'\fR.  The \f(CW\*(C`CAN_READ\*(C'\fR and \f(CW\*(C`CAN_WRITE\*(C'\fR 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 \f(CW\*(C`HAS_ERROR\*(C'\fR to non-zero.
.IP "session" 4
.IX Item "session"
Returns the \f(CW\*(C`Net::OSCAR\*(C'\fR object associated with this \f(CW\*(C`Net::OSCAR::Connection\*(C'\fR.
.SH "USER INFORMATION"
.IX Header "USER INFORMATION"
Methods which return information about a user, such as \*(L"buddy\*(R", 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.
.IP "online" 4
.IX Item "online"
The user is signed on.  If this key is not present, all of the other keys may not
be present.
.IP "screenname" 4
.IX Item "screenname"
The formatted version of the user's screenname.  This includes all spacing and
capitalization.  This is a \f(CW\*(C`Net::OSCAR::Screenname\*(C'\fR object, so you don't have to
worry about the fact that it's case and whitespace insensitive when comparing it.
.IP "comment" 4
.IX Item "comment"
A user-defined comment associated with the buddy.  See \*(L"set_buddy_comment\*(R".
Note that this key will be present but undefined if there is no comment.
.IP "alias" 4
.IX Item "alias"
A user-defined alias for the buddy.  See \*(L"set_buddy_alias\*(R".
Note that this key will be present but undefined if there is no alias.
.IP "extended_status" 4
.IX Item "extended_status"
The user's extended status message, if one is set, will be in this key.
This requires that you set the \f(CW\*(C`extended_status\*(C'\fR capability when
creating the \f(CW\*(C`Net::OSCAR\*(C'\fR object.
.IP "trial" 4
.IX Item "trial"
The user's account has trial status.
.IP "aol" 4
.IX Item "aol"
The user is accessing the \s-1AOL\s0 Instant Messenger service from America OnLine.
.IP "free" 4
.IX Item "free"
Opposite of aol.
.IP "away" 4
.IX Item "away"
The user is away.
.IP "admin" 4
.IX Item "admin"
The user is an administrator.
.IP "mobile" 4
.IX Item "mobile"
The user is using a mobile device.
.IP "typing_status" 4
.IX Item "typing_status"
The user is known to support typing status notification.  We only find this out if they send us an \s-1IM.\s0
.IP "capabilities" 4
.IX Item "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.
.IP "icon" 4
.IX Item "icon"
The user's buddy icon, if available.
.IP "icon_checksum" 4
.IX Item "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.
.IP "icon_timestamp" 4
.IX Item "icon_timestamp"
The modification timestamp of the user's buddy icon, if available.
.IP "icon_length" 4
.IX Item "icon_length"
The length of the user's buddy icon, if available.
.IP "membersince" 4
.IX Item "membersince"
Time that the user's account was created, in the same format as the \f(CW\*(C`time\*(C'\fR function.
.IP "onsince" 4
.IX Item "onsince"
Time that the user signed on to the service, in the same format as the \f(CW\*(C`time\*(C'\fR function.
.IP "idle_since" 4
.IX Item "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 \f(CW\*(C`time()\*(C'\fR .
.IP "evil" 4
.IX Item "evil"
Evil (warning) level for the user.
.PP
Some keys; namely, \f(CW\*(C`typing_status\*(C'\fR and \f(CW\*(C`icon_checksum\*(C'\fR, may be available for people
who the user has communicated with but who are not on the user's buddylist.
.SH "ICQ-SPECIFIC INFORMATION"
.IX Header "ICQ-SPECIFIC INFORMATION"
\&\s-1ICQ\s0 support isn't nearly as well-tested as \s-1AIM\s0 support, and ICQ-specific
features aren't being particularly actively developed.  Patches for ICQ-isms
are welcome.  The initial patch enabling us to sign on to \s-1ICQ\s0 was provided by Sam Wong.
.SS "\s-1ICQ METHODS\s0"
.IX Subsection "ICQ METHODS"
.IP "get_icq_info (\s-1UIN\s0)" 4
.IX Item "get_icq_info (UIN)"
Requests ICQ-specific information.  See also the \*(L"buddy_icq_info\*(R" callback.
.SS "\s-1ICQ CALLBACKS\s0"
.IX Subsection "ICQ CALLBACKS"
.IP "buddy_icq_info (\s-1OSCAR, UIN, ICQ DATA\s0)" 4
.IX Item "buddy_icq_info (OSCAR, UIN, ICQ DATA)"
The result of a \*(L"get_icq_info\*(R" call.  Data is a hashref with the following keys, the value
of each key is a either a hashref or undefined:
.RS 4
.IP "basic" 4
.IX Item "basic"
.RS 4
.PD 0
.IP "nickname" 4
.IX Item "nickname"
.IP "firstname" 4
.IX Item "firstname"
.IP "lastname" 4
.IX Item "lastname"
.IP "email" 4
.IX Item "email"
.IP "gmt_offset" 4
.IX Item "gmt_offset"
.IP "authorization" 4
.IX Item "authorization"
.IP "web_aware" 4
.IX Item "web_aware"
.IP "direct_connect_permissions" 4
.IX Item "direct_connect_permissions"
.IP "publish_primary_email" 4
.IX Item "publish_primary_email"
.RE
.RS 4
.RE
.IP "home" 4
.IX Item "home"
.RS 4
.IP "city" 4
.IX Item "city"
.IP "state" 4
.IX Item "state"
.IP "phone_num" 4
.IX Item "phone_num"
.IP "fax_num" 4
.IX Item "fax_num"
.IP "address" 4
.IX Item "address"
.IP "cell_phone_num" 4
.IX Item "cell_phone_num"
.IP "zip_code" 4
.IX Item "zip_code"
.IP "country_code" 4
.IX Item "country_code"
.RE
.RS 4
.RE
.IP "office" 4
.IX Item "office"
.RS 4
.IP "city" 4
.IX Item "city"
.IP "state" 4
.IX Item "state"
.IP "phone_num" 4
.IX Item "phone_num"
.IP "fax_num" 4
.IX Item "fax_num"
.IP "address" 4
.IX Item "address"
.IP "zip_code" 4
.IX Item "zip_code"
.IP "country_code" 4
.IX Item "country_code"
.IP "company" 4
.IX Item "company"
.IP "department" 4
.IX Item "department"
.IP "position" 4
.IX Item "position"
.IP "occupation" 4
.IX Item "occupation"
.IP "office_website" 4
.IX Item "office_website"
.RE
.RS 4
.RE
.IP "background" 4
.IX Item "background"
.RS 4
.IP "age" 4
.IX Item "age"
.IP "gender" 4
.IX Item "gender"
.IP "homepage" 4
.IX Item "homepage"
.IP "birth_year" 4
.IX Item "birth_year"
.IP "birth_month" 4
.IX Item "birth_month"
.IP "birth_day" 4
.IX Item "birth_day"
.IP "spoken_languages" 4
.IX Item "spoken_languages"
.PD
This key is a listref containing the langauges the user speaks.
.IP "origin_city" 4
.IX Item "origin_city"
.PD 0
.IP "origin_state" 4
.IX Item "origin_state"
.IP "origin_country" 4
.IX Item "origin_country"
.IP "marital_status" 4
.IX Item "marital_status"
.RE
.RS 4
.RE
.IP "notes" 4
.IX Item "notes"
.PD
This key is a simple scalar.
.IP "email_addresses" 4
.IX Item "email_addresses"
This key is a listref, each element of which is a hashref with the following keys:
.RS 4
.IP "publish" 4
.IX Item "publish"
.PD 0
.IP "address" 4
.IX Item "address"
.RE
.RS 4
.RE
.IP "interests" 4
.IX Item "interests"
.PD
This key is a listref, each element of which is a hashref with the following keys:
.RS 4
.IP "category" 4
.IX Item "category"
.PD 0
.IP "interest" 4
.IX Item "interest"
.RE
.RS 4
.RE
.IP "past_affiliations" 4
.IX Item "past_affiliations"
.PD
This key is a listref, each element of which is a hashref with the following keys:
.RS 4
.IP "category" 4
.IX Item "category"
.PD 0
.IP "affiliation" 4
.IX Item "affiliation"
.RE
.RS 4
.RE
.IP "present_affiliations" 4
.IX Item "present_affiliations"
.PD
As per above.
.IP "homepage" 4
.IX Item "homepage"
.RS 4
.PD 0
.IP "category" 4
.IX Item "category"
.IP "keywords" 4
.IX Item "keywords"
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.PD
.SH "HIGH-PERFORMANCE EVENT PROCESSING"
.IX Header "HIGH-PERFORMANCE EVENT PROCESSING"
A second way of doing event processing is designed to make it easy to integrate \f(CW\*(C`Net::OSCAR\*(C'\fR into
an existing \f(CW\*(C`select\*(C'\fR\-based event loop, especially one where you have many \f(CW\*(C`Net::OSCAR\*(C'\fR objects.
Simply call the \*(L"process_connections\*(R" method with references to the lists of readers, writers,
and errors given to you by \f(CW\*(C`select\*(C'\fR.  Connections that don't belong to the object will be ignored,
and connections that do belong to the object will be removed from the \f(CW\*(C`select\*(C'\fR 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 \f(CW\*(C`Net::OSCAR\*(C'\fR objects:
.PP
.Vb 5
\&        my $ein = $rin | $win;
\&        select($rin, $win, $ein, 0.01);
\&        foreach my $oscar(@oscars) {
\&                $oscar\->process_connections(\e$rin, \e$win, \e$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.
.Ve
.PP
The third way of doing connection processing uses the \*(L"connection_changed\*(R"
callback in conjunction with \f(CW\*(C`Net::OSCAR::Connection\*(C'\fR's \*(L"process_one\*(R" method.
This method, in conjunction with \f(CW\*(C`IO::Poll\*(C'\fR, probably offers the highest performance
in situations where you have a long-lived application which creates and destroys many
\&\f(CW\*(C`Net::OSCAR\*(C'\fR sessions; that is, an application whose list of file descriptors to
monitor will likely be sparse.  However, this method is the most complicated.
What you need to do is call \f(CW\*(C`IO::Poll::mask\*(C'\fR inside of the \*(L"connection_changed\*(R"
callback.  That part's simple.  The tricky bit is figuring out which
\&\f(CW\*(C`Net::OSCAR::Connection::process_one\*(C'\fR'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 monitoring in the \f(CW\*(C`IO::Poll\*(C'\fR \- the FDs can be retrieved by doing
\&\f(CW\*(C`fileno($connection\->get_filehandle)\*(C'\fR inside of the \*(L"connection_changed\*(R" \-
and then calling \f(CW\*(C`@handles = $poll\->handles(POLLIN | POLLOUT | POLLERR | POLLHUP)\*(C'\fR
and walking through the handles.
.PP
For optimum performance, use the \*(L"connection_changed\*(R" callback.
.SH "HISTORY"
.IX Header "HISTORY"
.IP "\(bu" 4
1.925, 2006\-02\-06
.RS 4
.IP "\(bu" 4
Many buddylist performance enhancements and bug fixes.
.IP "\(bu" 4
Added support for receiving dynamic buddylist changes from the server
(\f(CW\*(C`callback_buddylist_changed\*(C'\fR.)
.IP "\(bu" 4
Add support buddylist transfer (\f(CW\*(C`set_callback_buddylist_in\*(C'\fR.)
.IP "\(bu" 4
Miscellaneous performance and scalability enhancements.
.IP "\(bu" 4
Added experimental migration support.
.IP "\(bu" 4
Added advanced rate limit management \s-1API.\s0
.IP "\(bu" 4
Added \f(CW\*(C`oscarserv\*(C'\fR server for testing.
.IP "\(bu" 4
Audited screennames exposed to application to verify that they are
\&\f(CW\*(C`Net::OSCAR::Screenname\*(C'\fR objects everywhere.
.IP "\(bu" 4
Began work on file transfer.
.IP "\(bu" 4
Connection status fix for compatibility with \s-1POE.\s0
.RE
.RS 4
.RE
.IP "\(bu" 4
1.907, 2004\-09\-22
.RS 4
.IP "\(bu" 4
Fixed assert failure on certain invalid input (\*(L"Buddy Trikill\*(R" crash)
.RE
.RS 4
.RE
.IP "\(bu" 4
1.906, 2004\-08\-28
.RS 4
.IP "\(bu" 4
Reorganized documentation
.RE
.RS 4
.RE
.IP "\(bu" 4
1.904, 2004\-08\-26
.RS 4
.IP "\(bu" 4
Add \f(CW$Net::OSCAR::XML::NO_XML_CACHE\fR to prevent use of cached \s-1XML\s0 parse tree,
and skip tests if we can't load Test::More or XML::Parser.
.RE
.RS 4
.RE
.IP "\(bu" 4
1.903, 2004\-08\-26
.RS 4
.IP "\(bu" 4
Generate \s-1XML\s0 parse tree at module build time so that users don't need to have
XML::Parser and expat installed.
.RE
.RS 4
.RE
.IP "\(bu" 4
1.902, 2004\-08\-26
.RS 4
.IP "\(bu" 4
Fixes to buddy icon upload and chat invitation decline
.IP "\(bu" 4
Increase performance by doing lazy generation of certain debugging info
.RE
.RS 4
.RE
.IP "\(bu" 4
1.901, 2004\-08\-24
.RS 4
.IP "\(bu" 4
Lots of buddylist-handling bug fixes; should fix intermittent buddylist modification errors
and errors only seen when modifying certain screennames; Roy C. rocks.
.IP "\(bu" 4
We now require Perl 5.6.1.
.IP "\(bu" 4
Workaround for bug in Perl pre\-5.8.4 which manifested as a \*(L"'basic \s-1OSCAR\s0 services' isn't numeric\*(R"
warning followed by the program freezing.
.IP "\(bu" 4
\&\f(CW\*(C`add_group\*(C'\fR and \f(CW\*(C`remove_group\*(C'\fR methods added.
.IP "\(bu" 4
Fixed a potential memory leak which could impact programs which create many transient Net::OSCAR
objects.
.RE
.RS 4
.RE
.IP "\(bu" 4
1.900, 2004\-08\-17
.RS 4
.IP "\(bu" 4
Wrote new XML-based protocol back-end with reasonably comprehensive test-suite.
Numerous protocol changes; we now emulate \s-1AOL\s0's version 5.5 client.
.IP "\(bu" 4
Rewrote snacsnatcher, an \s-1OSCAR\s0 protocol analysis tool
.IP "\(bu" 4
Reorganized documentation
.IP "\(bu" 4
\&\s-1ICQ\s0 meta-info support: get_icq_info method, buddy_icq_info callback
.IP "\(bu" 4
Stealth mode support: is_stealth and set_stealth methods, stealth_changed callback, stealth signon key
.IP "\(bu" 4
More flexible unknown \s-1SNAC\s0 handling: snac_unknown callback
.IP "\(bu" 4
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.
.IP "\(bu" 4
Inability to set blocking on Win32 is no longer fatal.  Silly platform.
.IP "\(bu" 4
Fixed chat functionality.
.RE
.RS 4
.RE
.IP "\(bu" 4
1.11, 2004\-02\-13
.RS 4
.IP "\(bu" 4
Fixed presence-related problems modifying some buddylists
.RE
.RS 4
.RE
.IP "\(bu" 4
1.10, 2004\-02\-10
.RS 4
.IP "\(bu" 4
Fixed idle time handling; user info hashes now have an 'idle_since' key,
which you should use instead of the old 'idle' key.  Subtract \f(CW\*(C`idle_since\*(C'\fR
from \f(CW\*(C`time()\*(C'\fR to get the length of time for which the user has been idle.
.IP "\(bu" 4
Fixed buddylist type 5 handling; this fixes problems modifying the buddylists
of recently-created screennames.
.RE
.RS 4
.RE
.IP "\(bu" 4
1.01, 2004\-01\-06
.RS 4
.IP "\(bu" 4
Fixed buddy \s-1ID\s0 generation (problems adding buddies)
.RE
.RS 4
.RE
.IP "\(bu" 4
1.00, 2004\-01\-03
.RS 4
.IP "\(bu" 4
Documented requirement to wait for buddylist_foo callback between calls to commit_buddylist
.IP "\(bu" 4
Fixed handling of idle time (zoyboy22)
.IP "\(bu" 4
More flexible signon method
.IP "\(bu" 4
Added buddy alias support
.IP "\(bu" 4
Buddy icon support
.IP "\(bu" 4
Typing notification support
.IP "\(bu" 4
mac.com screenname support
.IP "\(bu" 4
Support for communicating with \s-1ICQ\s0 users from \s-1AIM\s0
.IP "\(bu" 4
iChat extended status message support
.IP "\(bu" 4
We now emulate \s-1AOL\s0 Instant Messenger for Windows 5.2
.IP "\(bu" 4
We now parse the capabilities of other users
.IP "\(bu" 4
Attempts at Win32 (non-cygwin) support
.RE
.RS 4
.RE
.IP "\(bu" 4
0.62, 2002\-02\-25
.RS 4
.IP "\(bu" 4
Error handling slightly improved; error 29 is no longer unknown.
.IP "\(bu" 4
A minor internal buddylist enhancement
.IP "\(bu" 4
snacsnatcher fixes
.RE
.RS 4
.RE
.IP "\(bu" 4
0.61, 2002\-02\-17
.RS 4
.IP "\(bu" 4
Fixed connection handling
.RE
.RS 4
.RE
.IP "\(bu" 4
0.60, 2002\-02\-17
.RS 4
.IP "\(bu" 4
Various connection_changed fixes, including the new readwrite status.
.IP "\(bu" 4
Added Net::OSCAR::Connection::session method
.IP "\(bu" 4
Improved Net::OSCAR::Connection::process_one, documented it, and documented using it
.RE
.RS 4
.RE
.IP "\(bu" 4
0.59, 2002\-02\-15
.RS 4
.IP "\(bu" 4
Protocol fixes \- solves problem with \s-1AOL\s0 calling us an unauthorized client
.IP "\(bu" 4
Better handling of socket errors, especially when writing
.IP "\(bu" 4
Minor \s-1POD\s0 fixes
.RE
.RS 4
.RE
.IP "\(bu" 4
0.58, 2002\-01\-20
.RS 4
.IP "\(bu" 4
Send buddylist deletions before adds \- needed for complex \s-1BL\s0 mods (loadbuddies)
.IP "\(bu" 4
Added hooks to allow client do \s-1MD5\s0 digestion for authentication (auth_challenge
callback, Net::OSCAR::auth_response method)
.RE
.RS 4
.RE
.IP "\(bu" 4
0.57, 2002\-01\-16
.RS 4
.IP "\(bu" 4
Send callback_chat_joined correctly when joining an existing chat
.IP "\(bu" 4
Don't activate OldPerl fixes for perl 5.6.0
.IP "\(bu" 4
Ignore chats that we're already in
.RE
.RS 4
.RE
.IP "\(bu" 4
0.56, 2002\-01\-16
.RS 4
.IP "\(bu" 4
Fixed rate handling
.IP "\(bu" 4
Send multiple buddylist modifications per \s-1SNAC\s0
.IP "\(bu" 4
Detect when someone else signs on with your screenname
.IP "\(bu" 4
Corrected attribution of \s-1ICQ\s0 support
.RE
.RS 4
.RE
.IP "\(bu" 4
0.55, 2001\-12\-29
.RS 4
.IP "\(bu" 4
Preliminary \s-1ICQ\s0 support, courtesy of SDiZ Chen (actually, Sam Wong).
.IP "\(bu" 4
Restored support for pre\-5.6 perls \- reverted from \f(CW\*(C`IO::Socket\*(C'\fR to \f(CW\*(C`Socket\*(C'\fR.
.IP "\(bu" 4
Corrected removal of buddylist entries and other buddylist-handling improvements
.IP "\(bu" 4
Improved rate handling \- new \f(CW\*(C`worrisome\*(C'\fR parameter to rate_alert callback
.IP "\(bu" 4
Removed remaining \f(CW\*(C`croak\*(C'\fR from \f(CW\*(C`OSCAR::Connection\*(C'\fR
.IP "\(bu" 4
Added is_on method
.RE
.RS 4
.RE
.IP "\(bu" 4
0.50, 2001\-12\-23
.RS 4
.IP "\(bu" 4
Fixes for the \*(L"crap out on 'connection reset by peer'\*(R" and \*(L"get stuck and slow down in Perl_sv_2bool\*(R" bugs!
.IP "\(bu" 4
Correct handling of very large (over 100 items) buddylists.
.IP "\(bu" 4
We can now join exchange 5 chats.
.IP "\(bu" 4
Fixes in modifying permit mode.
.IP "\(bu" 4
Updated copyright notice courtesy of \s-1AOL\s0's lawyers.
.IP "\(bu" 4
Switch to IO::Socket for portability in set_blocking.
.RE
.RS 4
.RE
.IP "\(bu" 4
0.25, 2001\-11\-26
.RS 4
.IP "\(bu" 4
Net::OSCAR is now in beta!
.IP "\(bu" 4
We now work with perl 5.005 and even 5.004
.IP "\(bu" 4
Try to prevent weird Net::OSCAR::Screenname bug where perl gets stuck in Perl_sv_2bool
.IP "\(bu" 4
Fixed problems with setting visibility mode and adding to deny list (thanks, Philip)
.IP "\(bu" 4
Added some methods to allow us to be POE-ified
.IP "\(bu" 4
Added guards around a number of methods to prevent the user from trying to do stuff before s/he's finished signing on.
.IP "\(bu" 4
Fix *incredibly* stupid error in NO_to_BLI that ate group names
.IP "\(bu" 4
Fixed bad bug in log_printf
.IP "\(bu" 4
Buddylist error handling changes
.IP "\(bu" 4
Added chat_decline command
.IP "\(bu" 4
Signon, signoff fixes
.IP "\(bu" 4
Allow \s-1AOL\s0 screennames to sign on
.IP "\(bu" 4
flap_get crash fixes
.RE
.RS 4
.RE
.IP "\(bu" 4
0.09, 2001\-10\-01
.RS 4
.IP "\(bu" 4
Crash and undefined value fixes
.IP "\(bu" 4
New method: im_ok
.IP "\(bu" 4
New method: rename_group, should fix \*(L"Couldn't get group name\*(R" error.
.IP "\(bu" 4
Fix for buddy_in callback and data
.IP "\(bu" 4
Better error handling when we can't resolve a host
.IP "\(bu" 4
Vastly improved logging infrastructure \- debug_print(f) replaced with log_print(f). debug_print callback is now called log and has an extra parameter.
.IP "\(bu" 4
Fixed \s-1MANIFEST \-\s0 we don't actually use Changes (and we do use Screenname.pm)
.IP "\(bu" 4
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 \f(CW$bli\fR\->{0}\->{1}\->{2}\->{data}\->{0x3} = \*(L"foo\*(R" without worrying if 0, 1, 2, or data have been tied.  Should close bug #47.
.RE
.RS 4
.RE
.IP "\(bu" 4
0.08, 2001\-09\-07
.RS 4
.IP "\(bu" 4
Totally rewritten buddylist handling.  It is now much cleaner, bug-resistant,
and featureful.
.IP "\(bu" 4
Many, many internal changes that I don't feel like enumerating.
Hey, there's a reason that I haven't declared the interface stable yet! ;)
.IP "\(bu" 4
New convenience object: Net::OSCAR::Screenname
.IP "\(bu" 4
Makefile.PL: Fixed perl version test and compatibility with \s-1BSD\s0 make
.RE
.RS 4
.RE
.IP "\(bu" 4
0.07, 2001\-08\-13
.RS 4
.IP "\(bu" 4
A bunch of Makefile.PL fixes
.IP "\(bu" 4
Fixed spurious admin_error callback and prevent user from having multiple
pending requests of the same type.  (closes #39)
.IP "\(bu" 4
Head off some potential problems with set_visibility.  (closes #34)
.IP "\(bu" 4
Removed connections method, added selector_filenos
.IP "\(bu" 4
Added error number 29 (too many recent signons from your site) to Net::OSCAR::Common.
.IP "\(bu" 4
We now explicitly perl 5.6.0 or newer.
.RE
.RS 4
.RE
.IP "\(bu" 4
0.06, 2001\-08\-12
.RS 4
.IP "\(bu" 4
Prevent sending duplicate signon_done messages
.IP "\(bu" 4
Don't addconn after crapping out!
.IP "\(bu" 4
Don't try to delconn unless we have connections.
.IP "\(bu" 4
delete returns the correct value now in Net::OSCAR::Buddylist.
.IP "\(bu" 4
Don't use warnings if $] <= 5.005
.IP "\(bu" 4
evil is a method, not a manpage (doc fix)
.IP "\(bu" 4
Added buddyhash method.
.IP "\(bu" 4
Added a debug_print callback.
.IP "\(bu" 4
Clarified process_connections method in documentation
.IP "\(bu" 4
You can now specify an alternate host/port in signon
.IP "\(bu" 4
Added name method to Chat.
.IP "\(bu" 4
permit list and deny list are no longer part of buddylist
.IP "\(bu" 4
Rewrote buddylist parsing (again!)
.IP "\(bu" 4
No more default profile.
.IP "\(bu" 4
Fix bug when storing into an already-existing key in Net::OSCAR::Buddylist.
.IP "\(bu" 4
snacsnatcher: Remove spurious include of Net::OSCAR::Common
.IP "\(bu" 4
We don't need to handle \s-1VISMODE_PERMITBUDS\s0 ourself \- the server takes care of it.
Thanks, \s-1VB\s0!
.IP "\(bu" 4
Makefile.PL: Lots of way cool enhancements to make dist:
.RS 4
.IP "\-" 4
It modifies the version number for us
.IP "\-" 4
It does a \s-1CVS\s0 rtag
.IP "\-" 4
It updates the \s-1HTML\s0 documentation on zevils and the \s-1README.\s0
.RE
.RS 4
.RE
.IP "\(bu" 4
Added \s-1HISTORY\s0 and \s-1INSTALLATION\s0 section to \s-1POD.\s0
.RE
.RS 4
.RE
.IP "\(bu" 4
0.05, 2001\-08\-08
.RS 4
.IP "\(bu" 4
Don't send signon_done until after we get buddylist.
.IP "\(bu" 4
Added signoff method.
.IP "\(bu" 4
Fixed typo in documentation
.IP "\(bu" 4
Fixed chat_invite parm count
.IP "\(bu" 4
Added Scalar::Utils::dualvar variables, especially to Common.pm.
dualvar variables return different values in numeric and string context.
.IP "\(bu" 4
Added url method for Net::OSCAR::Chat (closes #31)
.IP "\(bu" 4
Divide evil by 10 in extract_userinfo (closes #30)
.IP "\(bu" 4
chat_invite now exposes chatname (closes #32)
.IP "\(bu" 4
Removed unnecessary and warning-generating session length from extract_userinfo
.RE
.RS 4
.RE
.IP "\(bu" 4
0.01, 2001\-08\-02
.RS 4
.IP "\(bu" 4
Initial release.
.RE
.RS 4
.RE
.SH "SUPPORT"
.IX Header "SUPPORT"
See http://www.zevils.com/programs/net\-oscar/ for support, including
a mailing list and bug-tracking system.
.SH "AUTHOR"
.IX Header "AUTHOR"
Matthew Sachs <matthewg@zevils.com>.
.SH "CREDITS"
.IX Header "CREDITS"
\&\s-1AOL,\s0 for creating the \s-1AOL\s0 Instant Messenger service, even though they aren't terribly helpful to
developers of third-party clients.
.PP
Apple Computer for help with mac.com support.
.PP
The users of \s-1IMIRC\s0 for being reasonably patient while this module was developed.  <http://www.zevils.com/programs/imirc/>
.PP
Bill Atkins for typing status notification and mobile user support.  <http://www.milkbone.org/>
.PP
Jayson Baker for some last-minute debugging help.
.PP
Roy Camp for loads of bug reports and ideas and helping with user support.
.PP
Rocco Caputo for helping to work out the hooks that let use be used with
\&\s-1POE. \s0 <http://poe.perl.org/>
.PP
Mark Doliner for help with remote buddylists.  <http://kingant.net/libfaim/ReadThis.html>
.PP
Adam Fritzler and the libfaim team for their documentation and an \s-1OSCAR\s0 implementation that
was used to help figure out a lot of the protocol details.  <http://www.zigamorph.net/faim/protocol/>
.PP
The gaim team \- the source to their libfaim client was also very helpful.  <http://gaim.sourceforge.net/>
.PP
Nick Gray for sponsoring scalability work.
.PP
John \*(L"VBScript\*(R" for a lot of technical assistance, including the explanation of rates.
.PP
Jonathon Wodnicki for additional help with typing status notification.
.PP
Sam Wong <sam@uhome.net> for a patch implementing \s-1ICQ2000\s0 support.
.SH "LEGAL"
.IX Header "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.  \fB\s-1AOL\s0\fR and \fB\s-1AMERICA ONLINE\s0\fR are registered trademarks
owned by America Online, Inc.  The \fB\s-1INSTANT MESSENGER\s0\fR mark is owned by America
Online, Inc.  \fB\s-1ICQ\s0\fR is a trademark and/or servicemark of \s-1ICQ.  \s0\f(CW\*(C`Net::OSCAR\*(C'\fR is not
endorsed by, or affiliated with, America Online, Inc or \s-1ICQ.  \s0\fBiChat\fR and \fBApple Computer\fR
are registered trademarks of Apple Computer, Inc.  \f(CW\*(C`Net::OSCAR\*(C'\fR is not endorsed by,
or affiliated with, Apple Computer, Inc or iChat.