MozillaWiki

Bookmarks Data API: Difference between revisions

Page Discussion

Bookmarks Data API (view source)

Revision as of 03:26, 7 July 2005

2,693 bytes added ,  7 July 2005
no edit summary
m (correct grammar)
No edit summary
Line 8: Line 8:


''There is a [[Bookmarks Use Cases]] page if you would like to describe and discuss user-level Bookmark behaviours and use cases.''
''There is a [[Bookmarks Use Cases]] page if you would like to describe and discuss user-level Bookmark behaviours and use cases.''
[[User:VladVukicevic|VladVukicevic]] 20:26, 6 Jul 2005 (PDT): Updated API incorporating comments, and expanding in-IDL documentation.  All bmI* became mozI*.  Removed the forwarded nsIMutableArray methods from mozIBookmarkContainer, and just required all mozIBookmarkContainer implementations to also implement nsIMutableArray.  All mozIBookmarkNode implementations also must implement nsIWritablePropertyBag.  Removed serialization/deserialization -- the property bag for each node should contain the entire state of that node, and will be serialized/deserialized automatically if the node is serialized.


<pre>
<pre>
/*
/*
  * The Provider is responsible for creating new bookmark nodes.
  * The Provider is responsible for creating new bookmark nodes.
Line 18: Line 19:


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


   /**
   /**
   * Create a new bookmark node from this provider.
  * Whether this provider can create items.
  */
  readonly attribute boolean canCreateItems;
 
  /**
  * Whether this provider can create containers.
  */
  readonly attribute boolean canCreateContainers;
 
  /**
   * Create a new bookmark item from this provider.  This item should
  * be initialized to some sane defaults; however, it is possile that
  * immediately after createItem() the node's property bag will
  * be filled in with properties read from storage to recreate a
  * bookmark item that was written to disk.
   *
   *
   * @returns a new bmIBookmarkNode instance
   * @returns a new mozIBookmarkItem instance for this provider.
   */
   */
   bmIBookmarkNode createBookmark();
   mozIBookmarkItem createItem();


   /**
   /**
   * Deserialize a bookmark node for this provider from the
   * Create a new bookmark container from this provider. This item
  * given serialized string.
   * should be initialized to some sane defaults; however, it is
   *
   * possile that immediately after createItem() the node's property
  * @param serialized a serialized string, returned by
   * bag will be filled in with properties read from storage to
   * bmIBookmarkNode's produced by this provider's serialize()
   * recreate a bookmark item that was written to disk.
   * method.
   *
  * @returns a bmIBookmarkNode instance representing
  * the serialized data.
   *
   *
   * @throws NS_ERROR_INVALID_ARG if deserialization failed, or the
   * @returns a new mozIBookmarkItem instance for this provider.
  * string is otherwise invalid.
   */
   */
   bmIBookmarkNode deserializeBookmark(in AUTF8String serialized);
   mozIBookmarkContainer createContainer();
};
};


Line 63: Line 73:


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


  /* well-known bookmark node identifiers
  * XXX - how do we actually set the BookmarksToolbarFolder?
  */
   const unsigned long BookmarksRoot = 0;
   const unsigned long BookmarksRoot = 0;
   const unsigned long BookmarksToolbarFolder = 1;
   const unsigned long BookmarksToolbarFolder = 1;
Line 76: Line 89:
   * @param bmtype well-known bookmark id
   * @param bmtype well-known bookmark id
   *
   *
   * @returns bmIBookmarkNode for the given bookmark id, or null
   * @returns mozIBookmarkNode for the given bookmark id, or null
   * if that well-known bookmark type isn't present in the current
   * if that well-known bookmark type isn't present in the current
   * bookmarks hierarchy.
   * bookmarks hierarchy.
Line 82: Line 95:
   * @throws NS_ERROR_INVALID_ARG if bmtype is invalid.
   * @throws NS_ERROR_INVALID_ARG if bmtype is invalid.
   */
   */
   bmIBookmarkNode getKnownBookmark(in string bmtype);
   mozIBookmarkNode getKnownBookmark(in string bmtype);


   /**
   /**
   * Get a bookmark by string id, which is bmIBookmarkNode.id.
   * Get a bookmark by string id, which is mozIBookmarkNode.id.
   *
   *
   * @param bmid the bookmark node's id which to return.
   * @param bmid the bookmark node's id which to return.
   *
   *
   * @returns bmIBookmarkNode for the given id, or null
   * @returns mozIBookmarkNode for the given id, or null
   * if bmid can't be found.
   * if bmid can't be found.
   */
   */
   bmIBookmarkNode getBookmarkById(in string bmid);
   mozIBookmarkNode getBookmarkById(in string bmid);
 
  /**
  * Get an array of bookmarks by property name and value.
  *
  * @param propName The property name to search for.
  * @param propValue The property value to search for.
  *
  * @returns An array of mozIBookmarkNodes.
  */
  void getBookmarksByProperty(in string propName, in nsIVariant propValue,
      out PRUint32 retCount,
      [retval,array,size_is(retCount)] out mozIBookmarkNode retNodes);


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


   /**
   /**
Line 112: Line 137:
   * @param obs the observer to add.
   * @param obs the observer to add.
   */
   */
   void addObserver(in bmIBookmarkObserver obs);
   void addObserver(in mozIBookmarkObserver obs);


   /**
   /**
Line 121: Line 146:
   * @throws NS_ERROR_INVALID_ARG if the observer isn't found.
   * @throws NS_ERROR_INVALID_ARG if the observer isn't found.
   */
   */
   void removeObserver(in bmIBookmarkObserver obs);
   void removeObserver(in mozIBookmarkObserver obs);
};
};


