/*
 * BEGIN FLOCK GPL
 *
 * Copyright Flock Inc. 2005-2008
 * http://flock.com
 *
 * This file may be used under the terms of the
 * GNU General Public License Version 2 or later (the "GPL"),
 * http://www.gnu.org/licenses/gpl.html
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * END FLOCK GPL
 */

#include "nsISimpleEnumerator.idl"
#include "flockIListener.idl"
#include "flockIWebService.idl"
#include "flockIManageableWebService.idl"


[scriptable, uuid(7bbd95a7-0656-464c-8560-73a21bd00be3)]
interface flockIBookmark : nsISupports {
  attribute string URL;
  attribute AString name;
  attribute AString description;
  attribute AString tags;
  attribute AString time;
};

/**
 * A Bookmark Web Service is a web service that stores a user's bookmarks
 * remotely and provides a means for the user to access them from a
 * multitude of client browsers.
 *
 * Flock is able to synchronize the user's in-browser bookmarks with
 * those in a flockIBookmarkWebServiceAccount.
 *
 * It is possible for a user to have more than one bookmark account, but
 * Flock is only able to synchronize with one account at a time.  For this
 * reason, Bookmark Web Services must be managed by the Web Service
 * Manager (flockIWebServiceManager) and hence must inherit from the
 * flockIManageableWebService interface.
 *
 * More documentation here:
 * http://wiki.flock.com/index.php?title=Danphe:AccountsAndServices
 *
 * @see flockIBookmarkWebServiceAccount
 * @see flockIWebServiceManager
 * @see flockIMangeableWebService
 */
[scriptable, uuid(5ECE2D74-4B7F-47E6-A319-F401909DAC43)]
interface flockIBookmarkWebService : flockIManageableWebService {
  /**
   * Posts one bookmark to the server
   * @param aListener (in) a listener to respond to successful publication or error
   * @param aAccountId (in) The account id (as the server would understand)
   * @param aBookmark (in) The bookmark to publish
   * @param aPrivate (in) true if private, false if public
   * @return nothing
   */
  void publish (in flockIListener aListener, in AString aAccountId,
                in flockIBookmark aBookmark, in boolean aPrivate);
  /**
   * Posts several bookmarks to the server
   * @param aListener (in) a listener to respond to successful publication or error
   * @param aAccountId (in) The account id (as the server would understand)
   * @param aBookmarkList (in) simpleEnumerator of flockIBookmark - the bookmarks to publish
   * @param aPrivate (in) true if private, false if public
   * @return nothing
   */
  void publishList (in flockIListener aListener, in AString aAccountId,
                    in nsISimpleEnumerator aBookmarkList, in boolean aPrivate);
  /**
   * Remove a bookmark from the server
   * @param aListener (in) a listener to respond to successful removal or error
   * @param aAccountId (in) The account id (as the server would understand)
   * @param aBookmark (in) The bookmark to remove
   * @return nothing
   */
  void remove (in flockIListener aListener,
               in AString aAccountId,
               in AString aBookmark);
  /**
   * Look in the local copy to see if a given bookmark exist on the server. No network call is done.
   * @param aAccountId (in) The account id (as the server would understand)
   * @param aURL (in) The URL to check for existance
   * @return true if the bookmark exists on the server (according to the local copy), false otherwise
   */
  boolean exists (in AString aAccountId, in AString aURL);
  /**
   * Return the URL of a given user
   * @param aAccountId (in) The account id, e.g. "flocktest"
   * @return the URL, e.g. "http://del.icio.us/flocktest"
   */
  AString getUserURL (in AString aAccountId);

};


/**
 * Represents an account with a bookmark web service.
 *
 * More documentation here:
 * http://wiki.flock.com/index.php?title=Danphe:AccountsAndServices
 *
 * @see flockIBookmarkWebService
 */
[scriptable, uuid(7F0738C0-5B07-11DB-B0DE-0800200C9A66)]
interface flockIBookmarkWebServiceAccount : flockIWebServiceAccount {
};
