NAME

VERSION

SYNOPSIS

        use Net::OSCAR qw(:standard);
        sub im_in {
                my($oscar, $sender, $message, $is_away) = @_;
                print "[AWAY] " if $is_away;
                print "$sender: $message\n";
        }
        $oscar = Net::OSCAR->new();
        $oscar->set_callback_im_in(\&im_in);
        $oscar->signon($screenname, $password);
        while(1) {
                $oscar->do_one_loop();
                # Do stuff
        }

INSTALLATION

HOW TO INSTALL

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

DEPENDENCIES

INTRODUCTION

ABSTRACT

EVENT PROCESSING OVERVIEW

FUNCTIONALITY

TERMINOLOGY

CALLBACKS

REFERENCE

BASIC FUNCTIONALITY

new ([capabilities => CAPABILITIES], [rate_manage => RATE_MANAGE_MODE])

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

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

signon (HASH)

signon (SCREENNAME, PASSWORD[, HOST, PORT]

Sign on to the OSCAR service. You can specify an alternate host/port to connect to. The default is login.oscar.aol.com port 5190.

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

signoff

Sign off from the OSCAR service.

signon_done (OSCAR)

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

BUDDIES AND BUDDYLISTS

findbuddy (BUDDY)

In scalar context, returns the name of the group that BUDDY is in, or undef if BUDDY could not be found in any group. If BUDDY is in multiple groups, will return the first one we find.

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

commit_buddylist

Sends your modified buddylist to the OSCAR server. Changes to the buddylist won't actually take effect until this method is called. Methods that change the buddylist have a warning about needing to call this method in their documentation. After calling this method, your program MUST not call it again until either the 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.

rename_group (OLDNAME, NEWNAME)

Renames a group. Call "commit_buddylist" for the change to take effect.

add_buddy (GROUP, BUDDIES)

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

remove_buddy (GROUP, BUDDIES)

See add_buddy.

add_group (GROUP)

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

remove_group (GROUP)

See add_group. Any buddies in the group will be removed from the group first.

groups

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

buddies (GROUP)

Returns the names of the buddies in the specified group in the user's buddylist. The names may not be formatted - that is, they may have spaces and capitalization removed. The names are "Net::OSCAR::Screenname" objects, so you don't have to worry that they're case and whitespace insensitive when using them for comparison.

buddy (BUDDY[, GROUP])

Returns information about a buddy on the user's buddylist. This information is a hashref as per "USER INFORMATION" below.

set_buddy_comment (GROUP, BUDDY[, COMMENT])

Set a brief comment about a buddy. You must call "commit_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.

buddylist_limits

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

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.

buddy_out (OSCAR, SCREENNAME, GROUP)

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

buddylist_error (OSCAR, ERROR, WHAT)

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

buddylist_ok (OSCAR)

This is called when your changes to the buddylist have been successfully commited.

buddylist_changed (OSCAR, CHANGES)

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

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

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

PRIVACY

add_permit (BUDDIES)

Add buddies to your permit list. Call "commit_buddylist" for the change to take effect.

add_deny (BUDDIES)

See add_permit.

remove_permit (BUDDIES)

See add_permit.

remove_deny (BUDDIES)

See add_permit.

get_permitlist

Returns a list of all members of the permit list.

get_denylist

Returns a list of all members of the deny list.

visibility

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

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 "is_stealth"/"set_stealth".

The visibility mode may be:

is_stealth

set_stealth STEALTH_STATUS

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

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

set_group_permissions (NEWPERMS)

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

group_permissions

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

OTHER USERS

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:

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.

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.

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_downloaded (OSCAR, SCREENNAME, ICONDATA)

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

typing_status (OSCAR, SCREENNAME, STATUS)

Called when someone has sent us a typing status notification message. See send_typing_status for a description of the different statuses.

im_ok (OSCAR, TO, REQID)

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

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

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

buddylist_in (OSCAR, FROM, BUDDYLIST)

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

buddy_info (OSCAR, SCREENNAME, BUDDY DATA)

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

THE SIGNED-ON USER

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.

profile

Returns your current profile.

set_away (MESSAGE)

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

set_extended_status (MESSAGE)

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

set_info (PROFILE)

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

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

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

set_icon (ICONDATA)

Sets the user's buddy icon. The "Net::OSCAR" object must have been created with the "buddy_icons" capability to use this. "ICONDATA" must be less than 4kb, should be 48x48 pixels, and should be BMP, GIF, or JPEG image data. You must call commit_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.

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

change_password (CURRENT PASSWORD, NEW PASSWORD)

Changes the user's password.

confirm_account

Confirms the user's account. This can be used when the user's account is in the trial state, as determined by the presence of the "trial" key in the information given when the user's 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.

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.

admin_error (OSCAR, REQTYPE, ERROR, ERRURL)

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

admin_ok (OSCAR, REQTYPE)

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

buddy_icon_uploaded (OSCAR)

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

stealth_changed (OSCAR, NEW_STEALTH_STATE)

This is called when the user's stealth state changes. See "is_stealth" and "set_stealth" for information on stealth.

extended_status (OSCAR, STATUS)

Called when the user's extended status changes. This will normally be sent in response to a successful set_extended_status call.

evil (OSCAR, NEWEVIL[, FROM])

Called when your evil level changes. NEWEVIL is your new evil level, as a percentage (accurate to tenths of a percent.) ENEMY is undef if the evil was anonymous (or if the message was 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.

FILE TRANSFER AND DIRECT CONNECTIONS

file_send SCREENNAME MESSAGE FILEREFS

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

EVENT PROCESSING

do_one_loop

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

process_connections (READERSREF, WRITERSREF, ERRORSREF)

Use this method when you want to implement your own "select" statement for event processing instead of using "Net::OSCAR"'s do_one_loop method. The parameters are references to the readers, writers, and errors parameters used by the select statement. The method will ignore all connections which are not "Net::OSCAR::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".

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

chat_join (NAME[, EXCHANGE])

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

chat_accept (CHATURL)

Use this to accept an invitation to join a chatroom.

chat_decline (CHATURL)

Use this to decline an invitation to join a chatroom.

chat_buddy_in (OSCAR, SCREENNAME, CHAT, BUDDY DATA)

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

chat_buddy_out (OSCAR, SCREENNAME, CHAT)

Called when someone leaves a chatroom.

chat_im_in (OSCAR, FROM, CHAT, MESSAGE)

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

chat_invite (OSCAR, WHO, MESSAGE, CHAT, CHATURL)

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

chat_joined (OSCAR, CHATNAME, CHAT)

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

chat_closed (OSCAR, CHAT, ERROR)

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

RATE LIMITS

rate_level (OSCAR, METHODNAME[, CHAT])

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

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

rate_limits (OSCAR, METHODNAME[, CHAT])

Similar to "rate_level". This returns the boundaries of the 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):

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

would_make_rate_level (OSCAR, METHODNAME[, CHAT])

Returns the rate level which your session would be at if "METHODNAME" were sent right now. See "rate_level" for more information.

rate_alert (OSCAR, LEVEL, CLEAR, WINDOW, WORRISOME, VIRTUAL)

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

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

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

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

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

MISCELLANEOUS

timeout ([NEW TIMEOUT])

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

loglevel ([LOGLEVEL[, SCREENNAME DEBUG]])

Gets or sets the level of logging verbosity. If this is non-zero, varing amounts of information will be printed to standard error (unless you have a "log" callback defined). Higher loglevels will give you more information. If the optional screenname debug parameter is non-zero, debug messages will be prepended with the screenname of the OSCAR session which is generating the message (but only if you don't have a "log" callback defined). This is useful when you have multiple "Net::OSCAR" objects.

See the "log" callback for more information.

auth_response (MD5_DIGEST[, PASS_IS_HASHED])

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

clone

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

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.

findconn (FILENO)

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

selector_filenos

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

icon_checksum (ICONDATA)

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

get_app_data ([GROUP[, BUDDY]])

Gets application-specific data. Returns a hashref whose keys are app-data IDs. IDs with high-order byte 0x0001 are reserved for non-application-specific usage and must be registered with the "libfaim-aim-protocol@lists.sourceforge.net" list. If you wish to set application-specific data, you should reserve a high-order byte for your application by emailing "libfaim-aim-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.

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.

auth_challenge (OSCAR, CHALLENGE, HASHSTR)

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

OSCAR uses an MD5-based challenge/response system for 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 . MD5(password) . HASHSTR. For instance, using the MD5::Digest module:

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

Note that this functionality is only available for certain 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:

ERROR HANDLING

error (OSCAR, CONNECTION, ERROR, DESCRIPTION, FATAL)

Called when any sort of error occurs (except see admin_error below and buddylist_error in "BUDDIES AND BUDDYLISTS".)

"CONNECTION" is the particular connection which generated the error - the "log_print" method of "Net::OSCAR::Connection" may be useful, as may be getting "$connection->{description}". "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.

snac_unknown (OSCAR, CONNECTION, SNAC, DATA)

Called when Net::OSCAR receives a message from the OSCAR server which it doesn't known how to handle. The default handler for this callback will print out the unknown SNAC.

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

CHAT CONNECTIONS

invite (WHO, MESSAGE)

Invite somebody into the chatroom.

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

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

part

Leave the chatroom.

url

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

name

Returns the name of the chatroom.

exchange

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

RATE LIMIT OVERVIEW

RATE MANAGEMENT MODES

TIME-DELAYED EVENTS

CONSTANTS

ADMIN_TYPE_PASSWORD_CHANGE

ADMIN_TYPE_EMAIL_CHANGE

ADMIN_TYPE_SCREENNAME_FORMAT

ADMIN_TYPE_ACCOUNT_CONFIRM

ADMIN_ERROR_UNKNOWN

ADMIN_ERROR_BADPASS

ADMIN_ERROR_BADINPUT

ADMIN_ERROR_BADLENGTH

ADMIN_ERROR_TRYLATER

ADMIN_ERROR_REQPENDING

ADMIN_ERROR_CONNREF

VISMODE_PERMITALL

VISMODE_DENYALL

VISMODE_PERMITSOME

VISMODE_DENYSOME

VISMODE_PERMITBUDS

RATE_CLEAR

RATE_ALERT

RATE_LIMIT

RATE_DISCONNECT

OSCAR_RATE_MANAGE_NONE

OSCAR_RATE_MANAGE_AUTO

OSCAR_RATE_MANAGE_MANUAL

GROUPPERM_OSCAR

GROUPPERM_AOL

TYPINGSTATUS_STARTED

TYPINGSTATUS_TYPING

TYPINGSTATUS_FINISHED

Net::AIM Compatibility

•

No get/set method.

•

No newconn/getconn method.

•

No group parameter for add_permit or add_deny.

•

Many differences in chat handling.

•

No chat_whisper.

•

No encode method - it isn't needed.

•

No send_config method - it isn't needed.

•

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

•

No normalize method - it isn't needed. Okay, there is a normalize function in "Net::OSCAR::Utility", but I can't think of any reason why it would need to be used outside of the module internals. "Net::OSCAR" provides the same functionality through the "Net::OSCAR::Screenname" class.

•

Different callbacks with different parameters.

MISCELLANEOUS INFO

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

USER INFORMATION

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_since

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

evil

Evil (warning) level for the user.

ICQ-SPECIFIC INFORMATION

ICQ METHODS

get_icq_info (UIN)

Requests ICQ-specific information. See also the "buddy_icq_info" callback.

ICQ CALLBACKS

buddy_icq_info (OSCAR, UIN, ICQ DATA)

The result of a "get_icq_info" call. Data is a hashref with the following keys, the value of each key is a either a hashref or undefined:

HIGH-PERFORMANCE EVENT PROCESSING

        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.

HISTORY

•

1.925, 2006-02-06

•

1.907, 2004-09-22

•

1.906, 2004-08-28

•

1.904, 2004-08-26

•

1.903, 2004-08-26

•

1.902, 2004-08-26

•

1.901, 2004-08-24

•

1.900, 2004-08-17

•

1.11, 2004-02-13

•

1.10, 2004-02-10

•

1.01, 2004-01-06

•

1.00, 2004-01-03

•

0.62, 2002-02-25

•

0.61, 2002-02-17

•

0.60, 2002-02-17

•

0.59, 2002-02-15

•

0.58, 2002-01-20

•

0.57, 2002-01-16

•

0.56, 2002-01-16

•

0.55, 2001-12-29

•

0.50, 2001-12-23

•

0.25, 2001-11-26

•

0.09, 2001-10-01

•

0.08, 2001-09-07

•

0.07, 2001-08-13

•

0.06, 2001-08-12

•

0.05, 2001-08-08

•

0.01, 2001-08-02

SUPPORT

AUTHOR

CREDITS

LEGAL