All functions are used somewhere in the Hawkeye sample pages, so take a look there if you have problems understanding this documentation. Remember that there are two ways to execute a function: By entering the URL directly on the browser's command line
http://your.host.name/bbs?action=testcgi&coffee=hot&tea=coldor by creating a .bbs file which contains a command like
<!--/bbs?action=testcgi&coffee=hot&tea=cold-->Which one you choose is up to you. Creating .bbs files is often more flexible because it allows you to specify the page's background and font size and lets you add your own elements to the page.
addfile
Description
| Adds a new file to the database. The specified file must already have
been placed in the /incoming directory when this function is
called. Otherwise, or if some of the parameters are incorrect, the
function will fail.
| Parameters
| file, section, title, descr
| Sample
| /bbs?action=addfile&file=archive_name.zip§ion=misc&title=My_Title&descr=Some+Description
| Sample Page
| /files/addfile.htm
| |
adduser
Description
| Adds a new user record to the database. Takes several parameters
to create his profile. The new user will be a member of the
entry_group as specified in the system configuration table.
Note that there are various restrictions placed on the format
of the parameters, for example that the lastname may not contain
spaces and the password must be at least 4 characters in length.
| Parameters
| login, firstname, lastname, password1, password2, street, zip, town, country, phone, fax, email
| Sample Page
| /login.htm
| |
changeuser
Description
| Modifies an existing user record. The list of parameters is
exactly the same as for the adduser
function. Group memberships are not touched.
| Parameters
| login, firstname, lastname, password1, password2, street, zip, town, country, phone, fax, email
| Sample Page
| /login.htm
| |
deletedb
Description
| Delete a database entry. Links to this function are usually
generated only by the editdb function.
If the verify parameter is not specified, the function
will exit with a fail status and ask the user
if he is sure he wants to delete the database entry.
| Parameters
| id, what, [verify], [newgroup]
| Sample Page
| see system administrator's tools
| |
delfile
Description
| Delete an entry in the file database as well as the file
on disk. Links to this function are usually generated only
by the editfile function.
| Parameters
| id
| Sample Page
| see file area
| |
delmail
Description
| Delete a mail message from the mail database. Links to
this function are usually generated only by the
showmail function.
| Parameters
| id
| Sample Page
| see email area
| |
delnews
Description
| Delete a news message from the newsgroup database. Links
to this function are usually generated only by the
shownews function.
| Parameters
| id
| Sample Page
| see news area
| |
editdb
Description
| Displays a database record in an HTML form ready for editing.
Links to this function are usually generated only by the
showdb function.
| Parameters
| id, what
| Sample Page
| see system administrator's tools
| |
editfile
Description
| Displays a file information record in an HTML form ready
for editing. Links to this function are usually generated
only by the findfile function.
| Parameters
| id
| Sample Page
| see file area
| |
findfile
Description
| Searches the file database and displays the search results.
The parameter section specifies a file area to limit
the search to. title contains one more more space-seperated
key words to use as a full-text search on the file descriptions.
Both parameters may contain the wild cards ? and *. The optional
age (counted in days) is used to exclude old files from the
search.
| Parameters
| section, title, [age]
| Sample
| /bbs?action=findfile§ion=misc.tools&title=calendar
| Sample Page
| /files/findfile.htm
| |
insertdb
Description
| Inserts a new record into the database and displays it ready
for editing, similar to the editdb function.
The parameter what may be one of users, groups,
newsgroups, chatboards, directories, functions, mimetypes,
config, aliases.
| Parameters
| what
| Sample
| /bbs?action=insertdb&what=chatboards
| Sample Page
| /admin/index_sysop.htm
| |
listgroups
Description
| Displays a list of all newsgroups the user has read access
to. If amount is specified, this value is passed on
to the listnews function.
| Parameters
| [amount]
| Sample
| /bbs?action=listgroups&amount=1000
| Sample Page
| /news/news_list.bbs
| |
listhomes
Description
| Displays a list of all homepages available on the system.
Each time a new homepage is created using the FTP server
(see chapter 3.10), the
server adds the user to this list. If the homepage directory
is removed, the user is deleted from the list again. If you
plan to use this function (which can save you a lot of
work, actually), you should never create or delete homepage
directories using your admin login. In this case,
Hawkeye will not recognize that you have modified a different
user's homepage status, and thus will not be able to update
the list generated by this function.
| Parameters
| -
| Sample
| /bbs?action=listhomes
| Sample Page
| /homes.bbs
| |
listmail
Description
| Displays a list of mails, containing links to the
showmail function. The optional
parameter amount may either be the string new,
if you want to display only mails which have not been read
yet, or any number to limit the list's size. If you
want all mails to be displayed, just set amount to
1000 or something even higher.
| Parameters
| [amount]
| Sample
| /bbs?action=listmail&amount=new
| Sample Page
| /mail/email_new.bbs
| |
listnews
Description
| Displays a list of news messages of a certain newsgroup.
Links to this function are usually only created by the
listgroups function. The optional
parameter amount (which may be specified in the call
to listgroups and is passed on to this function), may
either be the string new, if you want to display
only messages which have not been read yet, or any number
to limit the list's size. If you want all messages to be
displayed, just set amount to 1000 or something even
higher.
| Parameters
| id, [amount]
| Sample Page
| see news area
| |
sendmail
Description
| Sends an email (either an internal mail to another user
or an Internet mail, depending on the recipient address).
The to parameter specifies the recipient address,
which should be the name of another user of the system
or a valid Internet mail address (if the system is
configured to relay Internet mail). subject is the
subject line of the message, and body contains the
message itself. The optional ref parameter is used
only by the server itself to generate message
dependancies.
| Parameters
| to, subject, body, [ref]
| Sample
| /bbs?action=sendmail&to=admin&subject=Hi&body=Hello+World
| Sample Page
| /mail/email_head.htm
| |
sendnews
Description
| Posts a news message to a newsgroup. The to parameter
specifies the name of the newsgroup, subject is the
subject line of the message, and body contains the
message itself. The optional ref parameter is used
only by the server itself to generate message
dependancies.
| Parameters
| to, subject, body, [ref]
| Sample
| /bbs?action=sendnews&to=talk.misc&subject=Hi&body=Hello+World
| Sample Page
| /news/news_head.htm
| |
showchat
Description
| Displays the contents of a chat board. The board
parameter specifies the name of the chat board, amount
is the number of lines to be displayed. Messages older than
five minutes are not displayed, anyway.
| Parameters
| board, [amount]
| Sample
| /bbs?action=showchat&board=chat.general&amount=20
| Sample Page
| /chat/chat_general.bbs
| |
showdb
Description
| Displays a database table. The output will contain links
to the editdb function.
The parameter what may be one of users, groups,
newsgroups, chatboards, directories, functions, mimetypes,
config, aliases. The parameter name may be used in conjunction
with the users table to specify only a specified user to
be displayed. group is the same when displaying the user
groups. If adduser is used when printing the
users database, only users which have the Created
by adduser... remark get displayed.
| Parameters
| what, [group], [name], [adduser]
| Sample
| /bbs?action=showdb&what=users
| Sample Page
| /admin/index_sysop.htm
| |
showmail
Description
| Displays a mail message from the mail database. Links to
this function are usually generated only by the
listmail function.
| Parameters
| id
| Sample Page
| see email area
| |
shownews
Description
| Displays a news message from the news database. Links to
this function are usually generated only by the
listnews function.
| Parameters
| id
| Sample Page
| see news area
| |
sweepdb
Description
| Cleans the database. Old mail, news and chat messages
are removed according to the specified ttl (time to
live) values in the system configuration.
| Parameters
| -
| Sample
| /bbs?action=sweepdb
| Sample Page
| /admin/index_sysop.htm
| |
sysinfo
Description
| Displays some information about the system. This function
is supposed to be used in a .bbs file because
output contains nothing but a small string or number.
The what parameter may be one of newemail,
nrofusers, userlist, version to display the number
of unread mails, the number of users on the system,
the list of users, or the version number of the Hawkeye
server, respectively.
| Parameters
| what
| Sample
| /bbs?action=sysinfo&what=version
| Sample Page
| /system/sysinfo.bbs
| |
templatemail
Description
| Displays an HTML form used to write a mail message. This is
in a way a more comfortable interface to the
sendmail function. The
parameters to, subject and body can be used to insert
pre-defined values into the form. reply is an
internal parameters only used in links generated by
the showmail function.
| Parameters
| [to], [subject], [body], [reply]
| Sample
| /bbs?action=templatemail&to=admin
| Sample Page
| /mail/email_head.htm
| |
templatenews
Description
| Displays an HTML form used to write a news message. This is
in a way a more comfortable interface to the
sendmail function. The
parameters to, subject and body can be used to insert
pre-defined values into the form. reply is an
internal parameters only used in links generated by
the showmail function.
| Parameters
| [to], [subject], [body], [reply]
| Sample
| /bbs?action=templatenews&to=talk.misc
| Sample Page
| /news/news_head.htm
| |
testcgi
Description
| A helpful command to test the way Hawkeye parses
function parameters. Accepts any parameters you
pass to it, and displays them in a HTML table.
| Parameters
| any
| Sample
| /bbs?action=testcgi&foo=bar&mickey=mouse&donald=duck
| |
updatedb
Description
| Updates a database record. Links to this function are
usually only generated by the editdb
function.
| Parameters
| id, what, [special], [fromgroup], <field_???>
| Sample Page
| see administrator's tools
| |
updatefile
Description
| Updates a file entry in the file database. Links to this function
are usually only generated by the editfile
function.
| Parameters
| id, title, descr, visible
| Sample Page
| see file area
| |
userinfo
Description
| Similar to the sysinfo function, this
command is used to display information about the user himeself.
The parameter what may be one of login, firstname,
lastname, street, zip, town, country, phone, fax, email.
| Parameters
| what
| Sample
| /bbs?action=userinfo&what=firstname
| Sample Page
| /mail/change.bbs
| |
whoison
Description
| Displays a list of users who have been online at the server
during the last minutes. This can even be used to check
large time intervals, for example 10080 minutes, which is
the equivalent of one week. :-) If the location
parameter is defined, the list will contain the town and
country of each user. Please check the legal situation of
your server before providing these features, as different
countries have restrictions on the amount of information
you may make available to the public. The optional
chatboard parameter displays only the users who are
active in a certain chat board.
| Parameters
| [minutes], [location], [chatboard]
| Sample
| /bbs?action=whoison&minutes=10&location=1
| Sample Page
| /mail/sysinfo.bbs
| |
writechat
Description
| This function will display a small text field used to
post a message to a chat board. Usually, you will first
use it without the message parameter. Once the
user has entered some text, the function is re-displayed
ready for accepting the next line of text.
| Parameters
| board, [message], [color]
| Sample
| /bbs?action=writechat&board=chat.general
| Sample Page
| /chat/chat_general.htm
| |
A.2 Additional Function Parameters
There are a few parameters which have a global meaning and thus can be
used with any of Hawkeye's functions. Take the following example:
/bbs?action=listgroups&amount=1000&target=left_frame&target2=main_frameThe listgroups function will produce a list of active newsgroups. This list will contain links to the listnews function so that the contents of a newsgroup are displayed when the user clicks on its name. The target=left_frame tells the server to direct the output of the links generated by the listgroups function to a frame called "left_frame". The next function, the one generated by listnews, will then place its output into "main_frame" because of the statement target2=main_frame. This may sound somewhat confusing - again our recommendation is to take a look at the sample pages (particularly the email and news areas).