functions/addressbook.php

   1 <?php
   2 /**
   3  * functions/addressbook.php - Functions and classes for the addressbook system
   4  *
   5  * Functions require SM_PATH and support of forms.php functions
   6  *
   7  * @copyright &copy; 1999-2006 The SquirrelMail Project Team
   8  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
   9  * @version $Id$
  10  * @package squirrelmail
  11  * @subpackage addressbook
  12  */
  13
  14 /**
  15  * Create and initialize an addressbook object.
  16  * @param boolean $showerr display any address book init errors. html page header
  17  * must be created before calling addressbook_init() with $showerr enabled.
  18  * @param boolean $onlylocal enable only local address book backends. Should
  19  *  be used when code does not need access to remote backends. Backends
  20  *  that provide read only address books with limited listing options can be
  21  *  tagged as remote.
  22  * @return object address book object.
  23  */
  24 function addressbook_init($showerr = true, $onlylocal = false) {
  25     global $data_dir, $username, $ldap_server, $address_book_global_filename;
  26     global $addrbook_dsn, $addrbook_table;
  27     global $abook_global_file, $abook_global_file_writeable, $abook_global_file_listing;
  28     global $addrbook_global_dsn, $addrbook_global_table, $addrbook_global_writeable, $addrbook_global_listing;
  29     global $abook_file_line_length;
  30
  31     /* Create a new addressbook object */
  32     $abook = new AddressBook;
  33
  34     /* Create empty error message */
  35     $abook_init_error='';
  36
  37     /*
  38         Always add a local backend. We use *either* file-based *or* a
  39         database addressbook. If $addrbook_dsn is set, the database
  40         backend is used. If not, addressbooks are stores in files.
  41     */
  42     if (isset($addrbook_dsn) && !empty($addrbook_dsn)) {
  43         /* Database */
  44         if (!isset($addrbook_table) || empty($addrbook_table)) {
  45             $addrbook_table = 'address';
  46         }
  47         $r = $abook->add_backend('database', Array('dsn' => $addrbook_dsn,
  48                             'owner' => $username,
  49                             'table' => $addrbook_table));
  50         if (!$r && $showerr) {
  51             $abook_init_error.=_("Error initializing address book database.") . "\n" . $abook->error;
  52         }
  53     } else {
  54         /* File */
  55         $filename = getHashedFile($username, $data_dir, "$username.abook");
  56         $r = $abook->add_backend('local_file', Array('filename' => $filename,
  57                                                      'line_length' => $abook_file_line_length,
  58                                                      'create'   => true));
  59         if(!$r && $showerr) {
  60             // no need to use $abook->error, because message explains error.
  61             $abook_init_error.=sprintf( _("Error opening file %s"), $filename );
  62         }
  63     }
  64
  65     /* Global file based addressbook */
  66     if (isset($abook_global_file) &&
  67         isset($abook_global_file_writeable) &&
  68         isset($abook_global_file_listing) &&
  69         trim($abook_global_file)!=''){
  70
  71         // Detect place of address book
  72         if (! preg_match("/[\/\\\]/",$abook_global_file)) {
  73             /* no path chars, address book stored in data directory
  74              * make sure that there is a slash between data directory
  75              * and address book file name
  76              */
  77             $abook_global_filename=$data_dir
  78                 . ((substr($data_dir, -1) != '/') ? '/' : '')
  79                 . $abook_global_file;
  80         } elseif (preg_match("/^\/|\w:/",$abook_global_file)) {
  81             // full path is set in options (starts with slash or x:)
  82             $abook_global_filename=$abook_global_file;
  83         } else {
  84             $abook_global_filename=SM_PATH . $abook_global_file;
  85         }
  86
  87         $r = $abook->add_backend('local_file',array('filename'=>$abook_global_filename,
  88                                                     'name' => _("Global address book"),
  89                                                     'detect_writeable' => false,
  90                                                     'line_length' => $abook_file_line_length,
  91                                                     'writeable'=> $abook_global_file_writeable,
  92                                                     'listing' => $abook_global_file_listing));
  93
  94         /* global abook init error is not fatal. add error message and continue */
  95         if (!$r && $showerr) {
  96             if ($abook_init_error!='') $abook_init_error.="\n";
  97             $abook_init_error.=_("Error initializing global address book.") . "\n" . $abook->error;
  98         }
  99     }
 100
 101     /* Load global addressbook from SQL if configured */
 102     if (isset($addrbook_global_dsn) && !empty($addrbook_global_dsn)) {
 103       /* Database configured */
 104       if (!isset($addrbook_global_table) || empty($addrbook_global_table)) {
 105           $addrbook_global_table = 'global_abook';
 106       }
 107       $r = $abook->add_backend('database',
 108                                Array('dsn' => $addrbook_global_dsn,
 109                                      'owner' => 'global',
 110                                      'name' => _("Global address book"),
 111                                      'writeable' => $addrbook_global_writeable,
 112                                      'listing' => $addrbook_global_listing,
 113                                      'table' => $addrbook_global_table));
 114       /* global abook init error is not fatal. add error message and continue */
 115       if (!$r && $showerr) {
 116           if ($abook_init_error!='') $abook_init_error.="\n";
 117           $abook_init_error.=_("Error initializing global address book.") . "\n" . $abook->error;
 118       }
 119     }
 120
 121     /*
 122      * hook allows to include different address book backends.
 123      * plugins should extract $abook and $r from arguments
 124      * and use same add_backend commands as above functions.
 125      * Since 1.5.2 hook sends third ($onlylocal) argument to address book
 126      * plugins in order to allow detection of local address book init.
 127      * @since 1.5.1 and 1.4.5
 128      */
 129     $hookReturn = do_hook('abook_init', $abook, $r, $onlylocal);
 130     $abook = $hookReturn[1];
 131     $r = $hookReturn[2];
 132     if (!$r && $showerr) {
 133         if ($abook_init_error!='') $abook_init_error.="\n";
 134         $abook_init_error.=_("Error initializing other address books.") . "\n" . $abook->error;
 135     }
 136
 137     /* Load configured LDAP servers (if PHP has LDAP support) */
 138     if (isset($ldap_server) && is_array($ldap_server)) {
 139         reset($ldap_server);
 140         while (list($undef,$param) = each($ldap_server)) {
 141             if (!is_array($param))
 142                 continue;
 143
 144             /* if onlylocal is true, we only add writeable ldap servers */
 145             if ($onlylocal && (!isset($param['writeable']) || $param['writeable'] != true))
 146                 continue;
 147
 148             $r = $abook->add_backend('ldap_server', $param);
 149             if (!$r && $showerr) {
 150                 if ($abook_init_error!='') $abook_init_error.="\n";
 151                 $abook_init_error.=sprintf(_("Error initializing LDAP server %s:"), $param['host'])."\n";
 152                 $abook_init_error.= $abook->error;
 153             }
 154         }
 155     } // end of ldap server init
 156
 157     /**
 158      * display address book init errors.
 159      */
 160     if ($abook_init_error!='' && $showerr) {
 161         error_box(nl2br(htmlspecialchars($abook_init_error)));
 162     }
 163
 164     /* Return the initialized object */
 165     return $abook;
 166 }
 167
 168 /**
 169  * Display the "new address" form
 170  *
 171  * Form is not closed and you must add closing form tag.
 172  * @since 1.5.1
 173  * @param string $form_url form action url
 174  * @param string $name form name
 175  * @param string $title form title
 176  * @param string $button form button name
 177  * @param array $defdata values of form fields
 178  */
 179 function abook_create_form($form_url,$name,$title,$button,$defdata=array()) {
 180     global $oTemplate;
 181
 182     echo addForm($form_url, 'post', 'f_add');
 183
 184     if ($button == _("Update address")) {
 185         $edit = true;
 186         $backends = NULL;
 187     } else {
 188         $edit = false;
 189         $backends = getWritableBackends();
 190     }
 191
 192     $fields = array (
 193                         'nickname'  => 'NickName',
 194                         'firstname' => 'FirstName',
 195                         'lastname'  => 'LastName',
 196                         'email'     => 'Email',
 197                         'label'     => 'Info',
 198                     );
 199     $values = array();
 200     foreach ($fields as $sqm=>$template) {
 201         $values[$template] = isset($defdata[$sqm]) ? $defdata[$sqm] : '';
 202     }
 203
 204     $oTemplate->assign('writable_backends', $backends);
 205     $oTemplate->assign('values', $values);
 206     $oTemplate->assign('edit', $edit);
 207
 208     $oTemplate->display('addrbook_addedit.tpl');
 209 }
 210
 211
 212 /**
 213  *   Had to move this function outside of the Addressbook Class
 214  *   PHP 4.0.4 Seemed to be having problems with inline functions.
 215  *   Note: this can return now since we don't support 4.0.4 anymore.
 216  */
 217 function addressbook_cmp($a,$b) {
 218
 219     if($a['backend'] > $b['backend']) {
 220         return 1;
 221     } else if($a['backend'] < $b['backend']) {
 222         return -1;
 223     }
 224
 225     return (strtolower($a['name']) > strtolower($b['name'])) ? 1 : -1;
 226
 227 }
 228
 229 /**
 230  * Retrieve a list of writable backends
 231  * @since 1.5.2
 232  */
 233 function getWritableBackends () {
 234     global $abook;
 235
 236     $write = array();
 237     $backends = $abook->get_backend_list();
 238     while (list($undef,$v) = each($backends)) {
 239         if ($v->writeable) {
 240             $write[$v->bnum]=$v->sname;
 241         }
 242     }
 243
 244     return $write;
 245 }
 246
 247 /**
 248  * Sort array by the key "name"
 249  */
 250 function alistcmp($a,$b) {
 251     $abook_sort_order=get_abook_sort();
 252
 253     switch ($abook_sort_order) {
 254     case 0:
 255     case 1:
 256       $abook_sort='nickname';
 257       break;
 258     case 4:
 259     case 5:
 260       $abook_sort='email';
 261       break;
 262     case 6:
 263     case 7:
 264       $abook_sort='label';
 265       break;
 266     case 2:
 267     case 3:
 268     case 8:
 269     default:
 270       $abook_sort='name';
 271     }
 272
 273     if ($a['backend'] > $b['backend']) {
 274         return 1;
 275     } else {
 276         if ($a['backend'] < $b['backend']) {
 277             return -1;
 278         }
 279     }
 280
 281     if( (($abook_sort_order+2) % 2) == 1) {
 282       return (strtolower($a[$abook_sort]) < strtolower($b[$abook_sort])) ? 1 : -1;
 283     } else {
 284       return (strtolower($a[$abook_sort]) > strtolower($b[$abook_sort])) ? 1 : -1;
 285     }
 286 }
 287
 288 /**
 289  * Address book sorting options
 290  *
 291  * returns address book sorting order
 292  * @return integer book sorting options order
 293  */
 294 function get_abook_sort() {
 295     global $data_dir, $username;
 296
 297     /* get sorting order */
 298     if(sqgetGlobalVar('abook_sort_order', $temp, SQ_GET)) {
 299       $abook_sort_order = (int) $temp;
 300
 301       if ($abook_sort_order < 0 or $abook_sort_order > 8)
 302         $abook_sort_order=8;
 303
 304       setPref($data_dir, $username, 'abook_sort_order', $abook_sort_order);
 305     } else {
 306       /* get previous sorting options. default to unsorted */
 307       $abook_sort_order = getPref($data_dir, $username, 'abook_sort_order', 8);
 308     }
 309
 310     return $abook_sort_order;
 311 }
 312
 313 /**
 314  * This function shows the address book sort button.
 315  *
 316  * @param integer $abook_sort_order current sort value
 317  * @param string $alt_tag alt tag value (string visible to text only browsers)
 318  * @param integer $Down sort value when list is sorted ascending
 319  * @param integer $Up sort value when list is sorted descending
 320  * @return string html code with sorting images and urls
 321  */
 322 function show_abook_sort_button($abook_sort_order, $alt_tag, $Down, $Up ) {
 323     global $form_url, $icon_theme_path;
 324
 325      /* Figure out which image we want to use. */
 326     if ($abook_sort_order != $Up && $abook_sort_order != $Down) {
 327         $img = 'sort_none.png';
 328         $text_icon = '&#9723;'; // U+25FB WHITE MEDIUM SQUARE
 329         $which = $Up;
 330     } elseif ($abook_sort_order == $Up) {
 331         $img = 'up_pointer.png';
 332         $text_icon = '&#8679;'; // U+21E7 UPWARDS WHITE ARROW
 333         $which = $Down;
 334     } else {
 335         $img = 'down_pointer.png';
 336         $text_icon = '&#8681;'; // U+21E9 DOWNWARDS WHITE ARROW
 337         $which = 8;
 338     }
 339
 340     /* Now that we have everything figured out, show the actual button. */
 341     return '&nbsp;<a href="' . $form_url .'?abook_sort_order=' . $which .
 342            '" style="text-decoration:none" title="'.$alt_tag.'">' .
 343            getIcon($icon_theme_path, $img, $text_icon, $alt_tag) .
 344            '</a>';
 345 }
 346
 347
 348 /**
 349  * This is the main address book class that connect all the
 350  * backends and provide services to the functions above.
 351  * @package squirrelmail
 352  * @subpackage addressbook
 353  */
 354 class AddressBook {
 355     /**
 356      * Enabled address book backends
 357      * @var array
 358      */
 359     var $backends    = array();
 360     /**
 361      * Number of enabled backends
 362      * @var integer
 363      */
 364     var $numbackends = 0;
 365     /**
 366      * Error messages
 367      * @var string
 368      */
 369     var $error       = '';
 370     /**
 371      * id of backend with personal address book
 372      * @var integer
 373      */
 374     var $localbackend = 0;
 375     /**
 376      * Name of backend with personal address book
 377      * @var string
 378      */
 379     var $localbackendname = '';
 380     /**
 381      * Controls use of 'extra' field
 382      *
 383      * Extra field can be used to add link to form, which allows
 384      * to modify all fields supported by backend. This is the only field
 385      * that is not sanitized with htmlspecialchars. Backends MUST make
 386      * sure that field data is sanitized and displayed correctly inside
 387      * table cell. Use of html formating in other address book fields is
 388      * not allowed. Backends that don't return 'extra' row in address book
 389      * data should not modify this object property.
 390      * @var boolean
 391      * @since 1.5.1
 392      */
 393     var $add_extra_field = false;
 394
 395     /**
 396      * Constructor function.
 397      */
 398     function AddressBook() {
 399         $this->localbackendname = _("Personal address book");
 400     }
 401
 402     /**
 403      * Return an array of backends of a given type,
 404      * or all backends if no type is specified.
 405      * @param string $type backend type
 406      * @return array list of backends
 407      */
 408     function get_backend_list($type = '') {
 409         $ret = array();
 410         for ($i = 1 ; $i <= $this->numbackends ; $i++) {
 411             if (empty($type) || $type == $this->backends[$i]->btype) {
 412                 $ret[] = &$this->backends[$i];
 413             }
 414         }
 415         return $ret;
 416     }
 417
 418
 419     /* ========================== Public ======================== */
 420
 421     /**
 422      * Add a new backend.
 423      *
 424      * @param string $backend backend name (without the abook_ prefix)
 425      * @param mixed optional variable that is passed to the backend constructor.
 426      * See each of the backend classes for valid parameters
 427      * @return integer number of backends
 428      */
 429     function add_backend($backend, $param = '') {
 430         static $backend_classes;
 431         if (!isset($backend_classes)) {
 432             $backend_classes = array();
 433         }
 434         if (!isset($backend_classes[$backend])) {
 435             /**
 436               * Support backend provided by plugins. Plugin function must
 437               * return an associative array with as key the backend name ($backend)
 438               * and as value the file including the path containing the backend class.
 439               * i.e.: $aBackend = array('backend_template' => SM_PATH . 'plugins/abook_backend_template/functions.php')
 440               *
 441               * NB: Because the backend files are included from within this function they DO NOT have access to
 442               * vars in the global scope. This function is the global scope for the included backend !!!
 443               */
 444             $aBackend = do_hook('abook_add_class');
 445             if (isset($aBackend) && is_array($aBackend) && isset($aBackend[$backend])) {
 446                 require_once($aBackend[$backend]);
 447             } else {
 448                 require_once(SM_PATH . 'functions/abook_'.$backend.'.php');
 449             }
 450             $backend_classes[$backend] = true;
 451         }
 452         $backend_name = 'abook_' . $backend;
 453         $newback = new $backend_name($param);
 454         //eval('$newback = new ' . $backend_name . '($param);');
 455         if(!empty($newback->error)) {
 456             $this->error = $newback->error;
 457             return false;
 458         }
 459
 460         $this->numbackends++;
 461
 462         $newback->bnum = $this->numbackends;
 463         $this->backends[$this->numbackends] = $newback;
 464
 465         /* Store ID of first local backend added */
 466         if ($this->localbackend == 0 && $newback->btype == 'local') {
 467             $this->localbackend = $this->numbackends;
 468             $this->localbackendname = $newback->sname;
 469         }
 470
 471         return $this->numbackends;
 472     }
 473
 474
 475     /**
 476      * create string with name and email address
 477      *
 478      * This function takes a $row array as returned by the addressbook
 479      * search and returns an e-mail address with the full name or
 480      * nickname optionally prepended.
 481      * @param array $row address book entry
 482      * @return string email address with real name prepended
 483      */
 484     function full_address($row) {
 485         global $addrsrch_fullname, $data_dir, $username;
 486         $prefix = getPref($data_dir, $username, 'addrsrch_fullname');
 487         if (($prefix != "" || (isset($addrsrch_fullname) &&
 488             $prefix == $addrsrch_fullname)) && $prefix != 'noprefix') {
 489             $name = ($prefix == 'nickname' ? $row['nickname'] : $row['name']);
 490             return $name . ' <' . trim($row['email']) . '>';
 491         } else {
 492             return trim($row['email']);
 493         }
 494     }
 495
 496     /**
 497      * Search for entries in address books
 498      *
 499      * Return a list of addresses matching expression in
 500      * all backends of a given type.
 501      * @param string $expression search expression
 502      * @param integer $bnum backend number. default to search in all backends
 503      * @return array search results
 504      */
 505     function search($expression, $bnum = -1) {
 506         $ret = array();
 507         $this->error = '';
 508
 509         /* Search all backends */
 510         if ($bnum == -1) {
 511             $sel = $this->get_backend_list('');
 512             $failed = 0;
 513             for ($i = 0 ; $i < sizeof($sel) ; $i++) {
 514                 $backend = &$sel[$i];
 515                 $backend->error = '';
 516                 $res = $backend->search($expression);
 517                 if (is_array($res)) {
 518                     $ret = array_merge($ret, $res);
 519                 } else {
 520                     $this->error .= "\n" . $backend->error;
 521                     $failed++;
 522                 }
 523             }
 524
 525             /* Only fail if all backends failed */
 526             if( $failed >= sizeof( $sel ) ) {
 527                 $ret = FALSE;
 528             }
 529
 530         } elseif (! isset($this->backends[$bnum])) {
 531             /* make sure that backend exists */
 532             $this->error = _("Unknown address book backend");
 533             $ret = false;
 534         } else {
 535
 536             /* Search only one backend */
 537
 538             $ret = $this->backends[$bnum]->search($expression);
 539             if (!is_array($ret)) {
 540                 $this->error .= "\n" . $this->backends[$bnum]->error;
 541                 $ret = FALSE;
 542             }
 543         }
 544
 545         return( $ret );
 546     }
 547
 548
 549     /**
 550      * Sorted search
 551      * @param string $expression search expression
 552      * @param integer $bnum backend number. default to search in all backends
 553      * @return array search results
 554      */
 555     function s_search($expression, $bnum = -1) {
 556
 557         $ret = $this->search($expression, $bnum);
 558         if ( is_array( $ret ) ) {
 559             usort($ret, 'addressbook_cmp');
 560         }
 561         return $ret;
 562     }
 563
 564
 565     /**
 566      * Lookup an address by alias.
 567      * Only possible in local backends.
 568      * @param string $alias
 569      * @param integer backend number
 570      * @return array lookup results. False, if not found.
 571      */
 572     function lookup($alias, $bnum = -1) {
 573
 574         $ret = array();
 575
 576         if ($bnum > -1) {
 577             if (!isset($this->backends[$bnum])) {
 578                 $this->error = _("Unknown address book backend");
 579                 return false;
 580             }
 581             $res = $this->backends[$bnum]->lookup($alias);
 582             if (is_array($res)) {
 583                return $res;
 584             } else {
 585                $this->error = $this->backends[$bnum]->error;
 586                return false;
 587             }
 588         }
 589
 590         $sel = $this->get_backend_list('local');
 591         for ($i = 0 ; $i < sizeof($sel) ; $i++) {
 592             $backend = &$sel[$i];
 593             $backend->error = '';
 594             $res = $backend->lookup($alias);
 595             if (is_array($res)) {
 596                if(!empty($res))
 597               return $res;
 598             } else {
 599                $this->error = $backend->error;
 600                return false;
 601             }
 602         }
 603
 604         return $ret;
 605     }
 606
 607
 608     /**
 609      * Return all addresses
 610      * @param integer $bnum backend number
 611      * @return mixed array with search results or boolean false on error.
 612      */
 613     function list_addr($bnum = -1) {
 614         $ret = array();
 615
 616         if ($bnum == -1) {
 617             $sel = $this->get_backend_list('');
 618         } elseif (! isset($this->backends[$bnum])) {
 619             /* make sure that backend exists */
 620             $this->error = _("Unknown address book backend");
 621             $ret = false;
 622         } else {
 623             $sel = array(0 => &$this->backends[$bnum]);
 624         }
 625
 626         for ($i = 0 ; $i < sizeof($sel) ; $i++) {
 627             $backend = &$sel[$i];
 628             $backend->error = '';
 629             $res = $backend->list_addr();
 630             if (is_array($res)) {
 631                $ret = array_merge($ret, $res);
 632             } else {
 633                $this->error = $backend->error;
 634                return false;
 635             }
 636         }
 637
 638         return $ret;
 639     }
 640
 641     /**
 642      * Create a new address
 643      * @param array $userdata added address record
 644      * @param integer $bnum backend number
 645      * @return integer the backend number that the/ address was added
 646      * to, or false if it failed.
 647      */
 648     function add($userdata, $bnum) {
 649
 650         /* Validate data */
 651         if (!is_array($userdata)) {
 652             $this->error = _("Invalid input data");
 653             return false;
 654         }
 655         if (empty($userdata['firstname']) && empty($userdata['lastname'])) {
 656             $this->error = _("Name is missing");
 657             return false;
 658         }
 659         if (empty($userdata['email'])) {
 660             $this->error = _("E-mail address is missing");
 661             return false;
 662         }
 663         if (empty($userdata['nickname'])) {
 664             $userdata['nickname'] = $userdata['email'];
 665         }
 666
 667         /* Blocks use of space, :, |, #, " and ! in nickname */
 668         if (eregi('[ \\:\\|\\#\\"\\!]', $userdata['nickname'])) {
 669             $this->error = _("Nickname contains illegal characters");
 670             return false;
 671         }
 672
 673         /* make sure that backend exists */
 674         if (! isset($this->backends[$bnum])) {
 675             $this->error = _("Unknown address book backend");
 676             return false;
 677         }
 678
 679         /* Check that specified backend accept new entries */
 680         if (!$this->backends[$bnum]->writeable) {
 681             $this->error = _("Address book is read-only");
 682             return false;
 683         }
 684
 685         /* Add address to backend */
 686         $res = $this->backends[$bnum]->add($userdata);
 687         if ($res) {
 688             return $bnum;
 689         } else {
 690             $this->error = $this->backends[$bnum]->error;
 691             return false;
 692         }
 693
 694         return false;  // Not reached
 695     } /* end of add() */
 696
 697
 698     /**
 699      * Remove the entries from address book
 700      * @param mixed $alias entries that have to be removed. Can be string with nickname or array with list of nicknames
 701      * @param integer $bnum backend number
 702      * @return bool true if removed successfully. false if there s an error. $this->error contains error message
 703      */
 704     function remove($alias, $bnum) {
 705
 706         /* Check input */
 707         if (empty($alias)) {
 708             return true;
 709         }
 710
 711         /* Convert string to single element array */
 712         if (!is_array($alias)) {
 713             $alias = array(0 => $alias);
 714         }
 715
 716         /* make sure that backend exists */
 717         if (! isset($this->backends[$bnum])) {
 718             $this->error = _("Unknown address book backend");
 719             return false;
 720         }
 721
 722         /* Check that specified backend is writable */
 723         if (!$this->backends[$bnum]->writeable) {
 724             $this->error = _("Address book is read-only");
 725             return false;
 726         }
 727
 728         /* Remove user from backend */
 729         $res = $this->backends[$bnum]->remove($alias);
 730         if ($res) {
 731             return $bnum;
 732         } else {
 733             $this->error = $this->backends[$bnum]->error;
 734             return false;
 735         }
 736
 737         return FALSE;  /* Not reached */
 738     } /* end of remove() */
 739
 740
 741     /**
 742      * Modify entry in address book
 743      * @param string $alias nickname
 744      * @param array $userdata newdata
 745      * @param integer $bnum backend number
 746      */
 747     function modify($alias, $userdata, $bnum) {
 748
 749         /* Check input */
 750         if (empty($alias) || !is_string($alias)) {
 751             return true;
 752         }
 753
 754         /* Validate data */
 755         if(!is_array($userdata)) {
 756             $this->error = _("Invalid input data");
 757             return false;
 758         }
 759         if (empty($userdata['firstname']) && empty($userdata['lastname'])) {
 760             $this->error = _("Name is missing");
 761             return false;
 762         }
 763         if (empty($userdata['email'])) {
 764             $this->error = _("E-mail address is missing");
 765             return false;
 766         }
 767
 768         if (eregi('[\\: \\|\\#"\\!]', $userdata['nickname'])) {
 769             $this->error = _("Nickname contains illegal characters");
 770             return false;
 771         }
 772
 773         if (empty($userdata['nickname'])) {
 774             $userdata['nickname'] = $userdata['email'];
 775         }
 776
 777         /* make sure that backend exists */
 778         if (! isset($this->backends[$bnum])) {
 779             $this->error = _("Unknown address book backend");
 780             return false;
 781         }
 782
 783         /* Check that specified backend is writable */
 784         if (!$this->backends[$bnum]->writeable) {
 785             $this->error = _("Address book is read-only");;
 786             return false;
 787         }
 788
 789         /* Modify user in backend */
 790         $res = $this->backends[$bnum]->modify($alias, $userdata);
 791         if ($res) {
 792             return $bnum;
 793         } else {
 794             $this->error = $this->backends[$bnum]->error;
 795             return false;
 796         }
 797
 798         return FALSE;  /* Not reached */
 799     } /* end of modify() */
 800
 801
 802 } /* End of class Addressbook */
 803
 804 /**
 805  * Generic backend that all other backends extend
 806  * @package squirrelmail
 807  * @subpackage addressbook
 808  */
 809 class addressbook_backend {
 810
 811     /* Variables that all backends must provide. */
 812     /**
 813      * Backend type
 814      *
 815      * Can be 'local' or 'remote'
 816      * @var string backend type
 817      */
 818     var $btype      = 'dummy';
 819     /**
 820      * Internal backend name
 821      * @var string
 822      */
 823     var $bname      = 'dummy';
 824     /**
 825      * Displayed backend name
 826      * @var string
 827      */
 828     var $sname      = 'Dummy backend';
 829
 830     /*
 831      * Variables common for all backends, but that
 832      * should not be changed by the backends.
 833      */
 834     /**
 835      * Backend number
 836      * @var integer
 837      */
 838     var $bnum       = -1;
 839     /**
 840      * Error messages
 841      * @var string
 842      */
 843     var $error      = '';
 844     /**
 845      * Writeable flag
 846      * @var bool
 847      */
 848     var $writeable  = false;
 849
 850     /**
 851      * Set error message
 852      * @param string $string error message
 853      * @return bool
 854      */
 855     function set_error($string) {
 856         $this->error = '[' . $this->sname . '] ' . $string;
 857         return false;
 858     }
 859
 860
 861     /* ========================== Public ======================== */
 862
 863     /**
 864      * Search for entries in backend
 865      *
 866      * Working backend should support use of wildcards. * symbol
 867      * should match one or more symbols. ? symbol should match any
 868      * single symbol.
 869      * @param string $expression
 870      * @return bool
 871      */
 872     function search($expression) {
 873         $this->set_error('search is not implemented');
 874         return false;
 875     }
 876
 877     /**
 878      * Find entry in backend by alias
 879      * @param string $alias name used for id
 880      * @return bool
 881      */
 882     function lookup($alias) {
 883         $this->set_error('lookup is not implemented');
 884         return false;
 885     }
 886
 887     /**
 888      * List all entries in backend
 889      *
 890      * Working backend should provide this function or at least
 891      * dummy function that returns empty array.
 892      * @return bool
 893      */
 894     function list_addr() {
 895         $this->set_error('list_addr is not implemented');
 896         return false;
 897     }
 898
 899     /**
 900      * Add entry to backend
 901      * @param array userdata
 902      * @return bool
 903      */
 904     function add($userdata) {
 905         $this->set_error('add is not implemented');
 906         return false;
 907     }
 908
 909     /**
 910      * Remove entry from backend
 911      * @param string $alias name used for id
 912      * @return bool
 913      */
 914     function remove($alias) {
 915         $this->set_error('delete is not implemented');
 916         return false;
 917     }
 918
 919     /**
 920      * Modify entry in backend
 921      * @param string $alias name used for id
 922      * @param array $newuserdata new data
 923      * @return bool
 924      */
 925     function modify($alias, $newuserdata) {
 926         $this->set_error('modify is not implemented');
 927         return false;
 928     }
 929
 930     /**
 931      * Creates full name from given name and surname
 932      *
 933      * Handles name order differences. Function always runs in SquirrelMail gettext domain.
 934      * Plugins don't have to switch domains before calling this function.
 935      * @param string $firstname given name
 936      * @param string $lastname surname
 937      * @return string full name
 938      * @since 1.5.2
 939      */
 940     function fullname($firstname,$lastname) {
 941         /**
 942          * i18n: allows to control fullname layout in address book listing
 943          * first %s is for first name, second %s is for last name.
 944          * Translate it to '%2$s %1$s', if surname must be displayed first in your language.
 945          * Please note that variables can be set to empty string and extra formating
 946          * (for example '%2$s, %1$s' as in 'Smith, John') might break. Use it only for
 947          * setting name and surname order. scripts will remove all prepended and appended
 948          *  whitespace.
 949          */
 950         return trim(sprintf(dgettext('squirrelmail',"%s %s"),$firstname,$lastname));
 951     }
 952 }