NAME
    Net::Knuddels - www.knuddels.de protocol implementation.

SYNOPSIS
     use Net::Knuddels;

DESCRIPTION
    RTSL.

  CLASS Net::Knuddels::Protocol
    You must call the "destroy" method of this class when you no longer use
    it, as circular references will keep the object alive otherwise.

    new Create a new "Net::Knuddels::Protocol" object.

    $protocol->feed_data ($octets)
        Feed raw protocol data into the decoder.

    $msg = $protocol->encode_msg (@strings)
        Join the strings with "\0", encode the result into a protocol packet
        and return it.

    $protocol->register ($type => $callback)
        Register a callback for events of type $type, which is either the
        name of a low-level event sent by the server (such as "k" for dialog
        box) or the name of a generated event, such as "login".

    $protocol->destroy
        *MUST* be called to destroy the object, otherwise it will leak (no
        automatic cleanup).

  CLASS Net::Knuddels::Client
    Implement a Knuddels client connection.

    new Net::Knuddels::Client [IO::Socket::new arguments]
        Create a new client connection.

        Optional extra arguments:

           command_wait => $cb($client,$wait)
              This callback will be called with the client object
              and a time to wait. It must call the C<command_cb> method
              after the time specified, either by a blocking wait
              or via some event loop callback. The default implementation
              just does a blockign wait.

    $client->fh
        Return the fh used for communications. You are responsible for
        calling "$client->ready" whenever the fh becomes ready for reading.

    $client->ready
        To be called then the filehandle is ready for reading. Returns false
        if the server closed the connection, true otherwise.

    $client->command_cb
        Should be called by the "command_wait" callback when the timer has
        expired, to send a delayed command to the server.

    $client->command ($type => @args)
        Send a message of type $type and the given arguments to the server,
        ensures a proper rate-limit.

    $client->login ($url, $unknown)
        Send a 't' message. The default for $url is
        "http://www.knuddels.de/applet.html?v=87&c=-3" and $unknown is 3.

    $client->enter_room ($room, $nick, $password)
        Enters a room $room with $nick and $password. (for joining multiple
        rooms call this multiple times)

        NOTE: i won't allow joins to multiple rooms with different
        nick/password's, the java client reacted very confused.. don't know
        whether the server supports this.

    $client->send_whois ($nick)
        Sends a whois-request for $nick.

    $client->send_room_msg ($nick, $room, $message)
        Sends a private $message to $nick over $room.

    $client->send_priv_msg ($nick, $room, $message)
        Sends a private $message to $nick over $room.

    $client->send_join_room ($oldroom, $room)
        Sends the server a join command for $room. This will result in a
        room change from $oldroom to $room.

    $client->send_exit_room ($room)
        Exits $room completly. (can be seen as counter method for
        "enter_room ()")

    $client->register ($type => $cb)
        See Net::Knuddels::Protocol::register. The following extra events
        will be generated by this class:

           login
              set_nick can only be called _after_ a login event has occured.

           msg_room => $room, $user, $msg
              produced when a public message is uttered :)

           msg_priv => $room, $src, $dst, $msg
              personal message from $src to $dst. better use msg_priv_nondup,
              msg_priv_james or msg_priv_echo

           msg_priv_echo => $room, $src, $dst, $msg
              like msg_priv, but only for echoed messages

           msg_priv_james => $room, $src, $dst, $msg
              like msg_priv, but only for messages from James

           msg_priv_nondup => $room, $src, $dst, $msg
              like msg_priv, but avoids duplicate messages, echos and james.

           user_list => $room, $list
              the userlist of a channel named $room, a elmement of the list (a user)
              looks like: 
                 {
                   name => <name>, 
                   flag => <some flag i don't know what it means>, 
                   color => like /\d+.\d+.\d+/,
                   age   => /\d+/,
                   gender => /(f|m)/, 
                   picture => <the picture file to put behind the nick> 
                 }

           room_info => $room, $room_info
              some information about the $room:
              $room_info =
              {
                 picture => <some picturefile>
              }

           join_room => $room, $user
              join message of $user joined the room $room
              $user contains the user structure (see user_list).
      
           part_room => $room, $user
              part message of $user who left the room $room
              $user contains the user structure (see user_list).
        =cut

        sub register { my ($self, $type, $cb) = @_;

           $self->{proto}->register ($type, $cb);
        }

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/