API functions
From XtConcordia
Our goal is to centralize many functions inside core/api.php so contributors can build fast and easy new modules. Normally there is no reason to put SQL-code inside a module, unless it's very specific for a module or panel. This page explains the details about all available functions inside core/api.php. Function names should be organised in an hierarchical structure. Function names begin with "api_".
Some functions are not located inside core/api.php but in core/functions.php because of their nature. These functions are in most cases only needed by the core of xtConcordia and not by modules or panels. If you don't agree why we define certain function as and API-function or as a core function, try to live with it. Some of them are historical and it would take too much time to change more than 30 modules just to rename the name of one function. The names of the core functions always start with "core_".
api_lan
LAN-party specific functions.
api_lan_active
Parameters: none
Returns the id of the currently active lan party. Only one lan party may be active at the same time. If no lan party is found, this function returns false.
api_lan_info
Parameters: $lanid
Returns an array with all necessary lan party information for the given lan party id. The array contains the following keys:
- name: Title of the lan party
- seats: available seats
- open:
- reg: the content id which contains the lan party regulations
- mail_reg: mail content which is sent during subscription
- mail_pay: mail content which is sent when payed
- location: where the lan party is held
- start: beginning of the lan party
- stop: end of the lan party
api_vote
Used for polls and vote systems.
api_vote_games_list
Parameters: none
Returns an array of game information (name and icon) located in the games table.
api_vote_games_result
Parameters: $userid, $lanid
Returns an array of the gamevotes from a specific user for the given lan party.
api_vote_games_results
Parameters: $lanid, $sortcol, $sortorder
Returns an array of all gamevotes for the given lan party. (... fixme)
api_vote_games_add
Parameters: $userid, $gameid, $lanid
Add a new game vote.
api_display
Functions which output directly some html-code to the browser. Usually nothing is returned.
api_display_winfull
Parameters: $title, $content
Output the html code located in $THEME_WINDOW to the browser and replaces %wintitle% and %wincontent% inside the html code by the given parameters. Nothing returned.
api_display_winstart
Parameters: $title
Output the first part of the html code located in $THEME_WINDOW to the browser. The code from %wincontent% until the end of the file is stripped off. Also replace %wintitle% with the given parameter. Nothing returned.
api_display_winstop
Parameters: none
Output the last part of the html code located in $THEME_WINDOW to the browser. The code from the beginning to %wincontent% is stripped off. Nothing returned.
api_users
Functions concerning more than one user at the same time.
api_user
Functions for user specific handles.
api_user_add
Parameters: $user
Add a new user the the database. The $user variable is an array which may containing the following keys:
- login
- nick
- name
- surname
- gender
- street
- streetnr
- streetbus
- zip
- city
- country
- clan
- lang
- tel
- gsm
- msn
- website
Before the insert is done, the following checks are performed automatically:
- validate login
- check if login already exists
- validate password
- verify birthday
When a new user is added, the account is assigned a magic number and set to invalid until e-mail verification has completed. Admin and RankId are also set to false.
This function returns an array in case of failure, or if succesful the userid of the new user.
api_user_birthdaycheck
Parameters: $date
Verifies if the given string is a valid date. The date should also be between the 'birthday_upper' and 'birthday_lower' boundaries set in the constants table.
api_user_addgroup
Parameters: $userid, $groupid
Adds the given user id to a group. This function doesn't check if userid and/or groupid (already) exist (fixme). Returns true if succesful.
api_user_update
Parameters: $userid, $info
Used to update fields in Users table. The $info variable should be an array where each array key contains an SQL-field of the Users table. Returns true if succesful.
api_user_validlogin
Parameters: $login
Returns true if a valid login (e-mail address) was given. This function only test for allowed characters. It doesn't check if the login exists in the system. Use this function to eliminate SQL-injection attacks.
api_user_validpwd
Parameters: $pwd
Returns true if the given password (clear text) matches the predefined criteria. The system only allows passwords containing only numbers and letters (case sensitive). The minimum/maximum length are defined in the constants table ('password_min' and 'password_max').
api_user_getid
Parameters: $login
Returns the id for the given login. You should validate $login first (using api_user_validlogin) before calling this function. If the given $login can't be found, false is returned instead.
api_user_activate
Parameters: $userid
Set the valid flag in Users table for the given user id. Only valid users can login into the system.
api_user_getmagic
Parameters: $userid
Returns the magic number for the given user id. This magic number is a large random number which is sent into the activation link to the user by e-mail. Using this magic number, a user confirms he is using a valid e-mail address.
api_user_checkpwd
api_user_changepwd
api_subs
Functions to handle subscriptions for a LAN-party.
api_subs_finduser
Parameters: $userid
Returns true if given $userid is subscribed for the current active lan.
api_subs_adduser
Parameters: $userid, $state, $arrived
Adds the $userid to the active lan with $state and $arrived option. Returns true if addition is okay.
api_subs_stats
Parameters: $lanid
Returns subscription statistics for the given lan party. The return array has the following keys: 'seats' (available seats), subs, 'subs' (subscribed users) and 'pay' (total of payed users).
api_cc
Credit card functions
api_cc_present
api_misc
All other functions which can't be located elsewhere.
api_misc_timestamp_to_date
Parameters: $timestamp
Returns a MySQL timestamp converted into a human readable date.
api_misc_readhtml
Parameters: $filename
Returns the content of a file. Preferrable to use $CMSPATH to construct the correct relative path.
api_misc_strreplace
Parameters: $str, $array
Function to replace text within a string. Each entry in $array contains an other array where key '0' defines the text to be replaced, and key '1' the text to be replaced with. Returns the new string after all replacements are done.
api_misc_random
Parameters: none
Returns (the hash of) a random number.
api_misc_sendmail
Parameters: $dest, $bcc, $subject, $body
This functions sends one e-mail ($subject / $body). You can have multiple destinations (array $dest) as well as multiple BCC destinations (array $bcc). Please configure 'mail_servers' (comma seperated list of SMTP-servers), 'mail_from' (e-mail) and 'mail_fromname' (friendly name) in the constants table.
Returns true if sent succesfully.
api_misc_sendmassmail
Parameters: $bcc, $subject, $body
Use this function to send out a mailinglist. The $bcc variable contains the list of destinations. Each entry in this array contains another array where the '0'-key holds the e-mail address and the '1'-key the friendly name the user. Use $subject and $body to store the mail content (no HTML support for now, only plain text mails).
The amount of destinations in BCC for one mail message is defined in 'mai_bccmax' in the constants table. Each mail should have at least one destination. Therefor we use the constants 'mail_listfrom' (e-mail) and 'mail_listfromname' (friendly name) which are stored in the constants table.
$return[0] is false if everything has been sent succesful. If not, $return[0] is true where the rest of the array contains the list of failed destinations.
api_misc_sponsors
api_addon
Specific function for addons (non-xtConcordia code).
api_addon_tinymce
Parameters: none
Returns a string with HTML-code which can be used in conjunction with form text areas to display a WYSIWYG-editor.
