[horde] How to program Horde, and Imp, hooks?

[Otto Stolz]

Hello,

for historic reasons, the names of the mailboxes in our IMAP server
have no algorithmic relation to the e-mail addresses. E. g., the
mailbox (= IMAP account) for my test account is "pop15959", whilst
the e-mail address is "hugine.habicht at uni-konstanz.de". I can look
up the relation (in both directions), in our LDAP server.

Now,

1. I want the user to login, directly to Imp H3 4.1.2, with the
    local part of their respective e-mail address,
    e. g. "hugine.habicht"; then Imp will have to determine the proper
    IMAP account, via an LDAP request.

2. I also want the proper e-mail address, and the cn from the LDAP
    entry, to be used for the SMTP "MAIL FROM" command, and for the
    RFC 822 "From:" header.

Ad 1.

I guess that an _imp_hook_vinfo function in horde/config/hooks.php
could be used to find the proper IMAP account, but I cannot figure
out the exact interface for that function.
- imp/config/conf.xml says: "The hook will be used to set $imp['user']
   at login time." -- but then, what is the exact purpose of that
   variable? Will it be used as the IMAP account, or as the From address?
   Is it supposed to contain a complete e-mail address, or only the local
   part?
- The example in horde/config/hooks.php.dist mentions:
   · a global variable named $_SESSION['imp']['user'],
   · an argument called $type, that may have the value 'username',
     or 'vdomain', or possibly something else.
   But I cannot find any information on
   · the possible keys and values of the $_SESSION array,
     and their respective use and meaning,
   · the possible values of that $type argument,
     and their respective meaning,
   · the meaning, and syntax, of the result this function
     is supposed to yield.

Where can I find the missing documentation?
Or, if a kind soul would be willing to tell me, how
(with which arguments) will this function be invoked,
and what is it supposed to yield, in the "Hugine.Habicht"
example outlined above?

Ad 2.

I guess that the _imp_hook_vinfo function is also somehow involved
in determining the correct From address -- but how? I hope, this
will become evident from the answer on item 1, above.

I also guess, that I will have to provide another hook to find
the full name for the RFC 822 From header, probably 
_prefs_hook_fullname. But again, I cannot derive from the
examples provided in horde/config/hooks.php.dist how this
function will be invoked, and what it is supposed to yield.
- It will be invoked with one argument, named $user.  I guess,
   this is the user name supplied in the login screen -- or
   can it be some other string, possibly derived from
   _imp_hook_vinfo's result? And why do the examples provided
   check for an empty argument? And what string will be delivered
   by Auth::get_Auth() -- in the example outlined above, will it
   be "pop15959", or "hugine.habicht at uni-konstanz.de", or
   "hugine.habicht"?
- And what is the difference between Auth::get_Auth() and
   $_SESSION['imp']['user']?
- Is _prefs_hook_fullname supposed to yield the user's common name
   in UTF-8, or as an encoded-word, according to RFC 2047?

Thanks, in advance, for any enlightment.

Best wishes,
    Otto Stolz