Places/AsyncAPIsForSync: Difference between revisions

Jump to navigation Jump to search

Places/AsyncAPIsForSync (view source)

Revision as of 03:46, 12 November 2010

5,359 bytes added ,  12 November 2010
→‎Detailed Proposal: Bookmark API propospal
No edit summary
(→‎Detailed Proposal: Bookmark API propospal)
Line 47: Line 47:
==Detailed Proposal==
==Detailed Proposal==


Introduce
The new methods can be added to a new interface.  Maybe nsIBookmarksService (and it only ever does async stuff)?


* getBookmarkInfoAsync()
The only thing not covered here so far is livemarks.  Not sure if it's worth an API for them or not (can we get data on how many people store now?).
* insertBookmarkAsync()
* updateBookmarkAsync()


that return/take in as much information as we keep about bookmarks.
=== nsIAnnotationInfo ===


TODO flesh these out
/**
  * Interface that describes an annotation.
  */
interface nsIAnnotationInfo : nsISupports
{
  readonly AUTF8String name;
  readonly nsIVariant value;
  readonly long flags;
  readonly unsigned short expiration;
}


Ideally, we could use this for a future async annotation service.  For now, it's just purposed for nsIBookmarkInfo.
=== nsIBookmarkInfo ===
/**
  * Interface that describes a bookmark.
  */
interface nsIBookmarkInfo : nsISupports
{
  readonly ACString guid;
  readonly long long id;
  readonly unsigned short type;
  readonly long long parentId;
  readonly ACString parentGuid;
  readonly long index;
  readonly nsIURI uri;
  readonly AString keyword;
  readonly AString title;
  /**
    * An array of nsIAnnotationInfo objects for the bookmark.
    */
  readonly nsIVariant annotations;
}
The idea here is that this interface will be returned and given to places APIs when you ask for information about a bookmark, and when you want to add a bookmark.  Because we have the type present, this will handle bookmarks, folders, separators, and dynamic containers (which, if I recall correctly, handles microsummaries and live bookmarks).
I included guids here, which makes this gated (possibly) on {{bug|607117}}.
Not clear to me if we need tags on here or not.  Need input from the Sync team.
=== nsIBookmarkInfoCallback ===
interface nsIBookmarkInfoCallback : nsISupports
{
  /**
    * Called when one of the bookmark methods is done with its work.
    *
    * @param aBookmarkInfo
    *        The information about the bookmark, or undefined if nothing was found.
    */
  void onComplete(in nsIBookmarkInfo aBookmarkInfo);
}
This should be marked with [function] so JS consumers can just pass a function in if they want.
=== getBookmarkInfo ===
/**
  * Gets all information known about a bookmark.  Callers must specify the id, guid, or the URI of the bookmark in question.
  *
  * @param aInfo
  *        The bookmark info object that contains the id xor the guid xor the URI of the bookmark.
  * @param aCallback
  *        The object/function to notify when we have the information about the bookmark.
  */
void getBookmarkInfo(in nsIBookmarkInfo aInfo,
                      in nsIBookmarkInfoCallback aCallback);
Consumers would do something like this:
bs.getBookmarkInfo({guid:"..."}, function(aInfo) { ... });
C++ consumers won't be happy, but I'm not sure I care.
=== insertBookmark ===
/**
  * Inserts a bookmark.  Required fields on nsIBookmarkInfo are:
  *  - parentId or parentGuid
  *  - uri
  *  - title
  * Everything else is optional.
  *
  * @param aInfo
  *        The bookmark info object that contains the data needed.
  * @param aCallback
  *        The object/function to notify when we have added the bookmark.
  */
void insertBookmarkWithInfo(in nsIBookmarkInfo aInfo,
                            in nsIBookmarkInfoCallback aCallback);
Need to document about everything that would make us throw.  Also, how do we handle errors?  Want to keep the callback simple, ideally.
=== insertBookmarksWithInfo ===
/**
  * Inserts many bookmarks.  Just like insertBookmarkWithInfo otherwise.
  *
  * @param aInfo
  *        The bookmark info objects that contain the data needed.
  * @param aCallback
  *        The object/function to notify when we have added each bookmark.
  */
void insertBookmarksWithInfo([array, size_is(aLength) in nsIBookmarkInfo aInfo,
                              in unsigned long aLength,
                              in nsIBookmarkInfoCallback aCallback);
Just like insertBookmarkWithInfo, but takes a big array of bookmark info and does it all at once.  This is basically the batch mode version.  I suspect mak and I are going to debate how to best do batch mode, so this may change a lot still.
=== updateBookmarkWithInfo ===
/**
  *
  * Update the information about a bookmark.  Callers must specify the id, guid, xor the URI of the bookmark in question.
  *
  * @param aIdentifier
  *        The bookmark info object that contains the id xor the guid xor the URI of the bookmark.
  * @param aInfo
  *        The information to update about the bookmark.
  * @param aCallback
  *        The object/function to notify when we have updated the information about the bookmark.
  */
void updateBookmarkInfo(in nsIBookmarkInfo aIdentifier,
                        in nsIBookmarkInfo aInfo,
                        in nsIBookmarkInfoCallback aCallback);
=== updateBookmarksWithInfo ===
/**
  * Updates many bookmarks.  Just like updateBookmarkWithInfo otherwise.  aIdentifiers and aInfo must have a 1:1 mapping.
  *
  * @param aIdentifiers
  *        Array of bookmark info objects that contains the id xor the guid xor the URI of the bookmarks.
  * @param aInfo
  *        Array of information to update about the bookmark.
  * @param aCallback
  *        The object/function to notify when we have added each bookmark.
  */
void updateBookmarksWithInfo([array, size_is(aLength) in nsIBookmarkInfo aIdentifiers,
                              [array, size_is(aLength) in nsIBookmarkInfo aInfo,
                              in unsigned long aLength,
                              in nsIBookmarkInfoCallback aCallback);


=History=
=History=
Comrade693
590

edits

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

Navigation menu