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