Back Forward Table of Contents

Appendix A. Internal Function Reference

A.1 Complete List of Functions

To get the documentation of a certain function, click one of the links below. A grey box marks functions which primarily used by the server itself or are generated by other functions. Those functions take arguments difficult to guess, such as numeric addresses of internal SQL database entries.

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=cold
or 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&section=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&section=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_frame
The 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).


Back Forward Table of Contents