NAME
    Net::OSCAR - Implementation of AOL's OSCAR protocol for instant
    messaging (for interacting with AIM a.k.a. AOL IM a.k.a. AOL Instant
    Messenger - and ICQ, too!)

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

    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". "Test::More" is
    needed to run the test suite, and "XML::Parser" is needed to generate
    the XML parse tree which is shipped with released versions.

INTRODUCTION
  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. Source code from the Gaim client, the protocol
    analysis provided by the Ethereal network sniffer, and the website
    <http://iserverd1.khstu.ru/oscar/> were also used as references.

    This module strives to be as compatible with "Net::AIM" as possible at
    the API level, but some protocol-level differences prevent total
    compatibility. The TOC protocol implemented by "Net::AIM" is simpler
    than OSCAR and has official reference documentation from AOL, but it
    only provides a small subset of the full "OSCAR" functionality. See the
    section on "Net::AIM Compatibility" for more information.

  EVENT PROCESSING OVERVIEW
    Event processing is the implementation of "Net::OSCAR" within the
    framework of your program, so that your program can respond to things
    happening on the OSCAR servers while still doing everything else that
    you need it to do, such as accepting user input. There are three main
    ways for the module to handle event processing. The simplest is to call
    the do_one_loop method, which performs a "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 adjusted using the timeout method. This
    means that every time you call do_one_loop, it will pause for that
    interval if there are no messages from the OSCAR server. If you need
    lower overhead, want better performance, or need to handle many
    Net::OSCAR objects and/or other files and sockets at once, see
    "HIGH-PERFORMANCE EVENT PROCESSING" below.

  FUNCTIONALITY
    "Net::OSCAR" pretends to be WinAIM 5.5.3595. It supports remote
    buddylists including permit and deny settings. It also supports chat,
    buddy icons, and extended status messages. At the present time, setting
    and retrieving of directory information is not supported; nor are email
    privacy settings, voice chat, stock ticker, file transfer, direct IM,
    and many other of the official AOL Instant Messenger client's features.

  TERMINOLOGY
    When you sign on with the OSCAR service, you are establishing an OSCAR
    session.

  CALLBACKS
    "Net::OSCAR" uses a callback mechanism to notify you about different
    events. A callback is a function provided by you which "Net::OSCAR" will
    call when a certain event occurs. To register a callback, 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.

REFERENCE
  BASIC FUNCTIONALITY
   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)]);

    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:

        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.

        stealth
            Use this to sign on with stealth mode activated. Using this, as
            opposed to signon on without this setting and then calling
            "set_stealth", will prevent the user from showing as online for
            a brief interval after signon. See "set_stealth" for information
            about stealth mode.

        pass_is_hashed
            If you want to give Net::OSCAR the MD5 hash of the password
            instead of the password itself, use the MD5'd password in the
            password key and also set this key. The benefit of this is that,
            if your application saves user passwords, you can save them in
            hashed form and don't need to store the plaintext.

        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.

    signoff
        Sign off from the OSCAR service.

   CALLBACKS
    signon_done (OSCAR)
        Called when the user is completely signed on to the service.

  BUDDIES AND BUDDYLISTS
    See also "OTHER USERS" for methods which pertain to any other user,
    regardless of whether they're on the buddylist or not.

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

    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.

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

  PRIVACY
    "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
    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:

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

    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:

        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.

  OTHER USERS
    See also "BUDDIES AND BUDDYLISTS".

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

    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.

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

    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
    These methods deal with the user who is currently signed on using a
    particular "Net::OSCAR" object.

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

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

  EVENT PROCESSING
   METHODS
    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".

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

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

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

   CALLBACKS
    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:

        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.

  ERROR HANDLING
   CALLBACKS
    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.

    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.

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

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::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
    There are two programs included with the "Net::OSCAR" distribution.
    "oscartest" is half a reference implementation of a "Net::OSCAR" client
    and half a tool for testing this library. "snacsnatcher" is a tool
    designed for analyzing the OSCAR protocol from libpcap-format packet
    captures, but it isn't particularly well-maintained; the Ethereal
    sniffer does a good job at this nowadays.

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

