From 4925c41a108ce46945710f3558974e11c6200111 Mon Sep 17 00:00:00 2001 From: cajus Date: Tue, 24 Nov 2009 08:12:01 +0000 Subject: [PATCH] Applied api docs done by psc. git-svn-id: https://oss.gonicus.de/repositories/gosa/trunk@14834 594d385d-05f5-0310-b6e9-bd551577e9d8 --- gosa-core/include/functions.inc | 620 +++++++++++++++++++++++++++++--- 1 file changed, 567 insertions(+), 53 deletions(-) diff --git a/gosa-core/include/functions.inc b/gosa-core/include/functions.inc index fffa4c6ca..1234a6d44 100644 --- a/gosa-core/include/functions.inc +++ b/gosa-core/include/functions.inc @@ -20,11 +20,10 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -/* Configuration file location */ +/*! \file + * Common functions and named definitions. */ -/* Allow setting the config patj in the apache configuration - e.g. SetEnv CONFIG_FILE /etc/path - */ +/* Configuration file location */ if(!isset($_SERVER['CONFIG_DIR'])){ define ("CONFIG_DIR", "/etc/gosa"); }else{ @@ -40,6 +39,7 @@ if(!isset($_SERVER['CONFIG_FILE'])){ define ("CONFIG_FILE",$_SERVER['CONFIG_FILE']); } +/* Define common locatitions */ define ("CONFIG_TEMPLATE_DIR", "../contrib"); define ("TEMP_DIR","/var/cache/gosa/tmp"); @@ -78,16 +78,16 @@ require_once ("functions_debug.inc"); require_once ("accept-to-gettext.inc"); /* Define constants for debugging */ -define ("DEBUG_TRACE", 1); -define ("DEBUG_LDAP", 2); -define ("DEBUG_MYSQL", 4); -define ("DEBUG_SHELL", 8); -define ("DEBUG_POST", 16); -define ("DEBUG_SESSION",32); -define ("DEBUG_CONFIG", 64); -define ("DEBUG_ACL", 128); -define ("DEBUG_SI", 256); -define ("DEBUG_MAIL", 512); // mailAccounts, imap, sieve etc. +define ("DEBUG_TRACE", 1); /*! Debug level for tracing of common actions (save, check, etc.) */ +define ("DEBUG_LDAP", 2); /*! Debug level for LDAP queries */ +define ("DEBUG_MYSQL", 4); /*! Debug level for mysql operations */ +define ("DEBUG_SHELL", 8); /*! Debug level for shell commands */ +define ("DEBUG_POST", 16); /*! Debug level for POST content */ +define ("DEBUG_SESSION",32); /*! Debug level for SESSION content */ +define ("DEBUG_CONFIG", 64); /*! Debug level for CONFIG information */ +define ("DEBUG_ACL", 128); /*! Debug level for ACL infos */ +define ("DEBUG_SI", 256); /*! Debug level for communication with gosa-si */ +define ("DEBUG_MAIL", 512); /*! Debug level for all about mail (mailAccounts, imap, sieve etc.) */ define ("DEBUG_FAI", 1024); // FAI (incomplete) /* Rewrite german 'umlauts' and spanish 'accents' @@ -113,7 +113,13 @@ $REWRITE= array( "ä" => "ae", "Ñ" => "Ny" ); -/* Class autoloader */ +/*! \brief Does autoloading for classes used in GOsa. + * + * Takes the list generated by 'update-gosa' and loads the + * file containing the requested class. + * + * \param string 'class_name' The currently requested class + */ function __autoload($class_name) { global $class_mapping, $BASE_DIR; @@ -132,8 +138,8 @@ function __autoload($class_name) { /*! \brief Checks if a class is available. - * @param name String The class name. - * @return boolean True if class is available, else false. + * \param string 'name' The subject of the test + * \return boolean True if class is available, else false. */ function class_available($name) { @@ -142,7 +148,13 @@ function class_available($name) } -/* Check if plugin is avaliable */ +/*! \brief Check if plugin is available + * + * Checks if a given plugin is available and readable. + * + * \param string 'plugin' the subject of the check + * \return boolean True if plugin is available, else FALSE. + */ function plugin_available($plugin) { global $class_mapping, $BASE_DIR; @@ -155,14 +167,39 @@ function plugin_available($plugin) } -/* Create seed with microseconds */ +/*! \brief Create seed with microseconds + * + * Example: + * \code + * srand(make_seed()); + * $random = rand(); + * \endcode + * + * \return float a floating point number which can be used to feed srand() with it + * */ function make_seed() { list($usec, $sec) = explode(' ', microtime()); return (float) $sec + ((float) $usec * 100000); } -/* Debug level action */ +/*! \brief Debug level action + * + * Print a DEBUG level if specified debug level of the level matches the + * the configured debug level. + * + * \param int 'level' The log level of the message (should use the constants, + * defined in functions.in (DEBUG_TRACE, DEBUG_LDAP, etc.) + * \param int 'line' Define the line of the logged action (using __LINE__ is common) + * \param string 'function' Define the function where the logged action happened in + * (using __FUNCTION__ is common) + * \param string 'file' Define the file where the logged action happend in + * (using __FILE__ is common) + * \param mixed 'data' The data to log. Can be a message or an array, which is printed + * with print_a + * \param string 'info' Optional: Additional information + * + * */ function DEBUG($level, $line, $function, $file, $data, $info="") { if (session::global_get('DEBUGLEVEL') & $level){ @@ -183,6 +220,18 @@ function DEBUG($level, $line, $function, $file, $data, $info="") } +/*! \brief Determine which language to show to the user + * + * Determines which language should be used to present gosa content + * to the user. It does so by looking at several possibilites and returning + * the first setting that can be found. + * + * -# Language configured by the user + * -# Global configured language + * -# Language as returned by al2gt (as configured in the browser) + * + * \return string gettext locale string + */ function get_browser_language() { /* Try to use users primary language */ @@ -217,7 +266,15 @@ function get_browser_language() } -/* Rewrite ui object to another dn */ +/*! \brief Rewrite ui object to another dn + * + * Usually used when a user is renamed. In this case the dn + * in the user object must be updated in order to point + * to the correct DN. + * + * \param string 'dn' the old DN + * \param string 'newdn' the new DN + * */ function change_ui_dn($dn, $newdn) { $ui= session::global_get('ui'); @@ -228,7 +285,22 @@ function change_ui_dn($dn, $newdn) } -/* Return theme path for specified file */ +/*! \brief Return themed path for specified base file + * + * Depending on its parameters, this function returns the full + * path of a template file. First match wins while searching + * in this order: + * + * - load theme depending file + * - load global theme depending file + * - load default theme file + * - load global default theme file + * + * \param string 'filename' The base file name + * \param boolean 'plugin' Flag to take the plugin directory as search base + * \param string 'path' User specified path to take as search base + * \return string Full path to the template file + */ function get_template_path($filename= '', $plugin= FALSE, $path= "") { global $config, $BASE_DIR; @@ -281,12 +353,23 @@ function get_template_path($filename= '', $plugin= FALSE, $path= "") } +/*! \brief Remove multiple entries from an array + * + * Removes every element that is in $needles from the + * array given as $haystack + * + * \param array 'needles' array of the entries to remove + * \param array 'haystack' original array to remove the entries from + */ function array_remove_entries($needles, $haystack) { return (array_merge(array_diff($haystack, $needles))); } +/*! \brief Remove multiple entries from an array (case-insensitive) + * + * Same as array_remove_entries(), but case-insensitive. */ function array_remove_entries_ics($needles, $haystack) { // strcasecmp will work, because we only compare ASCII values here @@ -294,6 +377,15 @@ function array_remove_entries_ics($needles, $haystack) } +/*! Merge to array but remove duplicate entries + * + * Merges two arrays and removes duplicate entries. Triggers + * an error if first or second parametre is not an array. + * + * \param array 'ar1' first array + * \param array 'ar2' second array- + * \return array + */ function gosa_array_merge($ar1,$ar2) { if(!is_array($ar1) || !is_array($ar2)){ @@ -304,6 +396,12 @@ function gosa_array_merge($ar1,$ar2) } +/*! \brief Generate a system log info + * + * Creates a syslog message, containing user information. + * + * \param string 'message' the message to log + * */ function gosa_log ($message) { global $ui; @@ -324,6 +422,17 @@ function gosa_log ($message) } +/*! \brief Initialize a LDAP connection + * + * Initializes a LDAP connection. + * + * \param string 'server' + * \param string 'base' + * \param string 'binddn' Default: empty + * \param string 'pass' Default: empty + * + * \return LDAP object + */ function ldap_init ($server, $base, $binddn='', $pass='') { global $config; @@ -346,6 +455,7 @@ function ldap_init ($server, $base, $binddn='', $pass='') } +/* \brief Process htaccess authentication */ function process_htaccess ($username, $kerberos= FALSE) { global $config; @@ -381,6 +491,15 @@ function process_htaccess ($username, $kerberos= FALSE) } +/*! \brief Verify user login against htaccess + * + * Checks if the specified username is available in apache, maps the user + * to an LDAP user. The password has been checked by apache already. + * + * \param string 'username' + * \return + * - TRUE on SUCCESS, NULL or FALSE on error + */ function ldap_login_user_htaccess ($username) { global $config; @@ -418,12 +537,22 @@ function ldap_login_user_htaccess ($username) $ui->loadACL(); /* TODO: check java script for htaccess authentication */ - session::global_set('js',true); + session::global_set('js', true); return ($ui); } +/*! \brief Verify user login against LDAP directory + * + * Checks if the specified username is in the LDAP and verifies if the + * password is correct by binding to the LDAP with the given credentials. + * + * \param string 'username' + * \param string 'password' + * \return + * - TRUE on SUCCESS, NULL or FALSE on error + */ function ldap_login_user ($username, $password) { global $config; @@ -515,6 +644,17 @@ function ldap_login_user ($username, $password) } +/*! \brief Test if account is about to expire + * + * \param string 'userdn' the DN of the user + * \param string 'username' the username + * \return int Can be one of the following values: + * - 1 the account is locked + * - 2 warn the user that the password is about to expire and he should change + * his password + * - 3 force the user to change his password + * - 4 user should not be able to change his password + * */ function ldap_expired_account($config, $userdn, $username) { $ldap= $config->get_ldap_link(); @@ -609,6 +749,14 @@ function ldap_expired_account($config, $userdn, $username) } +/*! \brief Add a lock for object(s) + * + * Adds a lock by the specified user for one ore multiple objects. + * If the lock for that object already exists, an error is triggered. + * + * \param mixed 'object' object or array of objects to lock + * \param string 'user' the user who shall own the lock + * */ function add_lock($object, $user) { global $config; @@ -670,6 +818,12 @@ function add_lock($object, $user) } +/*! \brief Remove a lock for object(s) + * + * Does the opposite of add_lock(). + * + * \param mixed 'object' object or array of objects for which a lock shall be removed + * */ function del_lock ($object) { global $config; @@ -713,6 +867,13 @@ function del_lock ($object) } +/*! \brief Remove all locks owned by a specific userdn + * + * For a given userdn remove all existing locks. This is usually + * called on logout. + * + * \param string 'userdn' the subject whose locks shall be deleted + */ function del_user_locks($userdn) { global $config; @@ -729,6 +890,14 @@ function del_user_locks($userdn) } +/*! \brief Get a lock for a specific object + * + * Searches for a lock on a given object. + * + * \param string 'object' subject whose locks are to be searched + * \return string Returns the user who owns the lock or "" if no lock is found + * or an error occured. + */ function get_lock ($object) { global $config; @@ -773,6 +942,14 @@ function get_lock ($object) } +/*! Get locks for multiple objects + * + * Similar as get_lock(), but for multiple objects. + * + * \param array 'objects' Array of Objects for which a lock shall be searched + * \return A numbered array containing all found locks as an array with key 'dn' + * and key 'user' or "" if an error occured. + */ function get_multiple_locks($objects) { global $config; @@ -807,15 +984,16 @@ function get_multiple_locks($objects) } -/* \!brief This function searches the ldap database. - It search in $sub_bases,*,$base for all objects matching the $filter. - - @param $filter String The ldap search filter - @param $category String The ACL category the result objects belongs - @param $sub_bases String The sub base we want to search for e.g. "ou=apps" - @param $base String The ldap base from which we start the search - @param $attributes Array The attributes we search for. - @param $flags Long A set of Flags +/*! \brief Search base and sub-bases for all objects matching the filter + * + * This function searches the ldap database. It searches in $sub_bases,*,$base + * for all objects matching the $filter. + * \param string 'filter' The ldap search filter + * \param string 'category' The ACL category the result objects belongs + * \param string 'sub_bases' The sub base we want to search for e.g. "ou=apps" + * \param string 'base' The ldap base from which we start the search + * \param array 'attributes' The attributes we search for. + * \param long 'flags' A set of Flags */ function get_sub_list($filter, $category,$sub_deps, $base= "", $attributes= array(), $flags= GL_SUBSEARCH) { @@ -968,6 +1146,10 @@ function get_sub_list($filter, $category,$sub_deps, $base= "", $attributes= arra } +/*! \brief Search base for all objects matching the filter + * + * Just like get_sub_list(), but without sub base search. + * */ function get_list($filter, $category, $base= "", $attributes= array(), $flags= GL_SUBSEARCH) { global $config, $ui; @@ -1036,6 +1218,7 @@ function get_list($filter, $category, $base= "", $attributes= array(), $flags= G } +/*! \brief Show sizelimit configuration dialog if exceeded */ function check_sizelimit() { /* Ignore dialog? */ @@ -1055,7 +1238,7 @@ function check_sizelimit() return (""); } - +/*! \brief Print a sizelimit warning */ function print_sizelimit_warning() { if (session::global_is_set('size_limit') && session::global_get('size_limit') >= 10000000 || @@ -1071,6 +1254,7 @@ function print_sizelimit_warning() } +/*! \brief Handle sizelimit dialog related posts */ function eval_sizelimit() { if (isset($_POST['set_size_action'])){ @@ -1125,6 +1309,7 @@ function getMenuCache() } +/*! \brief Return the current userinfo object */ function &get_userinfo() { global $ui; @@ -1133,6 +1318,7 @@ function &get_userinfo() } +/*! \brief Get global smarty object */ function &get_smarty() { global $smarty; @@ -1141,6 +1327,21 @@ function &get_smarty() } +/*! \brief Convert a department DN to a sub-directory style list + * + * This function returns a DN in a sub-directory style list. + * Examples: + * - ou=1.1.1,ou=limux becomes limux/1.1.1 + * - cn=bla,ou=foo,dc=local becomes foo/bla or foo/bla/local, depending + * on the value for $base. + * + * If the specified DN contains a basedn which either matches + * the specified base or $config->current['BASE'] it is stripped. + * + * \param string 'dn' the subject for the conversion + * \param string 'base' the base dn, default: $this->config->current['BASE'] + * \return a string in the form as described above + */ function convert_department_dn($dn, $base = NULL) { global $config; @@ -1165,14 +1366,40 @@ function convert_department_dn($dn, $base = NULL) } -/* Strip off the last sub department part of a '/level1/level2/.../' - * style value. It removes the trailing '/', too. */ +/*! \brief Return the last sub department part of a '/level1/level2/.../' style value. + * + * Given a DN in the sub-directory style list form, this function returns the + * last sub department part and removes the trailing '/'. + * + * Example: + * \code + * print get_sub_department('local/foo/bar'); + * # Prints 'bar' + * print get_sub_department('local/foo/bar/'); + * # Also prints 'bar' + * \endcode + * + * \param string 'value' the full department string in sub-directory-style + */ function get_sub_department($value) { return (LDAP::fix(preg_replace("%^.*/([^/]+)/?$%", "\\1", $value))); } +/*! \brief Get the OU of a certain RDN + * + * Given a certain RDN name (ogroupRDN, applicationRDN etc.) this + * function returns either a configured OU or the default + * for the given RDN. + * + * Example: + * \code + * # Determine LDAP base where systems are stored + * $base = get_ou('systemRDN') . $this->config->current['BASE']; + * $ldap->cd($base); + * \endcode + * */ function get_ou($name) { global $config; @@ -1221,7 +1448,6 @@ function get_ou($name) return ""; } - if ($ou != ""){ if (!preg_match('/^[^=]+=[^=]+/', $ou)){ $ou = @LDAP::convert("ou=$ou"); @@ -1241,24 +1467,45 @@ function get_ou($name) } +/*! \brief Get the OU for users + * + * Frontend for get_ou() with userRDN + * */ function get_people_ou() { return (get_ou("userRDN")); } +/*! \brief Get the OU for groups + * + * Frontend for get_ou() with groupRDN + */ function get_groups_ou() { return (get_ou("groupRDN")); } +/*! \brief Get the OU for winstations + * + * Frontend for get_ou() with sambaMachineAccountRDN + */ function get_winstations_ou() { return (get_ou("sambaMachineAccountRDN")); } +/*! \brief Return a base from a given user DN + * + * \code + * get_base_from_people('cn=Max Muster,dc=local') + * # Result is 'dc=local' + * \endcode + * + * \param string 'dn' a DN + * */ function get_base_from_people($dn) { global $config; @@ -1275,6 +1522,14 @@ function get_base_from_people($dn) } +/*! \brief Check if strict naming rules are configured + * + * Return TRUE or FALSE depending on weither strictNamingRules + * are configured or not. + * + * \return Returns TRUE if strictNamingRules is set to true or if the + * config object is not available, otherwise FALSE. + */ function strict_uid_mode() { global $config; @@ -1286,6 +1541,10 @@ function strict_uid_mode() } +/*! \brief Get regular expression for checking uids based on the naming + * rules. + * \return string Returns the desired regular expression + */ function get_uid_regexp() { /* STRICT adds spaces and case insenstivity to the uid check. @@ -1298,6 +1557,27 @@ function get_uid_regexp() } +/*! \brief Generate a lock message + * + * This message shows a warning to the user, that a certain object is locked + * and presents some choices how the user can proceed. By default this + * is 'Cancel' or 'Edit anyway', but depending on the function call + * its possible to allow readonly access, too. + * + * Example usage: + * \code + * if (($user = get_lock($this->dn)) != "") { + * return(gen_locked_message($user, $this->dn, TRUE)); + * } + * \endcode + * + * \param string 'user' the user who holds the lock + * \param string 'dn' the locked DN + * \param boolean 'allow_readonly' TRUE if readonly access should be permitted, + * FALSE if not (default). + * + * + */ function gen_locked_message($user, $dn, $allow_readonly = FALSE) { global $plug, $config; @@ -1368,6 +1648,17 @@ function gen_locked_message($user, $dn, $allow_readonly = FALSE) } +/*! \brief Return a string/HTML representation of an array + * + * This returns a string representation of a given value. + * It can be used to dump arrays, where every value is printed + * on its own line. The output is targetted at HTML output, it uses + * '
' for line breaks. If the value is already a string its + * returned unchanged. + * + * \param mixed 'value' Whatever needs to be printed. + * \return string + */ function to_string ($value) { /* If this is an array, generate a text blob */ @@ -1383,6 +1674,19 @@ function to_string ($value) } +/*! \brief Return a list of all printers in the current base + * + * Returns an array with the CNs of all printers (objects with + * objectClass gotoPrinter) in the current base. + * ($config->current['BASE']). + * + * Example: + * \code + * $this->printerList = get_printer_list(); + * \endcode + * + * \return array an array with the CNs of the printers as key and value. + * */ function get_printer_list() { global $config; @@ -1395,6 +1699,14 @@ function get_printer_list() } +/*! \brief Function to rewrite some problematic characters + * + * This function takes a string and replaces all possibly characters in it + * with less problematic characters, as defined in $REWRITE. + * + * \param string 's' the string to rewrite + * \return string 's' the result of the rewrite + * */ function rewrite($s) { global $REWRITE; @@ -1407,6 +1719,10 @@ function rewrite($s) } +/*! \brief Return the base of a given DN + * + * \param string 'dn' a DN + * */ function dn2base($dn) { global $config; @@ -1423,7 +1739,14 @@ function dn2base($dn) } - +/*! \brief Check if a given command exists and is executable + * + * Test if a given cmdline contains an executable command. Strips + * arguments from the given cmdline. + * + * \param string 'cmdline' the cmdline to check + * \return TRUE if command exists and is executable, otherwise FALSE. + * */ function check_command($cmdline) { $cmd= preg_replace("/ .*$/", "", $cmdline); @@ -1442,6 +1765,12 @@ function check_command($cmdline) } +/*! \brief Print plugin HTML header + * + * \param string 'image' the path of the image to be used next to the headline + * \param string 'image' the headline + * \param string 'info' additional information to print + */ function print_header($image, $headline, $info= "") { $display= "
\n"; @@ -1461,6 +1790,13 @@ function print_header($image, $headline, $info= "") } +/*! \brief Print page number selector for paged lists + * + * \param int 'dcnt' Number of entries + * \param int 'start' Page to start + * \param int 'range' Number of entries per page + * \param string 'post_var' POST variable to check for range + */ function range_selector($dcnt,$start,$range=25,$post_var=false) { @@ -1568,6 +1904,7 @@ function range_selector($dcnt,$start,$range=25,$post_var=false) } +/*! \brief Generate HTML for the 'Apply filter' button */ function apply_filter() { $apply= ""; @@ -1580,6 +1917,7 @@ function apply_filter() } +/*! \brief Generate HTML for the 'Back' button */ function back_to_main() { $string= '

