Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.IEmailAddressResolver

Timestamp:

Dec 6, 2014, 12:56:11 PM (9 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.notification.api.IEmailAddressResolver

@@ +1 @@
+== Extension Point : ''IEmailAddressResolver'' ==
+
+||'''Interface'''||''IEmailAddressResolver''||'''Since'''||[wiki:TracDev/ApiChanges/1.1.3#IEmailAddressResolver 1.1.3]||
+||'''Module'''||''trac.notification''||'''Source'''||[source:psuter/trac/notification/api.py@advanced-notification-mail-distribution#/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.
+
+== 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_session(sid, authenticated):
+        address = None
+        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})' % sid,
+                                     ['mail']):
+            if 'mail' in entry:
+                address = entry['mail']
+        ld.unbind_s()
+        return address
+}}}
+
+== Available Implementations ==
+
+* [source:trunk/trac/ticket/notification/mail.py trac.ticket.notification.mail.SessionEmailResolver]
+
+== Additional Information and References ==
+
+ * [apiref:trac.notification.api.IEmailAddressResolver-class epydoc]
+ * [apidoc:api/trac_notification#trac.notification.api.IEmailAddressResolver API Reference]
+ * Related tickets:
+   * #2766 introduced the `ignore_domains` option after so user names that look like email addresses are recognized correctly.
+   * #4372 introduced the `admit_domains` option so email addresses with uncommon domains are recognized correctly.
+
+=== History
+ * This interface originated in th:AnnouncerPlugin as `IAnnouncementAddressResolver`.
+ * [wiki:TracDev/ApiChanges/1.1.3#IEmailAddressResolver 1.1.3]: Integrated `IEmailAddressResolver` in Trac as part of [wiki:TracDev/Proposals/AdvancedNotification this proposal] (#3517)
+   * Renamed `get_address_for_name()` to `get_address_for_session()`.