NAME
    Net::OSCAR - Implementation of AOL's OSCAR protocol for instant
    messaging

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

            $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 requies "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 the section on "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 the Net::AIM
    Compatibility entry elsewhere in this document for more information.

EVENT PROCESSING
    There are two main ways for the module to handle event processing. The
    first is to call the the do_one_loop manpage 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
    the timeout manpage 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
    the process_connections manpage 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 = $my_readers;
            my $win = $my_writers;
            foreach my $oscar(@oscars) {
                    foreach my $socket($oscar->connections) {
                            vec($rin, fileno $socket, 1) = 1;
                            vec($win, fileno $socket, 1) = 1;
                    }
            }
            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 the do_one_loop manpage
        method. The default timeout is 0.01 seconds.

    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.

    signoff
        Sign off from the OSCAR service.

    debug (DEBUGLEVEL[, SCREENNAME DEBUG])
        Sets the debugging level. If this is non-zero, lots of information
        will be printed to standard error. In theory, higher debugging
        levels will give you more information, but right now it's all or
        nothing. 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. This is useful when you
        have multiple "Net::OSCAR" objects.

    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 the
        do_one_loop manpage 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.

        You must include the file numbers of all sockets returned by the the
        connections manpage method in both the readers, writers, and errors
        parameters of your select statement.

        See the the connections manpage method for a way to get the file
        descriptors to add to 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 the timeout manpage 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.

    add_permit (BUDDIES)
        Add buddies to your permit list. Note that this is the same as
        calling the add_buddy manpage with a group of "permit".

    add_deny (BUDDIES)
        See the add_permit manpage.

    remove_permit (BUDDIES)
        See the add_permit manpage.

    remove_deny (BUDDIES)
        See the add_permit manpage.

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

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

    add_buddy (GROUP, BUDDIES)
        Adds buddies to the given group on your buddylist.

    remove_buddy (GROUP, BUDDIES)
        See the add_buddy manpage.

    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.

    get_info (WHO)
        Requests a user's information, which includes their profile and idle
        time. See the the buddy_info manpage callback for more information.

    get_away (WHO)
        Similar to the get_info manpage, 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.

    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.

    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.

    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
        the section on "chat_accept" method for that.

    chat_accept (CHAT)
        Use this to accept 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, debug level, 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 the signon
        manpage method on the object returned by clone.

    connections
        Returns all the filehandles being used by this object. At present,
        these are symbol references generated by the "Socket" package, but
        that might change in the future. However, this will always be
        something you can use the "fileno" function on. This method is
        provided primarily for use with the the process_connections manpage
        method.

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

    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.

    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.

        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.

    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, DESCRIPTION, ERRNO, URL, REQDATA, FAMILY,
    SUBTYPE[, FATAL])
        Called when any sort of error occurs (except see the admin_error
        manpage below.) Note that most of these parameters, except for
        OSCAR, DESCRIPTION, and FATAL, are optional.

        CONNECTION is the particular connection which generated the error -
        the "debug_print" method of "Net::OSCAR::Connection" may be useful,
        as may be getting "$connection-"{description}>. DESCRIPTION is a
        somewhat nicely formatted error message. It is recommended that you
        just use this and ignore all the other parameters (except for FATAL)
        unless you want to get fancy.

        ERRNO is the error number - a list of error descriptions indexed by
        error number is returned by "Net::OSCAR::Common::ERRORS". URL is an
        http URL which the user can visit for more information about the
        error. REQDATA is some data the was associated with the request
        which generated the error. At present, it is a screenname for errors
        sending IMs or retrieving user information. FAMILY and SUBTYPE are
        the SNAC numbers of the request which generated the error and
        probably aren't too useful to you. FATAL is non-zero if the error
        was fatal - something like an invalid password on signon or the
        connection to OSCAR being severed.

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

    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 the
        admin_error manpage 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 the buddy manpage method.

    chat_buddy_in (OSCAR, SCREENNAME, CHAT, BUDDY DATA)
        SCREENNAME has entered CHAT. BUDDY DATA is the same as that returned
        by the the buddy manpage 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_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 the chat_send manpage.

    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 the chat_accept manpage 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 the section on "evil"
        method for more information on evils.

    buddy_info(OSCAR, SCREENNAME, BUDDY DATA)
        Called in response to a the get_info manpage or the get_away manpage
        request. BUDDY DATA is the same as that returned by the the buddy
        manpage 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.

    debug_print(OSCAR, MESSAGE)
        Use this callback if you don't want the debug_print methods to just
        print to STDERR.

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.

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

HISTORY
    *   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>

    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.

    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 Instant Messenger and AIM are registered
    service marks of AOL/Time Warner. America OnLine is a registered
    trademark of AOL/Time Warner. "Net::OSCAR" is not affiliated with,
    endorsed by, or supported by AOL.

