[imp] _prefs_hook_fullname

[Otto Stolz]

Hello,

finally, my  _prefs_hook_fullname routine for Horde 3.1.2
and Imp H3 4.1.2 is working, so here is an outline of its
interfaces.

Meanwhile, I have Horde configured to allow login from Imp.
So the observations reported below hold for this case.

On 2006-08-08, I had written:
> - prefs_hook_fullname is invoked without an argument,
>   the $imp array is NULL,
>   and any and all of the following function calls yield NULL:
>   · Auth::getAuth()
>   · Auth::getCredential('user_name')
>   · Auth::getCredential('username')
>   · NLS::getCharset()
> - consequently, _prefs_hook_fullname yields NULL.

This is only partially true. Actually, _prefs_hook_fullname
is invoked *2 times* during Horde login, and *3 times*
during logout. Only the 2nd time during login, _prefs_hook_fullname
gets enough information to yield a sensible result. So it is
wise to code a shortcut into _prefs_hook_fullname to avoid
needless, time-consuming LDAP requests when there is no
argument to _prefs_hook_fullname.

Horde rather should invoke _prefs_hook_fullname just once,
when the user credentials have been obtained from the login
screen. This would enhance both efficiency and clarity of
the API.

_prefs_hook_fullname's result (if not NULL) is inserted into
the Welcome line of the Imp screen, and in the From headers
of outgoining e-mail. It should be encoded in the
current character set, as yielded by NLS::getCharset();
For outgoing mail, Imp will later encode it, in compliance with
RFC 2047, in the charset chosen by the user for transmission
of the respective message.

Best wishes,
   Otto Stolz

~~~~~~~~~~~~~~~~ Example ~~~~~~~~~~~~~~~~~

/* string function _prefs_hook_fullname (string $user):
  * Gets the cn from LDAP-Server in charge.
  * Activation in horde/conf/prefs.php.
  * Attention: Login must be via Imp, so $imp['server'] will be defined.

  * 2006-08-22 by <Otto.Stolz at uni-konstanz.de>
**/

if (!function_exists('_prefs_hook_fullname')) :
   function _prefs_hook_fullname($user = null)
   { global $imp;      // Imp Session data
     global $servers;  // from horde/imp/config/servers.php

     if (is_null($user)) {$user = Auth::getAuth();}
        // Dunno whether this is really useful

     if (empty($user)) : // this happens 80% of the invocations
       $name = '';
     else :
       switch ($imp['server']):
       case $servers['Informatik']['server']:
         $ldapServer  = 'ldap.inf.example.com';
         $ldapPort    = '389';
         $searchBase  = 'ou=People,dc=inf,dc=example,dc=de';
         $searchArg   = 'uid=' . $user;
         $ldapcharset = 'ascii';
         ldap_set_option(NULL, LDAP_OPT_DEBUG_LEVEL, 7);
         break;
       case $servers['RZ-Cyrus']['server']:
       default:
         $ldapServer = 'ldap.rz.example.com';
         $ldapPort = '389';
         $searchBase = 'ou=people,o=example,c=de';
         $searchArg   = 'uid=' . $user;
         $ldapcharset = 'utf-8';
         break;
       endswitch;
       $ds           = @ldap_connect($ldapServer, $ldapPort);
       $searchResult = @ldap_search($ds, $searchBase, $searchArg);
       $information  = @ldap_get_entries($ds, $searchResult);
       $name         = $information[0]['cn'][0];
       ldap_close($ds);

       $outputcharset = NLS::getCharset();
       if ($ldapcharset != $outputcharset) :
          $name = String::convertCharset( $name
                                        , $ldapcharset
                                        , $outputcharset
                                        );
       endif;
     endif;
     return $name;
   }
endif;