From ace4c62c1999df7206731e637594f2da98bd52a8 Mon Sep 17 00:00:00 2001 From: tokul Date: Sun, 29 May 2005 08:33:18 +0000 Subject: [PATCH] documenting prefs functions git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@9470 7612ce4b-ef26-0410-bec9-ea0150e637f0 --- functions/db_prefs.php | 76 ++++++++++++++++++++++++++++++++++++++-- functions/file_prefs.php | 36 +++++++++++++++++++ functions/prefs.php | 15 ++++++-- 3 files changed, 122 insertions(+), 5 deletions(-) diff --git a/functions/db_prefs.php b/functions/db_prefs.php index ec2a099f..fe1d4253 100644 --- a/functions/db_prefs.php +++ b/functions/db_prefs.php @@ -27,8 +27,13 @@ * * @version $Id$ * @package squirrelmail + * @subpackage prefs + * @since 1.1.3 */ +/** @ignore */ +if (!defined('SM_PATH')) define('SM_PATH','../'); + /** Unknown database */ define('SMDB_UNKNOWN', 0); /** MySQL */ @@ -86,22 +91,61 @@ function cachePrefValues($username) { } /** - * Completely undocumented class - someone document it! + * Class used to handle connections to prefs database and operations with preferences * @package squirrelmail + * @subpackage prefs + * @since 1.1.3 */ class dbPrefs { + /** + * Table used to store preferences + * @var string + */ var $table = 'userprefs'; + /** + * Field used to store owner of preference + * @var string + */ var $user_field = 'user'; + /** + * Field used to store preference name + * @var string + */ var $key_field = 'prefkey'; + /** + * Field used to store preference value + * @var string + */ var $val_field = 'prefval'; + /** + * Database connection object + * @var object + */ var $dbh = NULL; + /** + * Error messages + * @var string + */ var $error = NULL; + /** + * Database type (SMDB_* constants) + * Is used in setKey(). + * @var integer + */ var $db_type = SMDB_UNKNOWN; + /** + * Default preferences + * @var array + */ var $default = Array('theme_default' => 0, 'show_html_default' => '0'); + /** + * initialize DB connection object + * @return boolean true, if object is initialized + */ function open() { global $prefs_dsn, $prefs_table; global $prefs_user_field, $prefs_key_field, $prefs_val_field; @@ -139,6 +183,10 @@ class dbPrefs { return true; } + /** + * Function used to handle database connection errors + * @param object PEAR Error object + */ function failQuery($res = NULL) { if($res == NULL) { printf(_("Preference database error (%s). Exiting abnormally"), @@ -150,7 +198,13 @@ class dbPrefs { exit; } - + /** + * Get user's prefs setting + * @param string $user user name + * @param string $key preference name + * @param mixed $default (since 1.2.5) default value + * @return mixed preference value + */ function getKey($user, $key, $default = '') { global $prefs_cache; @@ -167,6 +221,12 @@ class dbPrefs { } } + /** + * Delete user's prefs setting + * @param string $user user name + * @param string $key preference name + * @return boolean + */ function deleteKey($user, $key) { global $prefs_cache; @@ -190,6 +250,13 @@ class dbPrefs { return true; } + /** + * Set user's preference + * @param string $user user name + * @param string $key preference name + * @param mixed $value preference value + * @return boolean + */ function setKey($user, $key, $value) { if (!$this->open()) { return false; @@ -264,6 +331,11 @@ class dbPrefs { return true; } + /** + * Fill preference cache array + * @param string $user user name + * @since 1.2.3 + */ function fillPrefsCache($user) { global $prefs_cache; diff --git a/functions/file_prefs.php b/functions/file_prefs.php index 93b47143..bd180007 100644 --- a/functions/file_prefs.php +++ b/functions/file_prefs.php @@ -10,13 +10,21 @@ * * @version $Id$ * @package squirrelmail + * @subpackage prefs + * @since 1.2.5 */ +/** @ignore */ +if (! defined('SM_PATH')) define('SM_PATH','../'); + /** include this for error messages */ include_once(SM_PATH . 'functions/display_messages.php'); /** * Check the preferences into the session cache. + * @param string $data_dir + * @param string $username + * @since 1.1.3 */ function cachePrefValues($data_dir, $username) { global $prefs_are_cached, $prefs_cache; @@ -87,6 +95,11 @@ function cachePrefValues($data_dir, $username) { /** * Return the value for the preference given by $string. + * @param string $data_dir data directory + * @param string $username user name + * @param string $string preference name + * @param string $default (since 1.2.0) default preference value + * @return mixed */ function getPref($data_dir, $username, $string, $default = '') { global $prefs_cache; @@ -108,6 +121,9 @@ function getPref($data_dir, $username, $string, $default = '') { /** * Save the preferences for this user. + * @param string $data_dir data directory + * @param string $username user name + * @since 1.1.3 */ function savePrefValues($data_dir, $username) { global $prefs_cache; @@ -140,6 +156,9 @@ function savePrefValues($data_dir, $username) { /** * Remove a preference for the current user. + * @param string $data_dir data directory + * @param string $username user name + * @param string $string preference name */ function removePref($data_dir, $username, $string) { global $prefs_cache; @@ -155,6 +174,10 @@ function removePref($data_dir, $username, $string) { /** * Set a there preference $string to $value. + * @param string $data_dir data directory + * @param string $username user name + * @param string $string preference name + * @param mixed $value preference value */ function setPref($data_dir, $username, $string, $value) { global $prefs_cache; @@ -175,6 +198,10 @@ function setPref($data_dir, $username, $string, $value) { /** * Check for a preferences file. If one can not be found, create it. + * @param string $data_dir data directory + * @param string $username user name + * @param string $filename (since 1.2.0) preference file name. + * detects file name, if set to empty string. */ function checkForPrefs($data_dir, $username, $filename = '') { /* First, make sure we have the filename. */ @@ -228,6 +255,11 @@ function checkForPrefs($data_dir, $username, $filename = '') { /** * Write the User Signature. + * @param string $data_dir data directory + * @param string $username user name + * @param integer $number (since 1.2.5) identity number. + * parameter was used for signature text before 1.2.5. + * @param string $value (since 1.2.5) signature text */ function setSig($data_dir, $username, $number, $value) { // Limit signature size to 64KB (database BLOB limit) @@ -257,6 +289,10 @@ function setSig($data_dir, $username, $number, $value) { /** * Get the signature. + * @param string $data_dir data directory + * @param string $username user name + * @param integer $number (since 1.2.5) identity number + * @return string signature */ function getSig($data_dir, $username, $number) { $filename = getHashedFile($username, $data_dir, "$username.si$number"); diff --git a/functions/prefs.php b/functions/prefs.php index fb1c0c38..d92c76f0 100644 --- a/functions/prefs.php +++ b/functions/prefs.php @@ -10,8 +10,12 @@ * * @version $Id$ * @package squirrelmail + * @subpackage prefs */ +/** @ignore */ +if (!defined('SM_PATH')) define('SM_PATH','../'); + /** Include global.php */ require_once(SM_PATH . 'functions/global.php'); require_once(SM_PATH . 'functions/plugin.php'); @@ -47,6 +51,7 @@ if (isset($prefs_backend) && !empty($prefs_backend) && file_exists(SM_PATH . $pr * @param string datafile the name of the file to open * @param bool hash_seach default true * @return string the hashed location of datafile + * @since 1.2.0 */ function getHashedFile($username, $dir, $datafile, $hash_search = true) { @@ -96,6 +101,7 @@ function getHashedFile($username, $dir, $datafile, $hash_search = true) { * @param string dir the SquirrelMail datadir * @param string hash_dirs default '' * @return the path to the hash dir for username + * @since 1.2.0 */ function getHashedDir($username, $dir, $hash_dirs = '') { global $dir_hash_level; @@ -133,6 +139,7 @@ function getHashedDir($username, $dir, $hash_dirs = '') { * * @param string username the username to calculate the hash dir for * @return array a list of hash dirs for this username + * @since 1.2.0 */ function computeHashDirs($username) { /* Compute the hash for this user and extract the hash directories. */ @@ -147,10 +154,12 @@ function computeHashDirs($username) { } /** - * FIXME: Undocumented function + * Javascript support detection function + * @param boolean $reset recheck javascript support if set to true. + * @return integer SMPREF_JS_* constants + * @since 1.5.1 */ -function checkForJavascript($reset = FALSE) -{ +function checkForJavascript($reset = FALSE) { global $data_dir, $username, $javascript_on, $javascript_setting; if ( !$reset && sqGetGlobalVar('javascript_on', $javascript_on, SQ_SESSION) ) -- 2.25.1