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 Build.PL
        perl Build
        perl Build test
        perl Build install
                                                                                                      

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

DEPENDENCIES

This modules requires Digest::MD5 and Scalar::Util.

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 three 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.

A second way of doing event processing is designed to make it easy to integrate Net::OSCAR into an existing select-based event loop, especially one where you have many Net::OSCAR objects. Simply call the "process_connections" method with references to the lists of 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.

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

For optimum performance, use the "connection_changed" callback.

FUNCTIONALITY

Net::OSCAR pretends to be WinAIM 5.2.3292. 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 IM, 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 ([capabilities => CAPABILITIES])

Creates a new Net::OSCAR object. You may optionally pass a hash to set some parameters for the object.

capabilities

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

extended_status

iChat-style extended status messages

buddy_icons

file_transfer

file_sharing

typing_status

Typing status notification

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

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. In the special case of password being present but undefined, the auth_challenge callback will be used - see "auth_challenge" for details.

local_ip

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

host

port

proxy_type

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

proxy_host

proxy_port

proxy_username

proxy_password

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

auth_response (MD5_DIGEST)

Provide a response to an authentication challenge - see the "auth_challenge" callback for details.

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. After calling this method, your program MUST not call it again until either the buddylist_ok or buddylist_error callbacks are received.

rollback_buddylist

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

reorder_groups (GROUPS)

Changes the ordering of the groups in your buddylist. Call "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.

send_typing_status (RECIPIENT, STATUS)

Send a typing status change to another user. Send these messages to implement typing status notification. Valid values for STATUS are:

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

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

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

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)

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.

set_extended_status (MESSAGE)

Sets the user's extended status message. This requires the Net::OSCAR object to have been created with the extended_status 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.

set_info (PROFILE)

Sets the user's profile. Call "commit_buddylist" to have the new profile stored on the OSCAR server.

Note that if the user's profile was previously set with Net::OSCAR, it will be stored in the server-side buddylist, and so this method will not have to be called every time the user signs on. However, other clients do not store the profile on the server, so if the user previously set a profile with a non-Net::OSCAR-based client, this method will need to be called in order for the user's profile to be set.

See the file PROTOCOL, included with the Net::OSCAR distribution, for details of how we're storing this data.

set_icon (ICONDATA)

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

When reading the icon data from a file, make sure to call binmode on the file handle.

Note that if the user's buddy icon was previously set with Net::OSCAR, enough data will be stored in the server-side 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.

See the file PROTOCOL, included with the Net::OSCAR distribution, for details of how we're storing this data.

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

get_icon (SCREENNAME, MD5SUM)

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

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

icon_checksum (ICONDATA)

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

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.

alias

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

extended_status

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

trial

The user's account has trial status.

aol

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

free

Opposite of aol.

away

The user is away.

admin

The user is an administrator.

mobile

The user is using a mobile device.

typing_status

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

capabilities

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

icon

The user's buddy icon, if available.

icon_checksum

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

icon_timestamp

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

icon_length

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

membersince

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

onsince

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

idle

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.

evil

Evil (warning) level for the user.

Some keys; namely, typing_status and icon_checksum, may be available for people who the user has communicated with but who are not on the user's buddylist.

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. You must call "commit_buddylist" to save the comment to the server. If COMMENT is undefined, the comment is deleted.

set_buddy_alias (GROUP, BUDDY[, ALIAS])

Set an alias for a buddy. You must call "commit_buddylist" to save the comment to the server. If ALIAS is undefined, the alias is deleted.

chat_invite (CHAT, MESSAGE, WHO)

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

chat_leave (CHAT)

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

chat_send (CHAT, MESSAGE)

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

CALLBACKS

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.

new_buddy_icon (OSCAR, SCREENNAME, BUDDY DATA)

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

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

buddy_icon_uploaded (OSCAR)

This is called when the user's buddy icon is successfully uploaded to the server.

buddy_icon_downloaded (OSCAR, SCREENNAME, ICONDATA)

This is called when a user's buddy icon is successfully downloaded from the server.

chat_closed (OSCAR, CHAT, ERROR)

