The PhotonAPI Reference Guide
PhotonAPI provides robust methods for establishing connections, presenting text IO, and managing users that are connecting to a PhotonAPI built application. PhotonAPI is not limited to the creation of BBS systems, it can be used in an unlimited number of ways. Examples of it's use are visible in games like PhotonMUD, or even in smaller applications like YogiBOT. It can be used as an interface for any number of multiuser applications.
Configuration Variables: The following variables must be defined in a configuration file presented to the application, or in the main application itself. The variables must be defined prior to calling the modules into memory.
## Main BBS Path
$config{'home'}="/PATH/TO/APPLICATION";
## BBS Bin path (Currently unused)
$config{'bin'}="/bin";
## BBS Data path
$config{'data'}="/data";
## Pager / Teleconference message path
$config{'messages'}="/data/messages";
## Node information path
$config{'nodes'}="/data/nodes";
## Ansi & text files
$config{'text'}="/data/text";
## BBS Skin file
$config{'themes'}="/data/themes";
## User information path
$config{'users'}="/data/users";
## Script bin -> Path to door scripts
$config{'sbin'}="/sbin";
## Node info -> Drop files etc
$config{'doors'}=$config{'home'}."/doors";
## Passchr to echo at password prompt
$config{'passchr'}="*";
## Default Skin
$config{'theme'}="Your Theme File";
## Public/Private BBS
$config{'public'}="1";
## Force Full Name
$config{'usefullname'}="1";
## Force User's phone number
$config{'usephonenum'}="1";
## BBS's Name
$config{'systemname'}="Your BBS, or Application name";
## Sysop's Name
$config{'sysop'}="Your Handle, or Sysop";
## User account the application runs as
$config{'unixuser'}="chat";
## Default Sec level
$config{'defsecurity'}="10";
## Default Teleconference Channel
$config{'defchannel'}="MAIN";
## Default User selected skin
$config{'deftheme'}="Your Theme File";
## Teleconference Admin security level (hide / unhide ANY channels)
$config{'chanop'}="50";
## Delay (seconds) between processing events while waiting for commands
## Shouldn't need to change the event delay, it should handle hundreds
## of connections at "1"
$config{'eventdelay'}="1";
### System Information
## This defines the name of your server
$sysinfo{'servername'}="Your Application Name";
## Defines to the system the version of this application
$sysinfo{'version'}="Your Application Version";
## Defines your copyright notice
$sysinfo{'copyright'}="Your Copyright Notice";
## Defines the system host name as a system variable
chomp ($sysinfo{'host'}=`hostname`);
PhotonAPI System Functions:Function:doevents
Provides: Adds the capability of messaging. Doevents executes every 1 second while in the menuing system or a chat prompt, and processes incoming message events.
Arguments: None
Example: doevents();
Function:whosonline
Provides: Whosonline returns a listing of who is logged into the BBS system.
Arguments: None
Example: whosonline();
Function:iamat
Provides: Presents who's online data to the caller. It should be used in any major subroutine that takes a user away from the menuing system, or presents the user to the menuing system.
Arguments: Who, and Location
Example: iamat($info{'handle'},"Who's online");
Function:errorout
Provides: A clean method of trapping errors. It logs errors to logger, and sends the process to housekeeping to clean up open files before exiting.
Arguments: Error Condition
Example: open (in,"<$file") || errorout("Could not open $file");
Provides: The quit routine when invoked provides the user with an option to leave the system or stay online. It presents exita and exitb from the theme file, and waits for an input of Yes, No, or Relogin.
Function:quit
Arguments: None
Example: quit();
Function:bye
Provides: The housekeeping routine. When called, it presents goodbyemsg from the theme file, and then it does cleanup of any user activity and closes the process.
Arguments: None
Example: bye();
Function:colorize
Provides: Exposes the method of converting internal $COLOR codes to ANSI. It first checks to validate the user is capable of displaying ANSI by checking $info{'ansi'} and then processes color accordingly.
Arguments: None
Example: colorize();
Function:applytheme
Provides: applytheme reads in a theme file, and processes it into menu prompts.
Arguments: theme file
Example: applytheme('chizzle');
or
applytheme($info{'theme'});
Function:lockfile
Provides: Provides a simple file locking routine that enters a file into a locked state before it is opened by processes. If lockfile sees that a file is already locked it will sleep for 5 seconds, and forcefully remove the lock.
Arguments: filename
Example: lockfile($file);
open(in,"<$file") || errorout("Could not open $file");
Function:unlockfile
Provides: unlockfile provides a simple file unlock routine that compliments lockfile.
Arguments: filename
Example: open(in,"<$file") || errorout("Could not open $file");
unlockfile($file);
Function:readconfig
Provides: Exposes a method of reading in a configuration file, which is processed into key / value pairs. For security purposes readconfig requires files to be located in the BBS home/data directory or any subdirectory underneath.
Usage: readconfig("filename");
Example: readconfig("bbs.config");
Example config format: BBSNAME=Intergate
BBSOP=Fewt
Example usage: print "[".$config{'BBSNAME'}."]\n";
Example output: [Intergate]
Function:cbreak
Provides: Configures the process to mask keystrokes from display. It in essence turns echoing off. It is used by other functions for text entry processing.
Arguments: on, off
Example: cbreak(on);
$key=getc(STDIN);
cbreak(off);
Function:waitkey
Provides: Method for single keystroke entry. It's most common use could be to wait for a user to press c to continue at a more prompt.
Arguments: Default Key (accepts this input and uses it if a user just presses enter)
Example:print "Press (C)ontinue (S)top ? (C/s) ";
$result=waitkey("C");
Function:writeline
Provides: Function to display text on screen in an expected format. It will delete any characters in front of it as it displays output, and is configurable to include a carriage return.
Arguments: Text to output
CR (0 or 1)
Example: writeline ($WHT."You are the new owner of the ".$YLW.$channel.$WHT." channel ..",1);
Function:getline
Provides:
Function to input blocks of text with an expected format. It is used to process all non-instant input on the system.
Arguments: Input types: phone, dob, chat, password, text
Character Length (0-255)
Default input (any text)
Delete input on CR (0,1)
Example: $info{'location'}=getline(text,50,"The Internet",1);
Function:readfile
Provides: Exposes a function to present text files to users. It is commonly used to display help, welcome, or bulletin screens to users. Files read in and processed by readfile must be fully qualified, or located in the BBS home/data/text directory. readfile parses text files and replaces the following @CODES with system, or user data; or color information:
ActionColors: @LGN Light Green
@GRN Green
@RED Red
@BRN Brown
@PPL Purple
@LGR Light Grey
@GRY Grey
@YLW Yellow
@VLT Violet
@WHT White
@LTB Light Blue
@PNK Pink
@BLU Blue
@BLK Black
System Variables:@SYSNM - BBS name
@MENU - Currently selected menu
@NODE - Node Number
@CONNECT - IP Address connected from
@OS - BBS Operating System
@CPU - CPU Make and Model
@HOST - hostname
@SYSTEM - system
@SPEED - cpuspeed
@TIME - Current Time
@DATE - Current Date
@TOTALCALLS - Number of calls
@USER - Users Name
@RNAME - Users Real Name
@DOB - Date of Birth
@PHONE - Phone Number
@LOCAL - User Location
@CREDITS - Number of available Credits (unused)
@TLEFT - Time left in minutes (unused)
@ID - Users system ID index number
@SEX - M / F
@EMAIL - Users Email Address
@DND - Do not disturb
Arguments: Filename
Pause Prompt (0,1)
Absolute Path (0,1)
Example: readfile($info{'home'}."/".$info{'text'}."/welcome".$info{'ext'});
readfile("telehelp.txt",1);
readfile("$config{'home'}$config{'messages'}/teleconf/$channel/message",1,1);
Function:pause
Provides: Standardized wait for key to continue prompt that can be re-used anywhere on the system. It reads the pause prompt text from the pause text in the theme, and waits for (C)ontinue, (N)o Pause, or (Q)uit. pause returns the key pressed to the caller.
Arguments: None
Usage: pause();
Function:hi
Provides: Adds the the method of detecting user connection information. It performs the following operations:
Detects Telnet or SSH connection
Determines the connection type as local or IP
Filters scp or sftp connections
Checks for duplicate IP, and kills all connections (if configured)
Detects ANSI capability
Assigns a node number
Checks IP against a list of banned IP addresses
Updates the total calls file if it exists
Arguments: None
Example: hi();
authenticate();
Function:logger
Provides: Provides a common logging method. It will send logs to the bbs's host via syslog. Logs are presented to syslog as local6.notice. It is important that syslog be modified to accept logs from local6.
Arguments: Log data
Example: logger($info{'handle'}." Logged off!");
logger("Saved ".$info{'handle'}." to record number ".$info{'id'});
PhotonAPI User functions:Function:authenticate
Provides: Exposes a common framework for authenticating users. authenticate performs the following functions:
Displays login from the theme file
Accepts users handle, or NEW
Submits new user requests to newuser()
Determines if the user is local, if so:
Assigns the unix account name as the handle
Bypasses the password prompt
Processes a new user if user does not exist
Authenticates remote users
Arguments: None
Example: authenticate()
iamat($info{'handle'},"Heading to Chat");
Function:finduser
Provides: Provides a method of determining if a user exists on the system. If the user is found in the database, the user record is loaded into the system. finduser then returns "valid" or "invalid" based on the result of the search.
Arguments: None
Example: $info{'handle'}=getline(text,16,"",1)
$usercheck=finduser();
Function:finduserid
Provides: Searches the users.dat file, and returns the users ID. This function is only called by the updateuser function.
Arguments: None
Example: $info{'handle'}=getline(text,16,"",1);
$userid=finduserid();
Function:loaduser
Provides: Accepts the users ID as input, and loads the user record into memory. The user record is then accessible via the $info{} hash.
Arguments: User ID
Example: loaduser($id);
Function:updateuser
Provides: Updateuser provides the save function. It writes any new user data to the users .dat file.
Arguments: None
Example: updateuser();
Function:newuser
Provides: Provides a common method of adding new user accounts to the system. It is configurable by defining options in the configuration file, or the main application module itself. The following actions are taken by newuser:
Determine if it is a closed system (if so, hang up)
Present welcome.txt, and the agree prompt if it exists
Asks ANSI / ASCII choice (required)
Asks for users Full Name (if required)
Asks for phone number (if required)
Asks for location information (required)
Asks for email address (requred)
Asks for DOB (required)
Asks for Sex (required)
Asks for a Handle (required, bypassed if local)
Asks for and sets the new user's password
Arguments: None
Example: newuser();
Function:chansi
Provides: Exposes a function to toggle ansi color on and off.
Arguments: None
Example: if ($command =~/ANSI/i) {
chansi();
writeline($RST,1);
goto main;
}
Function:chsex
Provides: Allows you to change your sex from M to F or from F to M. Suspect it won't be used often.
Arguments: None
Example: if ($command =~/SEX/i) {
chsex();
writeline($RST,1);
goto main;
}
Function:chphone
Provides: Changes the users phone number.
Arguments: None
Example: if ($command =~/PHONE/i) {
chphone();
writeline($RST,1);
goto main;
}
Function:chdob
Provides: Changes the users date of birth.
Arguments: None
Example: if ($command =~/DOB/i) {
chdob();
writeline($RST,1);
goto main;
}
Function:chrealname
Provides: Changes the users name.
Arguments: None
Example: if ($command =~/NAME/i) {
chrealname();
writeline($RST,1);
goto main;
}
Function:chpassword
Provides: Changes the users password.
Arguments: None
Example: if ($command =~/PASSWORD/i) {
chpassword();
writeline($RST,1);
goto main;
}
Function:chlocal
Provides: Changes the users location.
Arguments: None
Example: if ($command =~/LOCATION/i) {
chlocal();
writeline($RST,1);
goto main;
}
Function:chdnd
Provides: Toggles do not disturb. Do not disturb mode supresses messages sent to the user by other users.
Arguments: None
Example: if ($command =~/DND/i) {
chdnd();
writeline($RST,1);
goto main;
}
Function:chemail
Provides: Changes the users email address.
Arguments: None
Example: if ($command =~/EMAIL/i) {
chemail();
writeline($RST,1);
goto main;
}
Download the PhotonAPI - [
HERE ]
