≡ addressBooks.provider API
The address book provider API allows to add address books, which are not stored or cached by Thunderbird itself, but are handled completely by the extension. Address books created by the this API will forward all access requests to the WebExtension.
Possible use cases include:
- Implementing a custom storage.
- Implementing search-only address books that query a remote server.
So far, only the API for search-only address books has been implemented.
.. rst-class:: api-main-section
The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.
Hint
Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.
.. api-member:: :name: :permission:`addressBooks` :refid: address-books-provider-permission-address-books :refname: addressBooks Read and modify your address books and contacts.
.. rst-class:: api-permission-info
Note
The permission addressBooks is required to use messenger.addressBooks.provider.*.
.. rst-class:: api-permission-info
Note
The permission addressBooks is required to use messenger.addressBooks.provider.*.
.. rst-class:: api-main-section
.. api-section-annotation-hack:: -- [Added in TB 91]
Registering this listener will create a read-only address book, similar to an LDAP address book. When selecting this address book, users will first see no contacts, but they can search for contacts, which will fire this event. Contacts returned by the listener callback will be displayed as contact cards in the address book. Several listeners can be registered, to create multiple address books.
The event also fires for each registered listener (for each created read-only address book), when users type something into the mail composer's To: field, or into similar fields like the calendar meeting attendees field. Contacts returned by the listener callback will be added to the autocomplete results in the dropdown of that field.
Example:
messenger.addressBooks.provider.onSearchRequest.addListener(
async (node, searchString, query) => {
const response = await fetch(
"https://people.acme.com/?query=" + searchString
);
const json = await response.json();
return {
isCompleteResult: true,
// Return an array of ContactProperties as results.
results: json.map(contact => ({
DisplayName: contact.name,
PrimaryEmail: contact.email,
})),
};
},
{
addressBookName: "ACME employees",
isSecure: true,
}
);.. api-header::
:label: Parameters for onSearchRequest.addListener(listener, parameters)
.. _address^books.provider.on^search^request.listener(node, search^string, query):
.. api-member::
:name: ``listener(node, searchString, query)``
:refid: address-books-provider-on-search-request-listener-node-search-string-query
:refname: listener(node, searchString, query)
A function that will be called when this event occurs.
.. _address^books.provider.on^search^request.parameters:
.. api-member::
:name: ``parameters``
:refid: address-books-provider-on-search-request-parameters
:refname: parameters
:type: (object)
Descriptions for the address book created by registering this listener.
.. _address^books.provider.on^search^request.parameters.address^book^name:
.. api-member::
:name: [``addressBookName``]
:refid: address-books-provider-on-search-request-parameters-address-book-name
:refname: addressBookName
:type: (string, optional)
The name of the created address book. If not provided, the name of the extension is used.
.. _address^books.provider.on^search^request.parameters.id:
.. api-member::
:name: [``id``]
:refid: address-books-provider-on-search-request-parameters-id
:refname: id
:type: (string, optional)
The unique identifier of the created address book. If not provided, a unique identifier will be generated for you.
.. _address^books.provider.on^search^request.parameters.is^secure:
.. api-member::
:name: [``isSecure``]
:refid: address-books-provider-on-search-request-parameters-is-secure
:refname: isSecure
:type: (boolean, optional)
Whether the address book search queries are using encrypted protocols like HTTPS.
.. api-header::
:label: Parameters passed to the listener function
.. _address^books.provider.on^search^request.node:
.. api-member::
:name: ``node``
:refid: address-books-provider-on-search-request-node
:refname: node
:type: (:ref:`address^books.^address^book^node`)
.. _address^books.provider.on^search^request.search^string:
.. api-member::
:name: [``searchString``]
:refid: address-books-provider-on-search-request-search-string
:refname: searchString
:type: (string, optional)
The search text that the user entered. Not available when invoked from the advanced address book search dialog.
.. _address^books.provider.on^search^request.query:
.. api-member::
:name: [``query``]
:refid: address-books-provider-on-search-request-query
:refname: query
:type: (string, optional)
The boolean query expression corresponding to the search.
.. note::
This parameter may change in future releases of Thunderbird.
.. api-header::
:label: Expected return value of the listener function
.. _address^books.provider.on^search^request.returns:
.. api-member::
:refid: address-books-provider-on-search-request-returns
:type: object
.. _address^books.provider.on^search^request.returns.is^complete^result:
.. api-member::
:name: ``isCompleteResult``
:refid: address-books-provider-on-search-request-returns-is-complete-result
:refname: isCompleteResult
:type: (boolean)
:annotation: -- [Added in TB 140]
.. _address^books.provider.on^search^request.returns.results:
.. api-member::
:name: ``results``
:refid: address-books-provider-on-search-request-returns-results
:refname: results
:type: (array of :ref:`contacts.^contact^properties`)
:annotation: -- [Added in TB 140]
.. api-header:: :label: Required permissions - :permission:`addressBooks`