Your connection to CHAT (a Net::OSCAR::Connection::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.

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.

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.

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::Connection::Chat object. CHATURL can be passed to the chat_accept method to accept the invitation.

chat_joined (OSCAR, CHATNAME, CHAT)

Called when you enter a chatroom. CHAT is the Net::OSCAR::Connection::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.

auth_challenge (OSCAR, CHALLENGE, HASHSTR)

OSCAR 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 OSCAR server sends an arbitrary number as a challenge. The client must respond with the MD5 digest of the concatenation of, in this order, the challenge, the password, and an additional hashing string (currently always the string "AOL Instant Messenger (SM)", but it is possible that this might change in the future.)

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

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

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

log (OSCAR, LEVEL, MESSAGE)

Use this callback if you don't want the log_print methods to just print to STDERR. It is called when even MESSAGE of level LEVEL is called. The levels are, in order of increasing 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, "readwrite" if "process_one" should be called in both cases, or "deleted" if the connection has been deleted.

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

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

CHATS

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

invite (WHO, MESSAGE)

Invite somebody into the chatroom.

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

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

part

Leave the chatroom.

url

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

name

Returns the name of the chatroom.

exchange

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

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

TYPINGSTATUS_STARTED

TYPINGSTATUS_TYPING

TYPINGSTATUS_FINISHED

Net::AIM Compatibility

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

• No get/set method.

• No newconn/getconn method.

• No group parameter for add_permit or add_deny.

• Many differences in chat handling.

• No chat_whisper.

• No encode method - it isn't needed.

• No send_config method - it isn't needed.

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

• No normalize method - it isn't needed. Okay, there is a normalize function in Net::OSCAR::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 some methods that may or may not be useful to you.

get_filehandle

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

process_one (CAN_READ, CAN_WRITE, HAS_ERROR)

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

session

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

HISTORY

• 1.00, 2004-01-03

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

  • Fixed handling of idle time (zoyboy22)

  • More flexible signon method

  • Added buddy alias support

  • Buddy icon support

  • Typing notification support

  • mac.com screenname support

  • Support for communicating with ICQ users from AIM

  • iChat extended status message support

  • We now emulate AOL Instant Messenger for Windows 5.2

  • We now parse the capabilities of other users

  • Attempts at Win32 (non-cygwin) support

• 0.62, 2002-02-25

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

  • A minor internal buddylist enhancement

  • snacsnatcher fixes

• 0.61, 2002-02-17

  • Fixed connection handling

• 0.60, 2002-02-17

  • Various connection_changed fixes, including the new readwrite status.

  • Added Net::OSCAR::Connection::session method

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

• 0.59, 2002-02-15

  • Protocol fixes - solves problem with AOL calling us an unauthorized client

  • Better handling of socket errors, especially when writing

  • Minor POD fixes

• 0.58, 2002-01-20

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

  • Added hooks to allow client do MD5 digestion for authentication (auth_challenge callback, Net::OSCAR::auth_response method)

• 0.57, 2002-01-16

  • Send callback_chat_joined correctly when joining an existing chat

  • Don't activate OldPerl fixes for perl 5.6.0

  • Ignore chats that we're already in

• 0.56, 2002-01-16

  • Fixed rate handling

  • Send multiple buddylist modifications per SNAC

  • Detect when someone else signs on with your screenname

  • Corrected attribution of ICQ support

• 0.55, 2001-12-29

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

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

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

  • Improved rate handling - new worrisome parameter to rate_alert callback

  • Removed remaining croak from OSCAR::Connection

  • Added is_on method

• 0.50, 2001-12-23

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

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

  • We can now join exchange 5 chats.

  • Fixes in modifying permit mode.

  • Updated copyright notice courtesy of AOL's lawyers.

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

• 0.25, 2001-11-26

  • Net::OSCAR is now in beta!

  • We now work with perl 5.005 and even 5.004

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

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

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

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

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

  • Fixed bad bug in log_printf

  • Buddylist error handling changes

  • Added chat_decline command

  • Signon, signoff fixes

  • Allow AOL screennames to sign on

  • flap_get crash fixes

• 0.09, 2001-10-01

  • Crash and undefined value fixes

  • New method: im_ok

  • New method: rename_group, should fix "Couldn't get group name" error.

  • Fix for buddy_in callback and data

  • Better error handling when we can't resolve a host

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

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

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

• 0.08, 2001-09-07

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

  • Many, many internal changes that I don't feel like 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

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

AUTHOR

Matthew Sachs <matthewg@zevils.com>.

CREDITS

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

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

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

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

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

Jonathon Wodnicki for additional help with typing status notification.

Roy Camp for loads of bug reports and ideas and helping with user support.

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

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

Jayson Baker for some last-minute debugging help.

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

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

Apple Computer for help with mac.com support.

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. iChat and Apple Computer are registered trademarks of Apple Computer, Inc. Net::OSCAR is not endorsed by, or affiliated with, Apple Computer, Inc or iChat.