Using the Places livemark service

The livemark service, offered by the nsILivemarkService interface, is used to create, edit, and reload livemarks. You can also use it to check whether an item is a livemark.

Livemarks are bookmark folders that contain the most recent items from an RSS feed.

Initiating the livemark service

Before using the livemark service, you need to obtain an instance:

var livemarkService = Components.classes["@mozilla.org/browser/livemark-service;2"]
                                .getService(Components.interfaces.nsILivemarkService);

Creating a new livemark

The nsILivemarkService.createLivemark() method creates a new livemark.

var newLvmkId = livemarkService.createLivemark(parentFolderId, "Livemark name",
                                               uri("http://example.com/"), 
                                               uri("http://example.com/rss.xml"),
                                               -1);

The first parameter is the ID of the folder in which to create the livemark. The second parameter is the livemark's name as it will appear in the bookmark's title. The third parameter is the URI of the site the livemark was created from (specified as an nsIURI object. Fourth argument is the URI of the actual RSS feed. The last argument takes in the index to insert at, or -1 to append the new livemark to the end of the folder.

You can convert a string into an nsIURI using nsIIOService.

When creating livemarks during startup, you should use the nsILivemarkService.createLivemarkFolderOnly() to avoid HTTP traffic. This creates the encapsulating livemark without actually fetching the RSS feed's contents.

var bmsvc = Components.classes["@mozilla.org/browser/nav-bookmarks-service;1"].
                       getService(Components.interfaces.nsINavBookmarksService);
var root = bmsvc.bookmarksMenuFolder; // Item ID of the Bookmarks Menu
var newLvmkId = livemarkService.createLivemarkFolderOnly(bmsvc, root, "Livemark name",
                                                         uri("http://example.com/"), 
                                                         uri("http://example.com/rss.xml"),
                                                         -1);

The parameters here are the same as for nsILivemarkService.createLivemark(), except for the insertion of a new parameter at the beginning, which is the nsINavBookmarksService to use when creating the livemark.

Determine whether a folder is a livemark

You can use the nsILivemarkService.isLivemark() method to determine whether or not a given folder is a livemark container:

if (livemarkService.isLivemark(folderID)) {
  // it's a livemark
} else {
  // it's not a livemark
}

Accessing the container's site URI

The nsILivemarkService.getSiteURI() method lets you obtain the nsIURI of the website associated with a livemark container.

var siteURI = livemarkService.getSiteURI(newLvmkId); 
             //newLvmkId = see "Create a new livemark" for more detail.

getSiteURI() returns null if there is no URI for the specified livemark.

nsILivemarkService.setSiteURI() sets the URI of the website associated with a livemark container.

livemarkService.setSiteURI(newLvmkId, uri("http://newuri.com/"); 
                //newLvmkId = see "Create a new livemark" for more detail.

Accessing a livemark's feed URI

nsILivemarkService.getFeedURI() gets the URI of the syndication feed associated with a livemark container.

var feedURI = livemarkService.getFeedURI(newLvmkId);
              //newLvmkId = see "Create a new livemark" for more detail.

nsILivemarkService.setFeedURI() sets the URI of feed associated with a livemark container.

livemarkService.setFeedURI(newLvmkId, uri("http://foo.example.com/rss.xml"));
                //newLvmkId = see "Create a new livemark" for more detail.

Update behavior

Five seconds after the browser starts up, the livemark service's update timer is started. The update timer fires immediately, and then every 15 minutes thereafter.

When the update timer fires, it iterates over the list of livemarks, and will refresh a livemark *only* if it's expired.

The expiration time for a livemark is determined by using information provided by the server when the feed was requested, specifically nsICacheEntryInfo.expirationTime. If no information was provided by the server, the default expiration time is 1 hour.

Users can modify the default expiration time via the <tt>browser.bookmarks.livemark_refresh_seconds</tt> preference, which indicates the expiration time in seconds.

See also

• Places