From 147e5af35378f4493d05b773b8097e10b81bc65c Mon Sep 17 00:00:00 2001 From: tokul Date: Mon, 1 Nov 2004 10:49:31 +0000 Subject: [PATCH] adding phpdoc blocks. fixed unchecked used of create. According to the docs it is optional. git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@8305 7612ce4b-ef26-0410-bec9-ea0150e637f0 --- functions/abook_local_file.php | 116 +++++++++++++++++++++++---------- 1 file changed, 81 insertions(+), 35 deletions(-) diff --git a/functions/abook_local_file.php b/functions/abook_local_file.php index 04c1eaa2..a841c035 100644 --- a/functions/abook_local_file.php +++ b/functions/abook_local_file.php @@ -1,44 +1,54 @@ path to addressbook file - * ? create => if true: file is created if it does not exist. - * ? umask => umask set before opening file. - * - * NOTE. This class should not be used directly. Use the - * "AddressBook" class instead. - * * @version $Id$ * @package squirrelmail * @subpackage addressbook */ /** - * Store the addressbook in a local file + * Backend for address book as a pipe separated file + * + * Stores the address book in a local file + * + * An array with the following elements must be passed to + * the class constructor (elements marked ? are optional): + *
+ *   filename  => path to addressbook file
+ * ? create    => if true: file is created if it does not exist.
+ * ? umask     => umask set before opening file.
+ * ? name      => name of address book
+ *
+ * NOTE. This class should not be used directly. Use the + * "AddressBook" class instead. * @package squirrelmail */ class abook_local_file extends addressbook_backend { + /** @var string backend type */ var $btype = 'local'; + /** @var string backend name */ var $bname = 'local_file'; + /** @var string file used to store data */ var $filename = ''; + /** @var object file handle */ var $filehandle = 0; + /** @var bool create file if it is not present */ var $create = false; + /** @var string umask of the file */ var $umask; /* ========================== Private ======================= */ - /* Constructor */ + /** + * Constructor + * @param array $param backend options + * @return bool + */ function abook_local_file($param) { $this->sname = _("Personal address book"); $this->umask = Umask(); @@ -54,8 +64,8 @@ class abook_local_file extends addressbook_backend { $this->filename = $param['filename']; - if($param['create']) { - $this->create = true; + if(isset($param['create'])) { + $this->create = $param['create']; } if(isset($param['umask'])) { $this->umask = $param['umask']; @@ -70,10 +80,14 @@ class abook_local_file extends addressbook_backend { } } - /* Open the addressbook file and store the file pointer. + /** + * Open the addressbook file and store the file pointer. * Use $file as the file to open, or the class' own * filename property. If $param is empty and file is - * open, do nothing. */ + * open, do nothing. + * @param bool $new is file already opened + * @return bool + */ function open($new = false) { $this->error = ''; $file = $this->filename; @@ -113,7 +127,7 @@ class abook_local_file extends addressbook_backend { return true; } - /* Close the file and forget the filehandle */ + /** Close the file and forget the filehandle */ function close() { @fclose($this->filehandle); $this->filehandle = 0; @@ -121,7 +135,7 @@ class abook_local_file extends addressbook_backend { $this->writable = false; } - /* Lock the datafile - try 20 times in 5 seconds */ + /** Lock the datafile - try 20 times in 5 seconds */ function lock() { for($i = 0 ; $i < 20 ; $i++) { if(flock($this->filehandle, 2 + 4)) @@ -132,13 +146,17 @@ class abook_local_file extends addressbook_backend { return false; } - /* Lock the datafile */ + /** Unlock the datafile */ function unlock() { return flock($this->filehandle, 3); } - /* Overwrite the file with data from $rows - * NOTE! Previous locks are broken by this function */ + /** + * Overwrite the file with data from $rows + * NOTE! Previous locks are broken by this function + * @param array $rows new data + * @return bool + */ function overwrite(&$rows) { $this->unlock(); $newfh = @fopen($this->filename.'.tmp', 'w'); @@ -171,7 +189,11 @@ class abook_local_file extends addressbook_backend { /* ========================== Public ======================== */ - /* Search the file */ + /** + * Search the file + * @param string $expr search expression + * @return array search results + */ function search($expr) { /* To be replaced by advanded search expression parsing */ @@ -205,7 +227,11 @@ class abook_local_file extends addressbook_backend { return $res; } - /* Lookup alias */ + /** + * Lookup alias + * @param string $alias alias + * @return array search results + */ function lookup($alias) { if(empty($alias)) { return array(); @@ -232,7 +258,10 @@ class abook_local_file extends addressbook_backend { return array(); } - /* List all addresses */ + /** + * List all addresses + * @return array list of all addresses + */ function list_addr() { $res = array(); $this->open(); @@ -251,7 +280,11 @@ class abook_local_file extends addressbook_backend { return $res; } - /* Add address */ + /** + * Add address + * @param array $userdata new data + * @return bool + */ function add($userdata) { if(!$this->writeable) { return $this->set_error(_("Addressbook is read-only")); @@ -294,15 +327,19 @@ class abook_local_file extends addressbook_backend { /* Test write result */ if($r === FALSE) { - /* Fail */ - $this->set_error(_("Write to addressbook failed")); - return FALSE; - } + /* Fail */ + $this->set_error(_("Write to addressbook failed")); + return FALSE; + } return TRUE; } - /* Delete address */ + /** + * Delete address + * @param string $alias alias that has to be deleted + * @return bool + */ function remove($alias) { if(!$this->writeable) { return $this->set_error(_("Addressbook is read-only")); @@ -334,7 +371,12 @@ class abook_local_file extends addressbook_backend { return true; } - /* Modify address */ + /** + * Modify address + * @param string $alias modified alias + * @param array $userdata new data + * @return bool true, if operation successful + */ function modify($alias, $userdata) { if(!$this->writeable) { return $this->set_error(_("Addressbook is read-only")); @@ -381,7 +423,11 @@ class abook_local_file extends addressbook_backend { return true; } - /* Function for quoting values before saving */ + /** + * Function for quoting values before saving + * @param string $value string that has to be quoted + * @param string quoted string + */ function quotevalue($value) { /* Quote the field if it contains | or ". Double quotes need to * be replaced with "" */ -- 2.25.1