Using the Places tagging service

The tagging service, offered by the nsITaggingService interface, provides methods to tag and untag a URI, to retrieve URIs for a given tag, and to retrieve all tags for a URI.

Initiating the tagging service

Before using the tagging service, you need to obtain a reference to an instance of it:

var taggingSvc = Components.classes["@mozilla.org/browser/tagging-service;1"]
                           .getService(Components.interfaces.nsITaggingService);

Tagging a URI

The nsITaggingService.tagURI() method tags a URL with the given set of tags. Current tags set for the URL persist, and tags which are already set for the given URL are ignored.

taggingSvc.tagURI(uri("https://example.com/"), ["tag 1"]); //First argument = URI
                                                          //Second Argument = Array of tag(s)

where uri() is probably similar to makeURI().

Untagging a URI

nsITaggingService.untagURI() removes tags from a URL. From the given set of tags, a tag is ignored if it isn't set for the given URL.

tagginSvc.untagURI(uri("https://example.com/"), ["tag 1"]); //First argument = URI
                                                           //Second Argument = Array of tag(s)

Finding all URLs with a given tag

The nsITaggingService.getURIsForTag() method returns an array of all URLs tagged with the given tag.

var tag1uris = taggingSvc.getURIsForTag("tag 1"); //"tag 1" = given tag

Getting all tags associated with a URL

The nsITaggingService.getTagsForURI() method returns an array of all tags set for the given URL.

var tags = taggingSvc.getTagsForURI(uri("https://example.com/", {})); 
  //tags = an array of tags stored in https://example.com/