Bookmarks Data API

The goal of this is to create a Bookmarks Data API that can support all the various sorts of things we want to be able to do with bookmarks (smart bookmarks, live bookmarks, remote bookmarks, shared bookmarks, live imported bookmarks, etc etc etc). The implementations of these bits aren't relevant to this API, however the API should make it possible to do all of those.

To use regular bookmarks and live bookmarks as an example: there would be a provider with a type of "simple" for regular bookmarks, and a provider with a type of "rss" for live bookmarks.

the simple provider's bmIBookmarkItem implementation wouldn't have much other than just the URI and the name. It would return true for all canBeContainedBy queries. The bmIBookmarkContainer would also be straightforward, and would return true for all canContain queries. For serialization, the container would just ask each child to serialize itself, chain these together, add some data (such as its own name and id), and return.

The live bookmarks provider would have its own implementation of bmIBookmarkContainer and bmIBookmarkItem; the container would reference a particular URL (which is what it would serialize, along with maybe information about items that have been visited), and it would create a bunch of bmIBookmarkItems (bmRSSBookmarkItem?) that would have URIs for the individual entries. bmLivemark would be a bmIBookmarkContainer with readOnly = false and containerReadOnly = true. Because these are read-only, the canContain/canBeContainedBy values don't really matter.

There is a Bookmarks Use Cases page if you would like to describe and discuss user-level Bookmark behaviours and use cases.

/*
 * The Provider is responsible for creating new bookmark nodes.
 * It is used as a service; one provider must exist per bookmark
 * node type.
 */

[scriptable, uuid(230e3f93-ce0b-48e1-ad40-e51cb6b8b814)]
interface bmIBookmarkProvider : nsISupports {
  /**
   * The name of this provider's bookmark types, as displayed in the URI.
   * Should be localized!
   */
  readonly attribute AUTF8String name;

  /**
   * The overlay that should be added to the properties dialog box
   * when a node from this provider is edited.
   */
  readonly attribute nsIURI propertiesOverlayURI;

  /**
   * Create a new bookmark node from this provider.
   *
   * @returns a new bmIBookmarkNode instance
   */
  bmIBookmarkNode createBookmark();

  /**
   * Deserialize a bookmark node for this provider from the
   * given serialized string.
   *
   * @param serialized a serialized string, returned by
   * bmIBookmarkNode's produced by this provider's serialize()
   * method.
   *
   * @returns a bmIBookmarkNode instance representing
   * the serialized data.
   *
   * @throws NS_ERROR_INVALID_ARG if deserialization failed, or the
   * string is otherwise invalid.
   */
  bmIBookmarkNode deserializeBookmark(in AUTF8String serialized);
};

/*
 * The service is the main entrypoint for bookmark users; it provides
 * some convenience functions for creating bookmarks (that avoid the
 * caller having to use getService for the right provider), as well
 * as provides access to well-known bookmarks.
 */

[scriptable, uuid(5ee39c0f-74f1-48ed-990f-fd68f28028e0)]
interface bmIBookmarkService  : nsISupports {
  // convenience to avoid having to call getBookmarkByType(BookmarksRoot)
  attribute bmIBookmarkContainer bookmarksRoot;

  const unsigned long BookmarksRoot = 0;
  const unsigned long BookmarksToolbarFolder = 1;

  /**
   * Get a bookmark with the well-known type bmtype, which is
   * one of the constants defined in bookmarks.idl.
   *
   * @param bmtype well-known bookmark id
   *
   * @returns bmIBookmarkNode for the given bookmark id, or null
   * if that well-known bookmark type isn't present in the current
   * bookmarks hierarchy.
   *
   * @throws NS_ERROR_INVALID_ARG if bmtype is invalid.
   */
  bmIBookmarkNode getKnownBookmark(in string bmtype);

  /**
   * Get a bookmark by string id, which is bmIBookmarkNode.id.
   *
   * @param bmid the bookmark node's id which to return.
   *
   * @returns bmIBookmarkNode for the given id, or null
   * if bmid can't be found.
   */
  bmIBookmarkNode getBookmarkById(in string bmid);

  /**
   * Create a bookmark with the given type.  This is a convenience
   * function, which will call getService to obtain a bmIBookmarkProvider
   * for that type, and call its createBookmark function.
   *
   * @param type the type of bookmark to be created
   *
   * @returns a new bookmark of the given type.
   *
   * @see bmIBookmarkProvider::createBookmark
   */
  bmIBookmarkNode createBookmark(in string type);

  /**
   * Add a new bookmark observer to be notified of changes.
   *
   * @param obs the observer to add.
   */
  void addObserver(in bmIBookmarkObserver obs);

  /**
   * Remove an observer.
   *
   * @param obs the observer to remove.
   *
   * @throws NS_ERROR_INVALID_ARG if the observer isn't found.
   */
  void removeObserver(in bmIBookmarkObserver obs);
};

