/*
 * BEGIN FLOCK GPL
 *
 * Copyright Flock Inc. 2005-2009
 * 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"


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

/**
 * 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 flockIBookmarkAccount.
 *
 * 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
 * flockILoginWebService interface.
 *
 * More documentation here:
 * http://developer.flock.com/wiki/Accounts_Management
 *
 * @see flockIBookmarkAccount
 * @see flockIWebServiceManager
 * @see flockILoginWebService
 */
[scriptable, uuid(d918069d-eee4-4b0c-a8f3-5795e4f0324c)]
interface flockIBookmarkWebService : flockILoginWebService {
  /**
   * Posts one bookmark to the server.
   *
   * @param aFlockListener (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
   */
  void publish(in flockIListener aFlockListener,
               in AString aAccountId,
               in flockIBookmark aBookmark);

  /**
   * Posts several bookmarks to the server.
   *
   * @param aFlockListener (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
   */
  void publishList(in flockIListener aFlockListener,
                   in AString aAccountId,
                   in nsISimpleEnumerator aBookmarkList);

  /**
   * Remove a bookmark from the server.
   *
   * @param aFlockListener (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
   */
  void remove(in flockIListener aFlockListener,
              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); else FALSE.
   */
  boolean exists(in AString aAccountId, in AString aURL);

  /**
   * Look in the local copy to see if a given bookmark is private 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) and is private.
   *         FALSE if the bookmark is public or doesn't exist on the server.
   */
  boolean isPrivate(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://developer.flock.com/wiki/Accounts_Management
 *
 * @see flockIBookmarkWebService
 */
[scriptable, uuid(abbb287a-79fa-46ea-9e6c-5431165e1f55)]
interface flockIBookmarkAccount : flockIWebServiceAccount {
};