assign("installprogress", progressbar($current_progress_in_percent),100,15,true); + * \endcode + * + * \param int 'percentage' Value to display + * \param int 'width' width of the resulting output + * \param int 'height' height of the resulting output + * \param boolean 'showvalue' weither to show the percentage in the progressbar or not + * */ function progressbar($percentage,$width=100,$height=15,$showvalue=false) { return(""); } +/*! \brief Lookup a key in an array case-insensitive + * + * Given an associative array this can lookup the value of + * a certain key, regardless of the case. + * + * \code + * $items = array ('FOO' => 'blub', 'bar' => 'blub'); + * array_key_ics('foo', $items); # Returns 'blub' + * array_key_ics('BAR', $items); # Returns 'blub' + * \endcode + * + * \param string 'key' needle + * \param array 'items' haystack + */ function array_key_ics($ikey, $items) { $tmp= array_change_key_case($items, CASE_LOWER); @@ -2031,6 +2473,12 @@ function array_key_ics($ikey, $items) } +/*! \brief Determine if two arrays are different + * + * \param array 'src' + * \param array 'dst' + * \return boolean TRUE or FALSE + * */ function array_differs($src, $dst) { /* If the count is differing, the arrays differ */ @@ -2069,13 +2517,14 @@ function saveFilter($a_filter, $values) } -/* Escape all LDAP filter relevant characters */ +/*! \brief Escape all LDAP filter relevant characters */ function normalizeLdap($input) { return (addcslashes($input, '()|')); } +/*! \brief Return the gosa base directory */ function get_base_dir() { global $BASE_DIR; @@ -2084,6 +2533,7 @@ function get_base_dir() } +/*! \brief Test weither we are allowed to read the object */ function obj_is_readable($dn, $object, $attribute) { global $ui; @@ -2092,6 +2542,7 @@ function obj_is_readable($dn, $object, $attribute) } +/*! \brief Test weither we are allowed to change the object */ function obj_is_writable($dn, $object, $attribute) { global $ui; @@ -2100,6 +2551,16 @@ function obj_is_writable($dn, $object, $attribute) } +/*! \brief Explode a DN into its parts + * + * Similar to explode (http://php.net/explode), but a bit more specific + * for the needs when splitting, exploding LDAP DNs. + * + * \param string 'dn' the DN to split + * \param config-object a config object. only neeeded if DN shall be verified in the LDAP + * \param boolean verify_in_ldap check weither DN is valid + * + */ function gosa_ldap_explode_dn($dn,$config = NULL,$verify_in_ldap=false) { /* Initialize variables */ @@ -2195,12 +2656,14 @@ function get_base_from_hook($dn, $attrib) } +/*! \brief Check if schema version matches the requirements */ function check_schema_version($class, $version) { return preg_match("/\(v$version\)/", $class['DESC']); } +/*! \brief Check if LDAP schema matches the requirements */ function check_schema($cfg,$rfc2307bis = FALSE) { $messages= array(); @@ -2399,7 +2862,14 @@ function get_languages($languages_in_own_language = FALSE,$strip_region_tag = FA } -/* Returns contents of the given POST variable and check magic quotes settings */ +/*! \brief Returns contents of the given POST variable and check magic quotes settings + * + * Depending on the magic quotes settings this returns a stripclashed'ed version of + * a certain POST variable. + * + * \param string 'name' the POST var to return ($_POST[$name]) + * \return string + * */ function get_post($name) { if(!isset($_POST[$name])){ @@ -2415,7 +2885,7 @@ function get_post($name) } -/* Return class name in correct case */ +/*! \brief Return class name in correct case */ function get_correct_class_name($cls) { global $class_mapping; @@ -2430,7 +2900,17 @@ function get_correct_class_name($cls) } -// change_password, changes the Password, of the given dn +/*! \brief Change the password of a given DN + * + * Change the password of a given DN with the specified hash. + * + * \param string 'dn' the DN whose password shall be changed + * \param string 'password' the password + * \param int mode + * \param string 'hash' which hash to use to encrypt it, default is empty + * for cleartext storage. + * \return boolean TRUE on success FALSE on error + */ function change_password ($dn, $password, $mode=0, $hash= "") { global $config; @@ -2549,7 +3029,15 @@ function change_password ($dn, $password, $mode=0, $hash= "") } -// Return something like array['sambaLMPassword']= "lalla..." +/*! \brief Generate samba hashes + * + * Given a certain password this constructs an array like + * array['sambaLMPassword'] etc. + * + * \param string 'password' + * \return array contains several keys for lmPassword, ntPassword, pwdLastSet, etc. depending + * on the samba version + */ function generate_smb_nt_hash($password) { global $config; @@ -2593,6 +3081,16 @@ function generate_smb_nt_hash($password) } +/*! \brief Get the Change Sequence Number of a certain DN + * + * To verify if a given object has been changed outside of Gosa + * in the meanwhile, this function can be used to get the entryCSN + * from the LDAP directory. It uses the attribute as configured + * in modificationDetectionAttribute + * + * \param string 'dn' + * \return either the result or "" in any other case + */ function getEntryCSN($dn) { global $config; @@ -2614,7 +3112,16 @@ function getEntryCSN($dn) } -/* Add a given objectClass to an attrs entry */ +/*! \brief Add (a) given objectClass(es) to an attrs entry + * + * The function adds the specified objectClass(es) to the given + * attrs entry. + * + * \param mixed 'classes' Either a single objectClass or several objectClasses + * as an array + * \param array 'attrs' The attrs array to be modified. + * + * */ function add_objectClass($classes, &$attrs) { if (is_array($classes)){ @@ -2629,7 +3136,11 @@ function add_objectClass($classes, &$attrs) } -/* Removes a given objectClass from the attrs entry */ +/*! \brief Removes a given objectClass from the attrs entry + * + * Similar to add_objectClass, except that it removes the given + * objectClasses. See it for the params. + * */ function remove_objectClass($classes, &$attrs) { if (isset($attrs['objectClass'])){ @@ -2652,10 +3163,11 @@ function remove_objectClass($classes, &$attrs) } } + /*! \brief Initialize a file download with given content, name and data type. - * @param data String The content to send. - * @param name String The name of the file. - * @param type String The content identifier, default value is "application/octet-stream"; + * \param string data The content to send. + * \param string name The name of the file. + * \param string type The content identifier, default value is "application/octet-stream"; */ function send_binary_content($data,$name,$type = "application/octet-stream") { @@ -2700,8 +3212,8 @@ function reverse_html_entities($str,$type = ENT_QUOTES , $charset = "UTF-8") /*! \brief Encode special string characters so we can use the string in \ HTML output, without breaking quotes. - @param The String we want to encode. - @return The encoded String + \param string The String we want to encode. + \return string The encoded String */ function xmlentities($str) { @@ -2733,8 +3245,8 @@ function xmlentities($str) /*! \brief Updates all accessTo attributes from a given value to a new one. For example if a host is renamed. - @param String $from The source accessTo name. - @param String $to The destination accessTo name. + \param String $from The source accessTo name. + \param String $to The destination accessTo name. */ function update_accessTo($from,$to) { @@ -2767,6 +3279,7 @@ function update_accessTo($from,$to) } +/*! \brief Returns a random char */ function get_random_char () { $randno = rand (0, 63); if ($randno < 12) { @@ -2931,6 +3444,7 @@ function get_next_id_pool($attrib) { return $id; } + function get_next_id_traditional($attrib, $dn) { global $config; -- 2.30.2