NAME

Net::ICB -- Object oriented interface to an fnet server.

SYNOPSIS

        use Net::ICB qw(:client);
        
        $obj = new Net::ICB('user' => "chatter");
        ($type, @msg) = $obj->readmsg();
        exit unless ($type eq $M_PROTO);
        ($type, @msg) = $obj->readmsg();
        exit unless ($type eq $M_LOGINOK);

        my $msg = "Hello to the group";
        $obj->sendopen($msg);

DESCRIPTION

Net::ICB provides an object interface to a fnet/icb style chat server. FNET or ICB is an old chat protocol dating back to 1988. The original code was written in fortran on some godforsaken machine at UKY by Sean Casey. After the server was rewritten in C, various servers sprung up and died over the years. As of 1998, approximately 4 public servers run, the most popular of which peaks at ~150 people. See http://www.icb.net/ for more information.

PROTOCOL

The ICB protocol uses only ascii text. Packets consist of a single byte of size, followed by up to 254 bytes of data. The data block contains a leading byte describing the data type, the data itself, and a trailing null. Multiple fields in the data are delimited by \001.

Turn on debugging and it'll become obvious.

CLASS METHODS

new - create a new Net::ICB object.

    my $obj = Net::ICB->new( [host   => $hostname,]
                             [port   => $port,]
                             [user   => $username,]
                             [nick   => $nickname,]
                             [group  => $initialgroup,]
                             [cmd    => $command,]
                             [passwd => $password] );

Constructs a new Net::ICB object. A new object is returned on success, null on failure with a carp()'ed error message.

If any arguments are given, then new() calls connect() to establish a connection to an ICB server. Also see connect(). Any missing parameters are taken from the $DEF_* variables defined in Net::ICB.pm.

version - return the module version number.

    my $ver = Net::ICB->version();

    print $obj->version();

Returns the Net::ICB.pm version number. Also available as a instance method.

INSTANCE METHODS

connect - connect to an ICB server.

    $obj->connect( [host   => $hostname,]
                   [port   => $port,]
                   [user   => $username,]
                   [nick   => $nickname,]
                   [group  => $initialgroup,]
                   [cmd    => $command,]
                   [passwd => $password] );

Establishes a connection to an ICB server and sends a login packet. Any missing parameters are taken from the $DEF_* variables defined in Net::ICB.pm.

Unlike new(), connect() creates a connection even in the absence of arguments. Returns null on failure, check error() for specific failure code.

error - return the internal error string.

    die $obj->error() unless ($obj->connect());

Returns a string pertaining to the last error. This string is not cleared between operations: check the return code first.

clearerr - clear the internal error string.

    $obj->clearerr();

Clears the internal error string.

debug - set and return the internal debug level.

    $obj->debug(1);

    print "Debug: ", $obj->debug(), "\n";

With an argument, debug() sets the internal debug level and returns the new value. Without, the current debug level is returned.

fd - return socket file descriptor.

    fileno($obj->fd());

Returns the socket associated with the currect connection.

sendopen - send an open message to the current group.

    $obj->sendopen($msg);

Sends a public message to the user's current group. Returns null on failure, check error() for details.

sendpriv - send a private message to a particular user.

    $obj->sendpriv($nickname, $msg);

    $obj->sendpriv("$nickname $msg");

Sends a private message to a named user. Returns null on failure, check error() for details.

sendcmd - send an arbitrary command to the server.

    $obj->sendcmd("beep", $username);

    $obj->sendcmd("g", $groupname);

Sends an arbitrary command to the server. Available commands vary by server but most provide m, w, g, name. Try "/m server help" or "/s_help". Returns null on failure, check error() for details.

EXAMPLES

Alter the default variables from a client.

    use Net::ICB qw(:defaults);
    $DEF_HOST = "myhost.com";
    $DEF_GROUP = "myhost";

Check who is on a server.

    use Net::ICB qw(:client);
    my $who = Net::ICB->new(cmd => 'w');
        die unless $who;
        while (my ($type, @packet) = $who->readmsg()) {
                exit if ($type eq $M_EXIT);
        print "@packet\n";
    }

AUTHOR

John M Vinopal, banshee@resort.com