Directories

Contacts are organised into directories (also referred to as address books or just books). Every Thunderbird profile has two default directories – Personal Address Book and Collected Addresses – and users can add any number of additional directories.

There are various types of directory, allowing for various ways of gathering contacts. Each directory is responsible for its own data storage.

Directories implement nsIAbDirectory. (Mailing lists also partially implement this, but shouldn’t be considered directories. Mailing lists are weird.) They are managed by AddrBookManager (MailServices.ab) which implements nsIAbManager. Directory configuration is stored in preferences named ldap_2.servers. plus a string derived from the original name of the directory.

Useful properties

dirName - The human-readable name of the directory.
UID - Unique identifier for the directory.
URI/dirPrefId - Other ways to refer to the directory. These should be considered deprecated, but remain commonly used in the code.
childNodes - An array of mailing lists in the directory.
childCards - An array of contacts and mailing lists in the directory.

Useful methods

addCard/modifyCard/deleteCards - Modify the collection of cards in the directory.
cardForEmailAddress - Find a card for a given email address.
search - Find cards using matching the given search criteria.

Directory types

SQLiteDirectory

This is the default directory type and contacts are stored in an SQLite database in the user profile. The databases for the two default directories are abook.sqlite and history.sqlite, and additional directories are usually named abook-N.sqlite, where N is a number.

The class SQLiteDirectory inherits from an abstract class AddrBookDirectory which contains most of the code, leaving only the storage to be implemented by subclasses.

CardDAVDirectory

CardDAVDirectory inherits from SQLiteDirectory and adds CardDAV RFC6352 capabilities. CardDAV can be used for synchronising contacts with a remote server.

LDAPDirectory

LDAP servers can be queried for contacts using LDAPDirectory. Unlike other directory types, LDAPDirectory is read-only, and it won’t typically return a list of all contacts. Contacts can only be found by searching, and all search queries go to the server — although it is possible to download all contacts from the server for offline use.

nsAbOSXDirectory and nsAbOutlookDirectory

These provide read-only access to the system address books of macOS and Windows, respectively. They have very few users and are no longer really maintained or supported.

ExtSearchBook

This is a directory type that allows extensions to provide contacts in response to address book searches.