Changes between Initial Version and Version 1 of TracDev/Proposals/AdvancedNotification/IEmailAddressResolver

Timestamp:

Nov 18, 2012, 12:21:15 AM (12 years ago)

Author:

Peter Suter

Comment:

Document the proposed IEmailAddressResolver extension point.

TracDev/Proposals/AdvancedNotification/IEmailAddressResolver

@@ +1 @@
+== Extension Point : ''IEmailAddressResolver'' ==
+
+||'''Interface'''||''IEmailAddressResolver''||'''Since'''||[wiki:TracDev/ApiChanges/1.1.1#IEmailAddressResolver 1.1.1]||
+||'''Module'''||''trac.notification''||'''Source'''||[source:trunk/trac/notification/api.py#/IEmailAddressResolver api.py]||
+
+The ''IEmailAddressResolver'' is a fallback mechanism for determining which email address should be used to send [TracNotification notifications].
+
+== Purpose ==
+
+Trac provides an extendible and flexible notification system, that historically has sent emails to the email address specified in the user preferences or in the CC, reporter or author fields.
+
+Now plugins can add additional ways to find an email address for a Trac session that has no email address specified in the user preferences.
+
+OPEN Is this even needed? The email distributor could just contain this logic. Maybe for directory services?
+
+== Usage ==
+
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
+
+The `get_address_for_session()` method returns the email address for the given session or `None`. The parameters are:
+* `sid`: The Trac session ID.
+* `authenticated`: 1 if the Trac session ID is authenticated, 0 otherwise.
+
+== Examples ==
+
+The following naively uses LDAP to retrieve the email address.
+
+{{{#!python
+import ldap
+
+from trac.core import *
+from trac.notification.api import IEmailAddressResolver
+
+class LdapEmailAddressResolver(Component):
+
+    implements(IEmailAddressResolver)
+
+    # IEmailAddressResolver methods
+    
+    def get_address_for_name(name, authenticated):
+        ld = ldap.initialize('ldap://localhost:1390')
+        ld.simple_bind_s()
+        for dn, entry in ld.search_s('ou=people,dc=example,dc=com',
+                                     ldap.SCOPE_SUBTREE,
+                                     '(cn={0}) % user,
+                                     ['mail']):
+            if 'mail' in entry:
+                return entry['mail']
+        ld.unbind_s()
+}}}
+
+== Available Implementations ==
+
+Only `trac.ticket.notification.mail.DefaultDomainEmailResolver` and `trac.ticket.notification.mail.SessionEmailResolver`  are part of core Trac.
+
+OPEN Are they even needed? The email distributor could just contain this logic.
+
+Various other resolvers might be part of th:AnnouncerPlugin.
+
+== Additional Information and References ==
+
+ * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.notification.api.IEmailAddressResolver-class.html epydoc]
+ * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_notification.html#trac.notification.api.IEmailAddressResolver API Reference]
+ * This interface originated in th:AnnouncerPlugin as `IAnnouncementAddressResolver`.
+   * DONE Renamed `get_address_for_name()` to `get_address_for_session()`.
+   * DONE Other distributors can not use the same interface (according to comment in th:AnnouncerPlugin's `XmppDistributor`) so this is email specific.
+   * TODO: Make it usable by multiple distributors?