Line 128: Line 153:
  */
  */
[scriptable, uuid(75c53908-7aa0-45ee-a68a-f2db90374742)]
[scriptable, uuid(75c53908-7aa0-45ee-a68a-f2db90374742)]
interface bmIBookmarkObserver : nsISupports {
interface mozIBookmarkObserver : nsISupports {
   // called after add
   /**
   void onBookmarkAdded (bmIBookmarkNode bmrk);
  * Notify this observer that the bookmark was added.
  * Called after the actual add took place.
  *
  * @param bmrk The bookmark node that was added.
  */
   void onBookmarkAdded (in mozIBookmarkNode bmrk);


   // called before remove
   /**
   void onBookmarkRemoved (bmIBookmarkNode bmrk);
  * Notify this observer that the bookmark was removed.
  * Called before the actual remove takes place.
  *
  * @param bmrk The bookmark that will be removed.
  */
   void onBookmarkRemoved (in mozIBookmarkNode bmrk);
 
  /**
  * Notify this observer that the bookmark's position in the given
  * container has changed.  The old index of the bookmark within the
  * container is passed in, as well as the new index.  Note that the
  * new index is relative to the container without the old bookmark,
  * and indicates that the bookmark was inserted at that position and
  * any elements present there are pushed forward.
  *
  * @param container The bookmark container in which the bookmark moved.
  * @param bmrk The bookmark which moved.
  * @param oldIndex The bookmark's old index in the container.
  * @param newIndex The bookmark's new index in the container.
  */


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


   // called when a bookmark was changed
   /**
   void onBookmarkChanged (bmIBookmarkNode bmrk);
  * Notify this observer that a bookmark's information has changed.  This
  * will be called whenever any attributes like "name" are changed,
  * or whenever any properties on the property bag are modified.
  *
  * @param bmrk The bookmark which changed.
  */
   void onBookmarkChanged (in mozIBookmarkNode bmrk);
};
};




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


[scriptable, uuid(be2823f2-79b4-4835-8a27-68efe378659f)]
[scriptable, uuid(be2823f2-79b4-4835-8a27-68efe378659f)]
interface bmIBookmarkNode : nsISupports {
interface mozIBookmarkNode : nsISupports {
  /**
  * UUID for this node
  */
   readonly attribute string id;
   readonly attribute string id;
   readonly attribute string type;
 
  /**
  * The provider type; part of the provider's contractid
  */
   readonly attribute string providerType;
 
  /**
  * Whether this node is read-only; in other whether, the
  * name or any other properties can be changed.
  */
   readonly attribute boolean readOnly;
   readonly attribute boolean readOnly;


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


   /**
   /**
Line 194: Line 252:


   /**
   /**
   * true if this node can be contained in the given container.
   * Tests whether this node can be contained by the given container.
  * Both the container and the node have a chance to reject a parent-child
  * relationship (via canBeContainedBy and canContain).
  *
  * @param bmcontainer The container to test.
  *
  * @returns a boolean indicating whether this node can be contained
  * by the given container.
   */
   */
   boolean canBeContainedBy(in bmIBookmarkContainer bmcontainer);
   boolean canBeContainedBy(in mozIBookmarkContainer bmcontainer);


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


Line 213: Line 277:
  */
  */
[scriptable, uuid(47e221fd-b4c3-4dc0-99da-8109c2730981)]
[scriptable, uuid(47e221fd-b4c3-4dc0-99da-8109c2730981)]
interface bmIBookmarkItem : bmIBookmarkNode {
interface mozIBookmarkItem : mozIBookmarkNode {
   /**
   /**
   * The URI for this item.
   * The URI for this item.
Line 227: Line 291:
/**
/**
  * A generic bookmark container, holding one or more child nodes.
  * A generic bookmark container, holding one or more child nodes.
*
* Implementors of mozIBookmarkContainer MUST also implement
* nsIMutableArray, which will be used to actually modify
* the bookmark contents.
  */
  */
[scriptable, uuid(3c82858d-9a17-45b7-87ef-173c70b1067e)]
[scriptable, uuid(3c82858d-9a17-45b7-87ef-173c70b1067e)]
interface bmIBookmarkContainer : bmIBookmarkNode {
interface mozIBookmarkContainer : mozIBookmarkNode {
   /**
   /**
   * If the container contents are read only.  If
   * If the container contents are read only.  If
Line 236: Line 304:
   * its children cannot be modified (e.g. can't add
   * its children cannot be modified (e.g. can't add
   * or remove a child).
   * or remove a child).
  *
  * Note that a readOnly node implies a read-only
  * container.
   */
   */
   readonly attribute boolean containerReadOnly;
   readonly attribute boolean containerReadOnly;
Line 246: Line 317:
   /**
   /**
   * Returns whether this container can contain a given node.
   * Returns whether this container can contain a given node.
  *
  * @param bmrk The bookmark node to be tested.
  *
  * @returns a boolean indicating whether this container can
  * contain the given node or not.
   */
   */
   boolean canContain(in bmIBookmarkNode bmrk);
   boolean canContain(in mozIBookmarkNode 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);


  /**
  * Convenience function to avoid having to deal with an
  * enumerator in JavaScript.
  *
  * @returns an array of mozIBookmarkNodes in the current container.
  */
   void getBookmarks(out unsigned long count,
   void getBookmarks(out unsigned long count,
    [retval,array,size_is(count)] out bmIBookmarkNode bookmarks);
    [retval,array,size_is(count)] out mozIBookmarkNode 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();
};
};
</pre>
</pre>
VladVukicevic
Confirmed users, Bureaucrats and Sysops emeriti
792

edits

Retrieved from "https://wiki.allizom.org/Special:MobileDiff/13127"