== Extension Point : ''INotificationDistributor'' ==

||'''Interface'''||''INotificationDistributor''||'''Since'''||[wiki:TracDev/ApiChanges/1.1#INotificationDistributor 1.1.3]||
||'''Module'''||''trac.notification''||'''Source'''||[source:trunk/trac/notification/api.py#/INotificationDistributor api.py]||


The ''INotificationDistributor'' sends [TracNotification notification] events over some distribution channel, like email.

== Purpose ==

Trac provides an extendible and flexible notification system, that historically has sent notifications by email. Notifications could however also be distributed by XMPP, SMS or any other messaging protocol.

== Usage ==

Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].

A simple `transports()` method lists the names of the supported transports (protocols / distribution channels). The `distribute()` method distributes a message to one or more recipients. It receives the following parameters:
* `transport`: The name of the transports that should be used. One of those returned by `transports()`.
* `recipients`: A list of `(sid, authenticated, address, format)` tuples. 
  * `sid`: The Trac session ID of the recipient (or `None`).
  * `authenticated`: `1` if the Trac session ID is authenticated, `0` otherwise.
  * `address`: A protocol specific address to send the notification to. If it is `None` the implementation might still be able to send the message to the recipient using the `sid` / `authenticated` information somehow. (E.g. the `EmailDistributor` falls back to [wiki:IEmailAddressResolver IEmailAddressResolver] implementations.)
  * `format`: MIME type of the message format to be used. 
* `event`: A `trac.notification.api.NotificationEvent` instance describing the event about which the recipients should be notified.

The `event` is supposed to be formatted into a message in the given `format` using a [wiki:trac.notification.api.INotificationFormatter INotificationFormatter].

== Examples ==

The following example distributes notifications by SMS. (The `sms` library does not exist. Several commercial SMS services provide real APIs.)

{{{#!python
from itertools import groupby
from operator import itemgetter

from trac.core import *
from trac.notification.api import INotificationDistributor, \
                                  INotificationFormatter

import sms

class SmsNotificationDistributor(Component):

    implements(INotificationDistributor)

    formatters = ExtensionPoint(INotificationFormatter)

    # INotificationDistributor methods

    def transports(self):
        return ['sms']

    def distribute(self, transport, recipients, event):
        if transport != 'sms':
            return

        # Group by message format:
        for format, group in groupby(recipients, itemgetter(3)):
            formatter = None
            for f in self.formatters:
                for style in f.styles(transport, event.realm):
                    if style == format:
                        formatter = f
            if formatter:
                message = formatter.format(transport, format, event)
                for sid, authenticated, address, format in group:
                    if address:                        
                        sms.send(message, address)
}}}

== Available Implementations ==

* [source:trunk/trac/notification/mail.py#/EmailDistributor trac.notification.mail.EmailDistributor]

== Additional Information and References ==

 * [apiref:trac.notification.api.INotificationDistributor-class epydoc]
 * [apidoc:api/trac_notification#trac.notification.api.INotificationDistributor API Reference]
 * Related to the [wiki:trac.notification.api.INotificationFormatter INotificationFormatter]

=== History
* This interface originated in th:AnnouncerPlugin as `IAnnouncementDistributor`.
* [wiki:TracDev/ApiChanges/1.1#INotificationDistributor 1.1.3]: Integrated `INotificationDistributor` in Trac as part of [wiki:TracDev/Proposals/AdvancedNotification this proposal] (#3517)
   * Added `format` in the `recipients` parameter to `distribute()`.