Documentation
License: This application is released under the Apache license. That means do what you want with it, just acknowledge me if you use any part of it, and don't call it the same name.
Requirements:
Perl - you need Perl installed, If using *nix, you should be good to go out of the box. If you are using Windows 9x, NT, 2000, XP, 2003 Server, etc., download and install ActivePerl.
Net::AIM - for AIM and ICQ. On *nix, Download the latest version of Net::AIM and untar into your site/lib dir. If your version of Perl is less than a few years old, running "perl -MCPAN -e "install 'Net::AIM'" from the command line should work on most systems. If you have trouble, read the MAN pages (!!).
On Windows, after installing ActivePerl, go to a command prompt and type "ppm" and hit enter. You will get a friendly prompt. Then enter "install Net-AIM" and you should be automagically squared away. If not, you are probably behind a firewall, in which case you can try to install it manually, as in the *nix instructions above.
OR
MSN.pm - for MSN Messenger. This is included with your download, or download from the author. Put it in your perl/site/lib directory. When unzipping, be sure you preserve directories, and make sure the "EventHandler.pm" file exists in that directory. The MSN protocol requires Time::HiRes and ssl support. SSL support can be gained with Crypt::SSLeay on Linux platforms, and with the included mshhtps library on windows. Reference page for Windows mshttps Perl modifications is here.
On Debian, 'apt-get install libcrypt-ssleay-perl' installs the required SSL support. (Thanks Joost).
Also check here is you still have problems and are using W2K sp3 or XP Pro.
OR
Net::YahooMessenger - for YIM. YIM also requires Crypt::PasswdMD5. Install like Net::AIM as above. Note: Since the last YIM protocol change in Oct 2003, these libraries have not worked.
OR
Net::Jabber - Install like Net::AIM as above
Depending on the kind of server you want to run, you will need a:
AIM name/pw: go to the AIM page and create a new name and password just for your server (click on the Big Red Button). You only need one, and it is very easy and painless.
OR
New MSN Passport.
OR
New ICQ Account.
OR
New YIM Account.
OR
New Jabber account (through your Jabber client)
Getting Started:
Open config.im and put in your settings. You will need to put in your screenname and password for the server, and can also set the text to appear in the server's profile, the session timeout, the multiple app text, and more.
At this point you can run sdba.pl from the command line and the server will start, log on, and serve all of the default applications that come with it. You may need to start with "perl sdba.pl"
Also, you can pass all the required logon information at the command line: sdba.pl [IMprotocol] [screenname] [password]
Basics to keep in mind:
- The filename of the first page of your applications needs to end with ".first"
- Other pages can end with anything, I have chosen ".im"
- Set $NEXTPAGE to direct the visitor to the next page
- Read the tutorials
- Learn a little Perl.
Browse the tutorials.
NOTE: YIM uses sdbayim.pl, not sdba.pl!
Special functions, outside of Perl:
imecho "string"; - echos out string to the text that will be sent as a response to the visitor's input. Double quotes ensure any variables get evaluated on-the-fly.
session (var); - tags a variable as a session variable - the value will be pre-filled and available in any page for the duration of the user's session. Note: this statement must occur before the variables are used!
include(file); - very similiar to Perl's require function, but tailored for other im pages. As a rule, require any perl libraries you want to use, and include impages. In practice, very similiar to PHP's include.
One-off commands
These allow the visitor (or admin) to send a particular command beginning with a "/" ("/about" in v 1.8 and up).
Logging
Message and conversation logs are stored in the logs/ directory, and are seperated by IM protocol.
Built-in subs
ACCESS_LIST(); It matches the visitor's screenname against a text file of names, one to a line, and only allows them to see the page if they are in the list. Does not require an argument, defaults to "access.lst" (in impages/) if not specified.
X; - Checks for a sinle "X" or "x" in $INCOMINGMSG, and ends the user's session and takes them abck to the first page if so. Add to the end of your scripts to give user a quick out.
SEND_IM($target, $message); - to allow you to initiate a session with another IM client.
SEND_PAGE($target, $message); - pages an MSN Mobile device for $target... obviously, this only works on MSN.
Writing subs for the Server
If you have a desire to add some universal server functionality, please send me what you have come up with. Built-in subs should be gateway-types of functions that can end or divert the user's session under the right conditions. They are stored in bin/ , and as rule are all caps.
Built-in subs have access to two vars that control the flow. Use these to decide what to do:
$Common::continue - Boolean, tells main script whether to stop. Defaults to 1 unless specifically set to 0.
$Common::ERRORMSG - what to send back if visitor cant continue
Browse bin/ACCESS_LIST.pl for an example with some documentation.
Writing one-off commands
All one-offs are in the "commands/" subdirectory. Please view about.pl, or use it as a template for your own.
The Visitor's Hash
Some developers will want to have access to this to see what other screennames are online, which leads to all sorts of odd possibilities, such as an IM msg-only BBoard, Match-making service, tech support coordination, etc. View the tutorial page for more info on how to go through the hash, and look at impages/BOTSTATS.first .
Known Bugs.
When using OPEN() (as in file) or require(), the base directory is the directory sdba.pl is in, so you will always need to add "impages/" to the start of any such file you wish to access with these functions.... This will be a fix in the future and will break any apps that work in a fix now, so please be aware.
| 
