--- title: API Contacts slug: Archive/B2G_OS/API/API_Contacts tags: - API - B2G - Contact - Contacts - Firefox OS - Guide translation_of: Archive/B2G_OS/API/Contacts_API ---

Non standard
Cette fonctionnalité n'est pas en voie de standardisation au W3C, mais elle est supportée par la plateforme Firefox OS. Bien que son implémentation puisse changer dans le futur et qu'elle n'est pas largement supportée par les différents navigateurs, elle est utilisable pour du code dédié aux applications Firefox OS.

Cette API est disponible sur Firefox OS pour des applications privilégiées ou certifiées seulement.

Résumé

L'API Contacts fournit une interface simple pour gérer les contacts des utilisateurs enregistrés dans le carnet d'adresses du système. Un cas pratique typique de l'API Contacts est l'implémentation d'une application de gestion de carnet d'adresses.

Note : Comme les informations personnelles des contacts utilisateurs constituent des données sensibles, seules les applications certifiées et privilégiées sont autorisées à accéder à cette API. L'utilisation des Activités Web pour déléguer les opérations sur les contacts est préconisée pour les autres applications.

Gestion des contacts

Les contacts enregistrés dans le carnet d'adresses du système sont accessibles par l'intermédiaire de la propriété navigator.mozContacts, elle-même étant une instance de l'interface ContactManager.

Ajout d'un contact

La création d'une nouvelle entrée dans le carnet d'adresses du système se fait en deux étapes :

  1. Instanciez un nouvel objet mozContact et remplissez toutes les propriétés nécéssaires. L'interface mozContact définit toutes les propriétés possibles pour un contact donné. Ces propriétés sont essentiellement les mêmes que celles définies dans la spécification vCard 4.0, avec les exceptions suivantes :
  2. Utilisez la méthode ContactManager.save() avec l'objet contact comme premier paramètre. La méthode renvoie un DOMRequest pour conserver une trace de la réussite ou de l'échec de l'opération d'enregistrement.
// première méthode : définir les propriétés directement
var person = new mozContact();
person.givenName  = ["John"];
person.familyName = ["Doe"];
person.nickname   = ["No kidding"];

// seconde méthode : utilisation d'un objet
var contactData = {
  givenName: ["John"],
  familyName: ["Doe"],
  nickname: ["No kidding"]
};

var person = new mozContact(contactData); // Firefox OS 1.3 prend un paramètre pour initialiser l'objet
if ("init" in person) {
  // Firefox OS 1.2 et précédents utilisent une méthode "init" pour initialiser l'objet
  person.init(contactData);
}

// enregistre le nouveau contact
var saving = navigator.mozContacts.save(person);

saving.onsuccess = function() {
  console.log('nouveau contact enregistré');
  // Cela actualise la personne telle qu'elle est enregistrée
  // Elle comporte son ID interne unique
  // Notez que saving.result est null ici
};

saving.onerror = function(err) {
  console.error(err);
};

Recherche d'un contact

Deux méthodes permettent de récupérer un contact depuis le carnet d'adresses du système :

Les deux méthodes attendent un paramètre qui est un objet défiinissant les options de filtres et de tri. ContactManager.getAll n'accepte que les options de tri. Ces dernières sont :

Et les options de filtre :

find renvoie un objet DOMRequest et getAll retourne un objet DOMCursor pour connaître la réussite ou l'échec d'une recherche.

Si la recherche réussit, son résultat est disponible dans la propriété DOMRequest.result, soit dans un tableau d'objets mozContact pour find, soit dans un unique objet mozContact pour getAll. Pour obtenir le résultat suivant dans la liste obtenue avec getAll, appelez la méthode continue() du curseur.

var options = {
  filterValue : "John",
  filterBy    : ["givenName","name","nickName"],
  filterOp    : "contains",
  filterLimit : 1,
  sortBy      : "familyName",
  sortOrder   : "ascending"
}

var search = navigator.mozContacts.find(options);

search.onsuccess = function() {
  if (search.result.length === 1) {
    var person = search.result[0];
    console.log("Trouvé :" + person.givenName[0] + " " + person.familyName[0]);
  } else {
    console.log("Désolé, il n'y a pas de tel contact.")
  }
};

search.onerror = function() {
  console.warn("Aïe ! Quelque chose ne va pas, aucun résultat !");
};

var allContacts = navigator.mozContacts.getAll({sortBy: "familyName", sortOrder: "descending"});

allContacts.onsuccess = function(event) {
  var cursor = event.target;
  if (cursor.result) {
    console.log("Trouvé : " + cursor.result.givenName[0] + " " + cursor.result.familyName[0]);
    cursor.continue();
  } else {
    console.log("Pas d'autre contact");
  }
};

allContacts.onerror = function() {
  console.warn("Quelque chose s'est mal passée ! :(");
};

Mise à jour d'un contact

Lors de l'obtention d'un contact par l'intermédiaire de find() ou de getAll() (ou après un appel réussi à save() pour un nouveau contact), celui-ci se voit attribuer des méta-données :

Actualiser un contact revient globalement à modifier les valeurs de ses propriétés puis à l'enregistrer via un appel à la méthode save().

Note : À chaque fois qu'un contact est ajouté, mis à jour ou supprimé, un événement contactchange est déclenché afin d'avoir un suivi de tous les changements apportés au carnet d'adresses du système. Cet événement peut être géré avec la propriété ContactManager.oncontactchange.

Suppression d'un contact

Un appel à la méthode ContactManager.remove() va tout simplement supprimer l'objet mozContact qui lui a été transmis.

Dans certains cas limites, il est aussi possible de se débarrasser de tous les contacts. Pour cela, utilisez ContactManager.clear(). Soyez prudent lors de l'appel de cette méthode ; il n'est pas possible de revenir en arrière.

Spécifications

Spécification État Commentaire
Contacts Manager API
La définition de 'Contacts Manager API' dans cette spécification.		 Obsolete  
vCard Format Specification IETF RFC RFC 6350

Compatibilité des navigateurs

Nous convertissons les données de compatibilité dans un format JSON. Ce tableau de compatibilité utilise encore l'ancien format car nous n'avons pas encore converti les données qu'il contient. Vous pouvez nous aider en contribuant !

Caractéristique Chrome Firefox (Gecko) Internet Explorer Opera Safari
support basique Pas de support Pas de support Pas de support Pas de support Pas de support
Caractéristique Android Chrome pour Android Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile
basic support Pas de support Pas de support 18.0 1.1 Pas de support Pas de support Pas de support

Voir aussi