/**
 * An observer for changes on all bookmarks in a given service's hierarchy.
 */
[scriptable, uuid(75c53908-7aa0-45ee-a68a-f2db90374742)]
interface bmIBookmarkObserver : nsISupports {
  // called after add
  void onBookmarkAdded (bmIBookmarkNode bmrk);

  // called before remove
  void onBookmarkRemoved (bmIBookmarkNode bmrk);

  // called after the bookmark's position in its parent
  // bookmarkContainer changes. oldIndex contains the
  // old index of this item in the container.
  void onBookmarkMoved (bmIBookmarkNode bmrk,
			unsigned long oldIndex);

  // called when a bookmark was changed
  void onBookmarkChanged (bmIBookmarkNode bmrk);
};


/**
 * A Node in the bookmarks tree.  Providers may derive
 * their own Node implementations from this interface, if
 * they wish to expose additional functionality.
 *
 * A bmIBookmarkNode may also implement a nsIPropertyBag or
 * nsIWritablePropertyBag for storing arbitrary data along
 * with the bookmark.
 */

[scriptable, uuid(be2823f2-79b4-4835-8a27-68efe378659f)]
interface bmIBookmarkNode : nsISupports {
  readonly attribute string id;
  readonly attribute string type;
  readonly attribute boolean readOnly;

  /**
   * The name of this node.  This is the "title" of the bookmark
   * in the UI.
   */
  attribute AUTF8String name;

  /**
   * The icon that should be displayed along with this bookmark.
   * The icon will be visible in the bookmarks menu, toolbar, manager,
   * and possibly other places.
   */
  attribute AUTF8String iconUrl;

  /**
   * The UTC time when this bookmark was created.
   */
  attribute PRTime creationTime;

  /**
   * Serialize this bookmark into a string that
   * bmIBookmarkProvider::deserializeBookmark for this node's
   * type understands.
   */
  AUTF8String serialize();

  /**
   * true if this bookmark node has been modified since the last
   * time it was flushed to disk.
   */
  readonly attribute boolean dirty;

  /**
   * true if this node can be contained in the given container.
   */
  boolean canBeContainedBy(in bmIBookmarkContainer bmcontainer);

  /**
   * Return a clone of this node, using some node type that has no
   * restrictions (e.g. that it can be contained by a simple
   * container -- in most cases, this would just use the simple item/container
   * types).  This would be used to copy an otherwise read-only
   * child, e.g. to save a RSS feed item into another folder.
   */
  bmIBookmarkNode cloneSimple();

};

/**
 * A generic non-container bookmark item, with a URI.
 */
[scriptable, uuid(47e221fd-b4c3-4dc0-99da-8109c2730981)]
interface bmIBookmarkItem : bmIBookmarkNode {
  /**
   * The URI for this item.
   */
  attribute nsIURI uri;

  /**
   * the last visited time for this bookmark.
   */
  attribute PRTime lastVisitedTime;
};

/**
 * A generic bookmark container, holding one or more child nodes.
 */
[scriptable, uuid(3c82858d-9a17-45b7-87ef-173c70b1067e)]
interface bmIBookmarkContainer : bmIBookmarkNode {
  /**
   * If the container contents are read only.  If
   * readOnly == false, but containerReadOnly == true,
   * then the container's name may be changed, but
   * its children cannot be modified (e.g. can't add
   * or remove a child).
   */
  readonly attribute boolean containerReadOnly;

  /**
   * The number of children this container has.
   */
  readonly attribute unsigned long numChildren;

  /**
   * Returns whether this container can contain a given node.
   */
  boolean canContain(in bmIBookmarkNode bmrk);

  // this is a similar interface to nsIArray/nsIMutableArray;
  // we could just require that all containers also implement
  // those, but this lets it be a bit clear
  bmIBookmarkNode getBookmarkAt(in unsigned long index);
  unsigned long indexOf(in bmIBookmarkNode bmrk);

  void getBookmarks(out unsigned long count,
		    [retval,array,size_is(count)] out bmIBookmarkNode bookmarks);

  /* The following will return NS_ERROR_XXX if called on a readonly container */
  void setBookmarks(in unsigned long count,
		    [array,size_is(count)] in bmIBookmarkNode bookmarks);
  void appendBookmark(in bmIBookmarkNode bmrk);
  void removeBookmark(in bmIBookmarkNode bmrk);
  void removeBookmarkAt(in unsigned long index);
  void removeBookmarkById(in string id);

  // inserts bmrk such that it becomes the new item at the given index.
  // any existing items are pushed forward one.  if index == numChildren,
  // this behaves just like appendBookmark.
  void insertElementAt(in bmIBookmarkNode bmrk, in unsigned long index);

  void clear();
};