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