Address Book Interfaces

  • Revision slug: Address_Book_Interfaces
  • Revision title: Address Book Interfaces
  • Revision id: 128237
  • Created:
  • Creator: Standard8
  • Is current revision? No
  • Comment 25 words added, 25 words removed

Revision Content

{{ tb_minversion_header("3") }}

This page contains a list of the interfaces that you'll will most likely hit when writing patches for the Address Book or writing extensions. The complete list of interfaces for the address book can be found here.

nsIAbManager

nsIAbManager is an interface to the main address book manager. It is used to create/delete address book instances and provides other utility functions such as the ability to export address books and add listeners to be notified about updates to address books.

RDF Obsolescence

In Thunderbird 2.x/SeaMonkey 1.1 the RDF service was used to get the list of all address books. For Thunderbird 3/SeaMonkey 2, using the RDF interfaces should be considered obsolete, except for using as datasources for tree elements. Instead use nsIAbManager.getDirectory and nsIAbManager.directories, although these interfaces aren't finalized, they are more convenient and will be heading towards the Address Book interfaces of the future.

nsIAbItem

nsIAbItem is the base class for all items that can be in address books. The only exception to this rule is that nsIAbDirectory items cannot currently be nested.

nsIAbItem contains functions that are generic to all items, at the moment this is one function, generateName that returns the name of an item suitable for display.

nsIAbCard

The nsIAbCard interface is used to represent and manipulate cards in the address book. The User Interfaces calls these cards "Contacts".

nsIAbCollection

nsIAbCollection represents collections of nsIAbItem. It contains information on the type of collection (remote, read-only, etc) and provides search functions.

{{ Note("At the moment, only nsIAbDirectory uses nsIAbCollection, it is intended that there will be another class (probably called nsIAbGroup) that will hold mailing lists and specific groups of email addresses.") }}

nsIAbDirectory

nsIAbDirectory are instances of nsIAbCollection that are saved in some form, this could be a file on the local disk, within another application or remotely over a network. On the user interface, each nsIAbDirectory is represented as an "Address Book".

The class contains methods for setting up the address book and for adding, modifying and removing nsIAbItem objects.

Address Book/Directory interfaces specific to types of Address Books

These interfaces should only be used where necessary for setting up address books of the appropriate type or accessing type specific functions. Keeping to non-type-specific interfaces (where possible) will mean that functions will work across different types of address book and help to provide a better user experience.

nsIAbMDBDirectory

A nsIAbMDBDirectory object is also an nsIAbDirectory and represents a mork-based address book. Address books of this type are stored within the user's profile.

The interface provides functions specific to setting up mork address books.

nsIAbLDAPDirectory

A nsIAbLDAPDirectory object is also an nsIAbDirectory and represents a remote LDAP address book.

Revision Source

<p>{{ tb_minversion_header("3") }}</p>
<p>This page contains a list of the interfaces that you'll will most likely hit when writing patches for the Address Book or writing extensions. The complete list of interfaces for the address book can be found <a class="external" href="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/" title="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/">here</a>.</p>
<h3>nsIAbManager</h3>
<p><code><a class="external" href="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/nsIAbManager.idl" title="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/nsIAbManager.idl">nsIAbManager</a></code> is an interface to the main address book manager. It is used to create/delete address book instances and provides other utility functions such as the ability to export address books and add listeners to be notified about updates to address books.</p>
<h4>RDF Obsolescence</h4>
<p>In Thunderbird 2.x/SeaMonkey 1.1 the RDF service was used to get the list of all address books. For Thunderbird 3/SeaMonkey 2, using the RDF interfaces should be considered <strong>obsolete</strong>, except for using as datasources for tree elements. Instead use <code>nsIAbManager.getDirectory</code> and <code>nsIAbManager.directories</code>, although these interfaces aren't finalized, they are more convenient and will be heading towards the Address Book interfaces of the future.</p>
<h3>nsIAbItem</h3>
<p><code><a class="external" href="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/nsIAbItem.idl" title="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/nsIAbItem.idl">nsIAbItem</a></code> is the base class for all items that can be in address books. The only exception to this rule is that <code>nsIAbDirectory</code> items cannot currently be nested.</p>
<p><code>nsIAbItem</code> contains functions that are generic to all items, at the moment this is one function, <code>generateName</code> that returns the name of an item suitable for display.</p>
<h3>nsIAbCard</h3>
<p>The <a class="internal" href="/en/nsIAbCard//Thunderbird3" title="En/NsIAbCard/Thunderbird3"><code>nsIAbCard</code></a> interface is used to represent and manipulate cards in the address book. The User Interfaces calls these cards "Contacts".</p>
<h3>nsIAbCollection</h3>
<p><code><a class="external" href="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/nsIAbCollection.idl" title="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/nsIAbCollection.idl">nsIAbCollection</a></code> represents collections of <code>nsIAbItem</code>. It contains information on the type of collection (remote, read-only, etc) and provides search functions.</p>
<p>{{ Note("At the moment, only <code>nsIAbDirectory</code> uses <code>nsIAbCollection</code>, it is intended that there will be another class (probably called <code>nsIAbGroup</code>) that will hold mailing lists and specific groups of email addresses.") }}</p>
<h3>nsIAbDirectory</h3>
<p><code><a class="external" href="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/nsIAbDirectory.idl" title="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/nsIAbDirectory.idl">nsIAbDirectory</a></code> are instances of <code>nsIAbCollection</code> that are saved in some form, this could be a file on the local disk, within another application or remotely over a network. On the user interface, each <code>nsIAbDirectory</code> is represented as an "Address Book".</p>
<p>The class contains methods for setting up the address book and for adding, modifying and removing <code>nsIAbItem</code> objects.</p>
<h4>Address Book/Directory interfaces specific to types of Address Books</h4>
<p>These interfaces should only be used where necessary for setting up address books of the appropriate type or accessing type specific functions. Keeping to non-type-specific interfaces (where possible) will mean that functions will work across different types of address book and help to provide a better user experience.</p>
<h5>nsIAbMDBDirectory</h5>
<p>A <code><a class="external" href="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/nsIAbMDBDirectory.idl" title="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/nsIAbMDBDirectory.idl">nsIAbMDBDirectory</a></code> object is also an <code>nsIAbDirectory</code> and represents a <a class="internal" href="/Special:Tags?tag=Mork&amp;language=en" title="Special:Tags?tag=Mork&amp;language=en">mork</a>-based address book. Address books of this type are stored within the user's profile.</p>
<p>The interface provides functions specific to setting up mork address books.</p>
<h5>nsIAbLDAPDirectory</h5>
<p>A <a class="external" href="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/nsIAbLDAPDirectory.idl" title="http://mxr.mozilla.org/comm-central/source/mailnews/addrbook/public/nsIAbLDAPDirectory.idl"><code>nsIAbLDAPDirectory</code></a> object is also an <code>nsIAbDirectory</code> and represents a remote LDAP address book.</p>
Revert to this revision