NAME
Net::OSCAR - Implementation of AOL's OSCAR protocol for instant
messaging
SYNOPSIS
use Net::OSCAR qw(:standard);
use Net::OSCAR::OldPerl; # You may need to use this perls older than 5.6.
$oscar = Net::OSCAR->new();
$oscar->set_callback_foo(\&foo);
$oscar->signon($screenname, $password);
while(1) {
$oscar->do_one_loop();
# Do stuff
}
INSTALLATION
perl Makefile.PL
make
make test
make install
See "perlmodinstall" for details.
DEPENDENCIES
This modules requires "Digest::MD5" and "Scalar::Util".
ABSTRACT
"Net::OSCAR" implements the OSCAR protocol which is used by AOL's AOL
Instant Messenger service. To use the module, you create a "Net::OSCAR"
object, register some functions as handlers for various events by using
the module's callback mechanism, and then continually make calls to the
module's event processing methods.
You probably want to use the :standard parameter when importing this
module in order to have a few important constants added to your
namespace. 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. That doesn't really help this module's stability much.
This module strives to be as compatible with "Net::AIM" as possible, but
some protocol-level differences prevent total compatibility. The TOC
protocol implemented by "Net::AIM" is simpler and more well-documented
but less-powerful protocol then "OSCAR". See the section on "Net::AIM
Compatibility" for more information.
EVENT PROCESSING
There are two main ways for the module to handle event processing. The
first is to call the do_one_loop method, which performs a "select" call
on all the object's sockets and reads incoming commands from the OSCAR
server on any connections which have them. The "select" call has a
default timeout of 0.01 seconds which can be adjust using the timeout
method.
The other way of doing event processing is designed to make it easy to
integrate "Net::OSCAR" into an existing "select"-based event loop,
especially one where you have many "Net::OSCAR" objects. Simply call the
"process_connections" method with references to the lists of readers,
writers, and errors given to you by "select". Connections that don't
belong to the object will be ignored, and connections that do belong to
the object will be removed from the "select" lists so that you can use
the lists for your own purposes. Here is an example that demonstrates
how to use this method with multiple "Net::OSCAR" objects:
my($rin, $win) = (0, 0);
foreach my $oscar(@oscars) {
my($thisrin, $thiswin) = $oscar->selector_filenos;
$rin |= $thisrin;
$win |= $thiswin;
}
# Add in any other file descriptors you care about using vec().
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.
FUNCTIONALITY
"Net::OSCAR" pretends to be WinAIM 4.3.2229. It supports remote
buddylists including permit and deny settings. It also supports chat. At
the present time, setting and retrieving of directory information is not
supported; nor are email privacy settings, buddy icons, voice chat,
stock ticker, and many other of the official AOL Instant Messenger
client's features.
TERMINOLOGY/METHODOLOGY
When you sign on with the OSCAR service, you are establishing an OSCAR
session. "Net::OSCAR" connects to the login server and requests a random
challenge string. It then sends the MD5 sum of the challenge string,
"AOL Instant Messenger (SM)", and your password to the server. If the
login is successful, the login server gives you an IP address and an
authorization cookie to use to connect with the BOS (Basic OSCAR
Services) server.
"Net::OSCAR" proceeds to disconnect from the login server and connect to
the BOS server. The two go through a handshaking process which includes
the server sending us our buddylist.
"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
new Creates a new "Net::OSCAR" object.
timeout ([NEW TIMEOUT])
Gets or sets the timeout value used by the do_one_loop method. The
default timeout is 0.01 seconds.
signon (HASH)
signon (SCREENNAME, PASSWORD[, HOST, PORT])
Sign on to the OSCAR service. Using a hash to pass the parameters to
this function is preferred - the old method is deprecated. You can
specify an alternate host/port to connect to. The default is
login.oscar.aol.com port 5190.
If you use a hash to pass parameters to this function, here are the
valid keys:
screenname
password
Screenname and password are mandatory. The other keys are
optional.
host
port
There are some other data that can be passed to this method. These
data are used to sign on to an OSCAR-using service other than the
default of AOL Instant Messenger, such as ICQ. You should not
attempt to specify these data directly - instead, use one of the
following constants:
OSCAR_SVC_AIM
OSCAR_SVC_ICQ
Example of signing on to ICQ:
$oscar->signon(screenname => "123456", password => "password", OSCAR_SVC_ICQ);
signoff
Sign off from the OSCAR service.
loglevel ([LOGLEVEL[, SCREENNAME DEBUG]])
Gets or sets the loglevel. 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.
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.
process_connections (READERSREF, WRITERSREF, ERRORSREF)
Use this method when you want to implement your own "select"
statement for event processing instead of using "Net::OSCAR"'s
do_one_loop method. The parameters are references to the readers,
writers, and errors parameters used by the select statement. The
method will ignore all connections which are not
"Net::OSCAR::Connection" objects or which are
"Net::OSCAR::Connection" objects from a different "Net::OSCAR"
object. It modifies its arguments so that its connections are
removed from the connection lists. This makes it very convenient for
use with multiple "Net::OSCAR" objects or use with a "select"-based
event loop that you are also using for other purposes.
See the selector_filenos method for a way to get the necessary bit
vectors to use in your "select".
do_one_loop
Processes incoming data from our connections to the various OSCAR
services. This method reads one command from any connections which
have data to be read. See the timeout method to set the timeout
interval used by this method.
findbuddy (BUDDY)
Returns the name of the group that BUDDY is in, or undef if BUDDY
could not be found in any group. If BUDDY is in multiple groups,
will return the first one we find.
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.
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
"commit_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.
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.
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. Call
"commit_buddylist" for the change to take effect.
remove_buddy (GROUP, BUDDIES)
See add_buddy.
set_visibility (MODE)
Sets the visibility mode, which determines how the permit and deny
lists are interpreted. The visibility mode may be:
* VISMODE_PERMITALL: Permit everybody.
* VISMODE_DENYALL: Deny everybody.
* VISMODE_PERMITSOME: Permit only those on your permit list.
* VISMODE_DENYSOME: Deny only those on your deny list.
* VISMODE_PERMITBUDS: Same as VISMODE_PERMITSOME, but your permit
list is made to be the same as the buddies from all the various
groups in your buddylist (except the deny group!) Adding and
removing buddies maintains this relationship. You shouldn't
manually alter the permit or deny groups when using this
visibility mode.
These constants are contained in the "Net::OSCAR::Common" package,
and will be imported into your namespace if you import "Net::OSCAR"
with the ":standard" parameter.
When someone is permitted, they can see when you are online and send
you messages. When someone is denied, they can't see when you are
online or send you messages. You cannot see them or send them
messages. You can talk to them if you are in the same chatroom,
although neither of you can invite the other one into a chatroom.
Call "commit_buddylist" for the change to take effect.
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.
profile
Returns your current profile.
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-protocol@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.
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.
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" functions
will be "Net::OSCAR::Screenname" objects, so you they will
automagically be compared without regards to case and whitespace.
evil (WHO[, ANONYMOUSLY])
"Evils", or "warns", a user. Evilling a user increases their evil
level, which makes them look bad and decreases the rate at which
they can send messages. Evil level gradually decreases over time. If
the second parameter is non-zero, the evil will be done anonymously,
which does not increase the user's evil level by as much as a
standard evil.
You can't always evil someone. You can only do it when they do
something like send you an instant message.
set_away (MESSAGE)
Set's the users away message, also marking them as being away. If
the message is undef or the empty string, the user will be marked as
no longer being away.
set_info (PROFILE)
Sets the user's profile. Call "commit_buddylist" to have the new
profile stored on the OSCAR server.
change_password (CURRENT PASSWORD, NEW PASSWORD)
Changes the user's password.
confirm_account
Confirms the user's account. This can be used when the user's
account is in the trial state, as determined by the presence of the
"trial" key in the information given when the user's information is
requested.
change_email (NEW EMAIL)
Requests that the email address registered to the user's account be
changed. This causes the OSCAR server to send an email to both the
new address and the old address. To complete the change, the user
must follow instructions contained in the email sent to the new
address. The email sent to the old address contains instructions
which allow the user to cancel the change within three days of the
change request. It is important that the user's current email
address be known to the OSCAR server so that it may email the
account password if the user forgets it.
format_screenname (NEW FORMAT)
Allows the capitalization and spacing of the user's screenname to be
changed. The new format must be the same as the user's current
screenname, except that case may be changed and spaces may be
inserted or deleted.
chat_join(NAME[, EXCHANGE])
Creates (or joins?) a chatroom. The exchange parameter should
probably not be specified unless you know what you're doing. Do not
use this method to accept invitations to join a chatroom - use the
"chat_accept" method for that.
chat_accept (CHAT)
Use this to accept an invitation to join a chatroom.
chat_decline (CHAT)
Use this to decline an invitation to join a chatroom.
set_idle (TIME)
Sets the user's idle time in seconds. Set to zero to mark the user
as not being idle. Set to non-zero once the user becomes idle. The
OSCAR server will automatically increment the user's idle time once
you mark the user as being idle.
clone
Clones the object. This creates a new "Net::OSCAR" object whose
callbacks, loglevel, screenname debugging, and timeout are the same
as those of the current object. This is provided as a convenience
when using multiple "Net::OSCAR" objects in order to allow you to
set those parameters once and then call the signon method on the
object returned by clone.
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
"process_connections" method for details.
visibility
Returns the user's current visibility setting. See set_visibility.
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
comparison.
buddy (BUDDY[, GROUP])
Returns information about a buddy on the user's buddylist. This
information is a hashref which may have the following keys:
online
The user is signed on. If this key is not present, all of the
other keys may not be present.
screenname
The formatted version of the user's screenname. This includes
all spacing and capitalization. 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
undefined if there is no comment.
trial
The user's account has trial status.
aol The user is accessing the AOL Instant Messenger service from
America OnLine.
free
Opposite of aol.
away
The user is away.
admin
The user is an administrator.
membersince
Time that the user's account was created, in the same format as
the "time" function.
onsince
Time that the user signed on to the service, in the same format
as the "time" function.
idle
Time that the user has been idle for, in seconds. If this key is
present but zero, the user is not idle. If this key is not
present, the user is not reporting idle time.
email
Returns the email address currently assigned to the user's account.
screenname
Returns the user's current screenname, including all capitalization
and spacing.
is_on
Returns true if the user is signed on to the OSCAR service.
Otherwise, returns false.
set_buddy_comment(GROUP, BUDDY[, COMMENT])
Set a brief comment about a buddy. This can be used for things such
as the buddy's real name. You must call "commit_buddylist" to save
the comment to the server. If COMMENT is undefined, the comment is
deleted.
chat_invite(CHAT, MESSAGE, WHO)
Deprecated. Provided for compatibility with "Net::AIM". Use the
appropriate method of the "Net::OSCAR::Chat" object instead.
chat_leave(CHAT)
Deprecated. Provided for compatibility with "Net::AIM". Use the
appropriate method of the "Net::OSCAR::Chat" object instead.
chat_send(CHAT, MESSAGE)
Deprecated. Provided for compatibility with "Net::AIM". Use the
appropriate method of the "Net::OSCAR::Chat" object instead.
CALLBACKS
"Net::OSCAR" uses a callback mechanism to notify you about different
events. A callback is registered by calling the
"set_callback_callbackname" method with a code reference as a parameter.
For instance, you might call "$oscar-"set_callback_error(\&got_error);>.
Your callback function will be passed parameters which are different for
each callback type (and are documented below). The first parameter to
each callback function will be the "Net::OSCAR" object which generated
the callback. This is useful when using multiple "Net::OSCAR" objects.
error (OSCAR, CONNECTION, ERROR, DESCRIPTION, FATAL)
Called when any sort of error occurs (except see admin_error below.)
"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}>. "DESCRIPTION" 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.
rate_alert (OSCAR, LEVEL, CLEAR, WINDOW, WORRISOME)
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.
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
successfully commited.
admin_error (OSCAR, REQTYPE, ERROR, ERRURL)
This is called when there is an error performing an administrative
function - changing your password, formatting your screenname,
changing your email address, or confirming your account. REQTYPE is
a string describing the type of request which generated the error.
ERROR is an error message. ERRURL is an http URL which the user may
visit for more information about the error.
admin_ok (OSCAR, REQTYPE)
This is called when an administrative function succeeds. See
admin_error for more info.
chat_closed (OSCAR, CHAT, ERROR)
Your connection to CHAT (a "Net::OSCAR::Chat" object) was severed
due to ERROR.
buddy_in (OSCAR, SCREENNAME, GROUP, BUDDY DATA)
SCREENNAME (in buddy group GROUP) has signed on, or their
information has changed. BUDDY DATA is the same as that returned by
the buddy method.
chat_buddy_in (OSCAR, SCREENNAME, CHAT, BUDDY DATA)
SCREENNAME has entered CHAT. BUDDY DATA is the same as that returned
by the buddy method.
buddy_out (OSCAR, SCREENNAME, GROUP)
Called when a buddy has signed off (or added us to their deny list.)
chat_buddy_out (OSCAR, SCREENNAME, CHAT)
Called when someone leaves a chatroom.
im_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.
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::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::Chat"
object for the chatroom.
evil(OSCAR, NEWEVIL[, FROM])
Called when your evil level changes. NEWEVIL is your new evil level,
as a percentage (accurate to tenths of a percent.) ENEMY is undef if
the evil was anonymous (or if the message was triggered because your
evil level naturally decreased), otherwise it is the screenname of
the person who sent us the evil. See the "evil" method for more
information on evils.
buddy_info(OSCAR, SCREENNAME, BUDDY DATA)
Called in response to a get_info or get_away request. BUDDY DATA is
the same as that returned by the buddy method, except that one of
two additional keys, "profile" and "awaymsg", may be present.
signon_done(OSCAR)
Called when the user is completely signed on to the service.
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 importance:
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 information
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
session. The "loglevel" method allows you to get or set the
loglevel.
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,
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_filehandle" method of "Net::OSCAR::Connection".
CHATS
Aside from the methods listed here, there are a couple of methods of the
"Net::OSCAR::Chat" object that are important for implementing chat
functionality. "Net::OSCAR::Chat" is a descendent of
"Net::OSCAR::Connection".
invite (WHO, MESSAGE)
Invite somebody into the chatroom.
chat_send (MESSAGE[, NOREFLECT[, AWAY]])
Sends a message to the chatroom. If the NOREFLECT parameter is
present, you will not receive the message as an incoming message
from the chatroom. If AWAY is present, the message was generated as
an automatic reply, perhaps because you have an away message set.
part
Leave the chatroom.
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.
ICQ
ICQ support is very preliminary. A patch enabling us to sign on to ICQ
was provided by Sam Wong. No further work beyond the ability to sign on
has been done on ICQ at this time. See the "signon" method for details
on signing on via ICQ.
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
GROUPPERM_OSCAR
GROUPPERM_AOL
Net::AIM Compatibility
Here are the major differences between the "Net::OSCAR" interface and
the "Net::AIM" interface:
* No get/set method.
* No newconn/getconn method.
* No group parameter for add_permit or add_deny.
* Many differences in chat handling.
* No chat_whisper.
* No encode method - it isn't needed.
* No send_config method - it isn't needed.
* No send_buddies method - we don't keep a separate local buddylist.
* No normalize method - it isn't needed. Okay, there is a normalize
function in "Net::OSCAR::Common", but I can't think of any reason
why it would need to be used outside of the module internals.
* Different callbacks with different parameters.
MISCELLANEOUS
There are two programs included with the "Net::OSCAR" distribution.
oscartest is a minimalist implementation of a "Net::OSCAR" client.
snacsnatcher is a tool designed for analyzing the OSCAR protocol from
libpcap-format packet captures.
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 a
"get_filehandle" method which returns the filehandle (in the current
implementation, a globref created via "gensym"/"socket") used for the
connection.
get_filehandle
Returns the filehandle used for the connection. Note that this is a
method of "Net::OSCAR::Connection", not "Net::OSCAR".
HISTORY
* 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 enumerating.
Hey, there's a reason that I haven't declared the interface
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 having
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 Common.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
mailing list and bug-tracking system.
AUTHOR
Matthew Sachs <matthewg@zevils.com>.
CREDITS
John "VBScript" for a lot of technical assistance, including the
explanation of rates.
Adam Fritzler and the libfaim team for their documentation and an OSCAR
implementation that was used to help figure out a lot of the protocol
Mark Doliner for help with remote buddylists.
Sam Wong <sam@uhome.net> for a patch implementing ICQ2000 support.
The gaim team - the source to their libfaim client was also very
The users of aimirc for being reasonably patient while this module was
Jayson Baker for some last-minute debugging help.
Rocco Caputo for helping to work out the hooks that let use be used with
AOL, for creating the AOL Instant Messenger service, even though they
aren't terribly helpful to developers of third-party clients.
LEGAL
Copyright (c) 2001 Matthew Sachs. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same
terms as Perl itself. AOL 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 servicemark of ICQ.
"Net::OSCAR" is not endorsed by, or affiliated with, America Online, Inc
or ICQ.