USER INFORMATION
    Methods which return information about a user, such as "buddy", will
    return the information in the form of a hash. The keys of the hash are
    the following -- note that any of these may be absent.

    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.

    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.

ICQ-SPECIFIC INFORMATION
    ICQ support isn't nearly as well-tested as AIM support, and ICQ-specific
    features aren't being particularly actively developed. Patches for
    ICQ-isms are welcome. The initial patch enabling us to sign on to ICQ
    was provided by Sam Wong.

  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:

        basic

            nickname
            firstname
            lastname
            email
            gmt_offset
            authorization
            web_aware
            direct_connect_permissions
            publish_primary_email

        home

            city
            state
            phone_num
            fax_num
            address
            cell_phone_num
            zip_code
            country_code

        office

            city
            state
            phone_num
            fax_num
            address
            zip_code
            country_code
            company
            department
            position
            occupation
            office_website

        background

            age
            gender
            homepage
            birth_year
            birth_month
            birth_day
            spoken_languages
                This key is a listref containing the langauges the user
                speaks.

            origin_city
            origin_state
            origin_country
            marital_status

        notes
            This key is a simple scalar.

        email_addresses
            This key is a listref, each element of which is a hashref with
            the following keys:

            publish
            address

        interests
            This key is a listref, each element of which is a hashref with
            the following keys:

            category
            interest

        past_affiliations
            This key is a listref, each element of which is a hashref with
            the following keys:

            category
            affiliation

        present_affiliations
            As per above.

        homepage

            category
            keywords

HIGH-PERFORMANCE EVENT PROCESSING
    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 $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.

HISTORY
    *   1.905, 2004-08-28

        *   Reorganized documentation

    *   1.904, 2004-08-26

        *   Add $Net::OSCAR::XML::NO_XML_CACHE to prevent use of cached XML
            parse tree, and skip tests if we can't load Test::More or
            XML::Parser.

    *   1.903, 2004-08-26

        *   Generate XML parse tree at module build time so that users don't
            need to have XML::Parser and expat installed.

    *   1.902, 2004-08-26

        *   Fixes to buddy icon upload and chat invitation decline

        *   Increase performance by doing lazy generation of certain
            debugging info

    *   1.901, 2004-08-24

        *   Lots of buddylist-handling bug fixes; should fix intermittent
            buddylist modification errors and errors only seen when
            modifying certain screennames; Roy C. rocks.

        *   We now require Perl 5.6.1.

        *   Workaround for bug in Perl pre-5.8.4 which manifested as a
            "'basic OSCAR services' isn't numeric" warning followed by the
            program freezing.

        *   "add_group" and "remove_group" methods added.

        *   Fixed a potential memory leak which could impact programs which
            create many transient Net::OSCAR objects.

    *   1.900, 2004-08-17

        *   Wrote new XML-based protocol back-end with reasonably
            comprehensive test-suite. Numerous protocol changes; we now
            emulate AOL's version 5.5 client.

        *   Rewrote snacsnatcher, an OSCAR protocol analysis tool

        *   Reorganized documentation

        *   ICQ meta-info support: get_icq_info method, buddy_icq_info
            callback

        *   Stealth mode support: is_stealth and set_stealth methods,
            stealth_changed callback, stealth signon key

        *   More flexible unknown SNAC handling: snac_unknown callback

        *   Application can give Net::OSCAR the MD5-hashed password instead
            of the cleartext password (pass_is_hashed signon key). This is
            useful if your application is storing user passwords.

        *   Inability to set blocking on Win32 is no longer fatal. Silly
            platform.

        *   Fixed chat functionality.

    *   1.11, 2004-02-13

        *   Fixed presence-related problems modifying some buddylists

    *   1.10, 2004-02-10

        *   Fixed idle time handling; user info hashes now have an
            'idle_since' key, which you should use instead of the old 'idle'
            key. Subtract "idle_since" from "time()" to get the length of
            time for which the user has been idle.

        *   Fixed buddylist type 5 handling; this fixes problems modifying
            the buddylists of recently-created screennames.

    *   1.01, 2004-01-06

        *   Fixed buddy ID generation (problems adding buddies)

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

