From 1da5dbefc31ce54d49e22d84fab8bc3a97d81e5b Mon Sep 17 00:00:00 2001 From: psc Date: Fri, 6 Nov 2009 16:26:22 +0000 Subject: [PATCH] Add API documentation to the config class Added doxygen tags to most of the config class functions. git-svn-id: https://oss.gonicus.de/repositories/gosa/branches/2.6-lhm@14783 594d385d-05f5-0310-b6e9-bd551577e9d8 --- trunk/gosa-core/include/class_config.inc | 147 +++++++++++++++++++++-- 1 file changed, 135 insertions(+), 12 deletions(-) diff --git a/trunk/gosa-core/include/class_config.inc b/trunk/gosa-core/include/class_config.inc index 63672fef9..9de15a949 100644 --- a/trunk/gosa-core/include/class_config.inc +++ b/trunk/gosa-core/include/class_config.inc @@ -20,6 +20,13 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ +/*! \brief Configuration class + * \ingroup coreclasses + * + * The configuration class, responsible for parsing and querying the + * gosa configuration file. + */ + class config { /* XML parser */ @@ -31,14 +38,17 @@ class config { var $section= ""; var $currentLocation= ""; - /* Selected connection */ - var $current= array(); + /*! \brief Store configuration for current location */ + var $current= array(); /* Link to LDAP-server */ var $ldap= NULL; var $referrals= array(); - /* Configuration data */ + /* \brief Configuration data + * + * - $data['SERVERS'] contains server informations. + * */ var $data= array( 'TABS' => array(), 'LOCATIONS' => array(), 'SERVERS' => array(), 'MAIN' => array(), 'MENU' => array(), 'SERVICE' => array()); @@ -53,6 +63,12 @@ class config { var $filename = ""; var $last_modified = 0; + /*! \brief Class constructor of the config class + * + * \param string 'filename' path to the configuration file + * \param string 'basedir' base directory + * + * */ function config($filename, $basedir= "") { $this->parser = xml_parser_create(); @@ -67,7 +83,14 @@ class config { } } - + + /*! \brief Check and reload the configuration + * + * This function checks if the configuration has changed, since it was + * read the last time and reloads it. It uses the file mtime to check + * weither the file changed or not. + * + * */ function check_and_reload() { global $ui; @@ -102,6 +125,14 @@ class config { } + /*! \brief Parse the given configuration file + * + * Parses the configuration file and displays errors if there + * is something wrong with it. + * + * \param string 'filename' The filename of the configuration file. + * */ + function parse($filename) { @@ -244,6 +275,22 @@ class config { } + /*! \brief Get a LDAP link object + * + * This function can be used to get an ldap object, which in turn can + * be used to query the LDAP. See the LDAP class for more information + * on how to use it. + * + * Example usage: + * \code + * $ldap = $this->config->get_ldap_link(); + * \endcode + * + * \param boolean sizelimit Weither to impose a sizelimit on the LDAP object or not. + * Defaults to false. If set to true, the size limit in the configuration + * file will be used to set the option LDAP_OPT_SIZELIMIT. + * \return ldapMultiplexer object + */ function get_ldap_link($sizelimit= FALSE) { if($this->ldap === NULL || !is_resource($this->ldap->cid)){ @@ -281,6 +328,10 @@ class config { return($obj); } + /*! \brief Set the current location + * + * \param string name the name of the location + */ function set_current($name) { $this->current= $this->data['LOCATIONS'][$name]; @@ -364,6 +415,13 @@ class config { $this->load_servers(); } + + /*! \brief Load server information from config/LDAP + * + * This function searches the LDAP for servers (e.g. goImapServer, goMailServer etc.) + * and stores information about them $this->data['SERVERS']. In the case of mailservers + * the main section of the configuration file is searched, too. + */ function load_servers () { /* Only perform actions if current is set */ @@ -817,10 +875,13 @@ class config { return($ret); } - /* This function returns all available Shares defined in this ldap - * There are two ways to call this function, if listboxEntry is true - * only name and path are attached to the array, in it is false, the whole - * entry will be parsed an atached to the result. + /*! \brief Get all available shares defined in the current LDAP + * + * This function returns all available Shares defined in this ldap + * + * \param boolean listboxEntry If set to TRUE, only name and path are + * attached to the array. If FALSE, the whole entry will be parsed an atached to the result. + * \return array */ function getShareList($listboxEntry = false) { @@ -853,7 +914,12 @@ class config { } - /* This function returns all available ShareServer */ + /*! \brief Return al available share servers + * + * This function returns all available ShareServers. + * + * \return array + * */ function getShareServerList() { global $config; @@ -885,7 +951,24 @@ class config { } - /* Check if there's the specified bool value set in the configuration */ + /*! \brief Check if there's the specified bool value set in the configuration + * + * The function checks, weither the specified bool value is set to a true + * value in the configuration file. Considered true are either true or yes, + * case-insensitive. + * + * Example usage: + * \code + * if ($this->config->boolValueIsTrue("main", "copyPaste")) { + * echo "Copy Paste Handling is enabled"; + * } + * \endcode + * + * \param string 'section' Section in the configuration file. + * \param string 'value' Key in the given section, which is subject to check + * + * + * */ function boolValueIsTrue($section, $value) { $section= strtoupper($section); @@ -922,6 +1005,18 @@ class config { } + /*! Search for a configuration setting in different categories + * + * Searches for the value of a given key in the configuration data. + * Optionally the list of categories to search (tabs, main, locations) can + * be specified. The first value that matches is returned. + * + * Example usage: + * \code + * $postcmd = $this->config->search(get_class($this), "POSTCOMMAND", array("menu", "tabs")); + * \endcode + * + * */ function search($class, $value, $categories= "") { if (is_array($categories)){ @@ -943,6 +1038,21 @@ class config { } + /*! \brief Get a configuration value from the config + * + * This returns a configuration value from the config. It either + * uses the data of the current location ($this->current), + * if it contains the value (e.g. current['BASE']) or otherwise + * uses the data from the main configuration section. + * + * If no value is found and an optional default has been specified, + * then the default is returned. + * + * \param string 'name' the configuration key (case-insensitive) + * \param string 'default' a default that is returned, if no value is found + * + * + */ function get_cfg_value($name, $default= "") { $name= strtoupper($name); @@ -960,6 +1070,13 @@ class config { } + /*! \brief Check if current configuration version matches the GOsa version + * + * This function checks if the configuration file version matches the + * version of the gosa version, by comparing it with the configuration + * file version of the example gosa.conf that comes with GOsa. + * If a version mismatch occurs an error is triggered. + * */ function check_config_version() { /* Skip check, if we've already mentioned the mismatch @@ -980,11 +1097,17 @@ class config { } - /* On debian systems the session files are deleted with + /*! \brief Check if session lifetime matches session.gc_maxlifetime + * + * On debian systems the session files are deleted with * a cronjob, which detects all files older than specified * in php.ini:'session.gc_maxlifetime' and removes them. - * This function checks if the gosa.conf value matches the range + * This function checks if the gosa.conf value matches the range * defined by session.gc_maxlifetime. + * + * \return boolean TRUE or FALSE depending on weither the settings match + * or not. If SESSIONLIFETIME is not configured in GOsa it always returns + * TRUE. */ function check_session_lifetime() { -- 2.30.2