Source for file addressbook.php

Documentation is available at 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: addressbook.php,v 1.100 2006/08/31 05:43:18 tokul Exp $
  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. }

Documentation generated on Sat, 07 Oct 2006 16:08:47 +0300 by phpDocumentor 1.3.0RC6