Net::ISCABBS - Perl interface to the ISCABBS system
use Net::ISCABBS;
# Create a new BBS object by logging in with your account
# If you leave off the login and password, you'll log in with
# unauthenticated rights, NOT as the user "Guest".
my $bbs = new Net::ISCABBS(login=>"Bugcrusher", password=>"mypass");
# Show the forums that you are a member of. The hash key is the
# forum number. Doesn't work for unauthenticated users.
my %forums = $bbs->forums("joined");
# Get the number for all joined forums with unread messages.
my %unread = $bbs->forums_with_unread;
foreach my $forum (sort keys %unread)
{
print "There are $unread{$forum}->{unread} unread messages in $unread{$forum}->{name}\n";
}
# Make the Unix forum your active one. You can jump by number or by
# name.
my $forum = $bbs->jump("Unix") or die "Couldn't join forum!\n";
print "Joined Forum $forum->{name}, adminned by $forum->{admin}\n";
# Get the forum information for your active forum
my $fi = $bbs->get_fi;
print "Forum Info author is $fi->{fi_author}\n";
print "\n$fi->{body}\n\n";
# Read all new messages in the current forum
while (my $message = $bbs->read)
{
print "\n\nNEW MESSAGE\n";
print "From: $message->{author}\n";
print "Date: $message->{date}\n";
print "$message->{body}\n";
}
# Post a message to Babble
$bbs->jump(3);
if ($bbs->can_post)
{
$bbs->post("I have something very insightful to say") or die;
}
else
{
print "You don't have permission to post here\n";
}
# Log out
$bbs->logout;
Established in 1989, ISCABBS has provided a virtual community for students of the University of Iowa and the Internet in general. Today ISCABBS is the world's largest free bulletin board system on the Internet, with over 5,000 active members. We have a validation structure to help prevent harassment while allowing for anonymity, a team of System Operators who help to maintain a near round the clock watch on activities, and nearly 200 discussion forums which cover a wide variety of topics, from the intensely technical to the sublimely silly.
The base code for ISCABBS is D.O.C. (Daves' Own Citadel), a telnet-based BBS code derived originally from Citadel. The D.O.C. code was written primarily by Dr. David Lacey, then a student at the University of Iowa. In 2001 the code for D.O.C. was released under the GNU General Public License. Several variants have already been developed from this base code.
ISCABBS offers Intra-BBS electronic mail and real-time instant messages between users and a variety of forums covering many areas of academic and social discussion, as well as general discussion forums.
ISCABBS is owned and maintained by the Iowa Student Computer Association at the University of Iowa in Iowa City, Iowa. This student group meets monthly during the school year and supports several projects.
A developer's interface to ISCABBS (raccdoc) was opened in September 2004. This module allows Perl coders to access that interface.
Most methods below return undef on failure and set $@, except when they don't.
This creates a new BBS object with the supplied parameters. All are optional - if you leave off the host and port, the defaults shown above will be used. If you do not supply the username and the password, you will gain access as an unauthenticated user (NOT the ISCABBS "Guest" account). That will disable a couple of methods involving joined forums, though, since you have to be authenticated to join some forums.
Returns the object on success, returns undef and sets $@ on failure.
Returns a hash of information about forums, specified by TYPE. If you omit the TYPE, you will get information about all forums that you can see.
The TYPE can be: all, private, public, todo, recent, joined. "joined" will probably be the most useful of the bunch. "todo" shows you forums with unread messages, but that is exposed via the $bbs->forums_with_unread method, so you'll probably want to use that instead of $bbs->forums("todo");
The hash returned is keyed by forum number, which itself is a hash reference containing the following information.
$forums{$i}->{name} - The ASCII forum name.
$forums{$i}->{lastnote} - The number of the last message posted in the forum.
$forums{$i}->{flags} - The permission flags for the forum.
Switches your active forum to the one specified. You can either jump based on forum number, or by the name of the forum (first match wins). Only one forum can be active at a time per connection.
Returns a hash reference that contains some or all the following keys:
$forum->{topic} - The forum number
$forum->{name} - The ASCII name of the forum
$forum->{lastnote} - The numeric message ID of the newest message in the forum.
$forum->{firstnote} - The numeric message ID of the oldest message in the forum.
$forum->{admin} - The ISCA username of the forum moderator.
Tests to see whether the current user is able to write in the current forum. Returns true if the user can write, undef if they cannot. This is a useful method if you want to provide different interfaces depending on whether or not the forum is writable.
Posts the text in $message to your current forum. Returns the post ID on success, undef on failure. For obvious reasons, this method will probably fail if you are not logged into the BBS, as no forums allow guest posting.
Performs an "XHDR" in your current forum, and returns an array of all post numbers in the forum. This is a less intensive operation than the "XHDR ALL" performed by get_forum_headers, so it should be used when you don't need the full post information.
Performs an "XHDR ALL" and returns a hash, where the keys are the post numbers and the value is a hash reference containing the following information:
$headers{$postnum}->{author} - The ISCABBS username of the author
$headers{$postnum}->{date} - The posting date
$headers{$postnum}->{subject} - A simple subject for the post, taken from the first few words.
The optional $rangestring gives the range of posts to get information about. It can be a single post ID ("31773") or a max-min range ("31770-31779"). If the $rangestring exists, only headers for the requested posts will be returned. Otherwise, all posts in a forum will be returned.
Returns a hash, where the keys are the forum numbers and the value is a hash reference containing the following information:
$unread{$forum_number}->{name} - The ASCII name of the forum
$unread{$forum_number}->{unread} - The count of unread messages in that forum.
$unread{$forum_number}->{firstnote} - The numeric message ID of the oldest message in the forum.
$unread{$forum_number}->{lastnote} - The numeric message ID of the newest message in the forum.
This method does not work if you are unauthenticated.
Returns a hash reference of the forum information for the active forum.
$fi->{fi_author} - The author of the forum information for the active forum
$fi->{last_updated} - The date that the forum information was modified
$fi->{body} - The text of the forum information
Gets the numeric message ID of the first message in your currently active forum that you have not read.
Returns the message ID on success.
Returns a hashref containing the message in your currently active forum. Arguments are a hash - if you provide the "message" argument, you will start reading from there. Otherwise, your first unread message is used. If the "dammit" option is true, and you have the proper forum permissions (FM or Sysop), you can get the author of an anonymous post.
The hashref contains the following fields:
$message->{author} - The author of the post.
$message->{date} - The date the post was made.
$message->{body} - The body of the post.
The $bbs->read method (as of 1.1) does NOT increment your "last read" counter, so you will need to call ->set_first_unread($postid) when you are done reading.
while (my $message = $bbs->read) { print "From: $message->{author}\n"; print "Date: $message->{date}\n"; print "$message->{body}\n"; } $bbs->set_first_unread($last_postid);
Sets the flag for your first unread message to the number specified in $messageid. Returns failure if the specified number is outside of the bounds of the first and last messages currently in the forum, success otherwise.
Deletes the post in your current forum specified by $postid. Returns true on success. Obviously, you must have permission to delete said post.
Sends a QUIT to the BBS and closes the TCP socket
Currently the module works in read-only mode. Posting and deleting are not yet working.
This is my first Perl module, so there are probably many things that could be done better. Patches welcome!
ISCABBS Website: http://www.iscabbs.com/
Telnet to bbs.isca.uiowa.edu to participate in ISCABBS.
For more information on the raccdoc interface, post in the The Future Of ISCA BBS> forum on ISCA.
H. Wade Minter, <minter@lunenburg.org> http://www.lunenburg.org/
Copyright 2004 by H. Wade Minter
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
