/*
 * 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 "flockIListener.idl"
#include "flockISocialWebService.idl"
#include "flockIWebService.idl"
#include "flockIWebServiceAPI.idl"
#include "nsIWritablePropertyBag2.idl"
#include "nsISupports.idl"
#include "nsITransferable.idl"

/**
 * Digg API
 */
[scriptable, uuid(38f91ce3-8956-48bb-b8f7-001723e97c01)]
interface flockIDiggAPI : flockIWebServiceAPI {
  /**
   * Retrieves digg information for a particular URL.
   *
   * @param aURL (in) URL to get digg info for.
   * @param aFlockListener (in) listener to notify when activity is complete
   * @param aShouldGetTopStories (in) require top stories to refresh
   *
   * @see flockIDiggService#loadDiggInfo
   */
  void getDiggInformation(in AString aURL,
                          in flockIListener aFlockListener,
                          in PRBool aShouldGetTopStories);

  /**
   * Retrieves digg information for a particular Digg URL.
   *
   * @param aCleanTitle (in) Title from Digg URL, http://digg.com/{CLEAN_TITLE}
   * @param aFlockListener (in) listener to notify when activity is complete
   *
   * @see flockIDiggService#getDiggInfoByCleanTitle
   */
  void getDiggInfoByCleanTitle(in AString aCleanTitle,
                               in flockIListener aFlockListener);

  /**
   * Retrieves the friends list for a particular user.
   *
   * @param aUsername (in) name of user to retrieve information for
   * @param aFlockListener (in) listener to notify when activity is complete
   */
  void getFriends(in AString aUsername, in flockIListener aFlockListener);

   /**
   * Retrieves whether or not two users are friends
   *
   * @param aUsername (in) username of the first user to compare
   * @param aFriendUsername (in) username of the second user to compare
   * @param aFlockListener (in) listener to notify when activity is complete
   */
  void isFriend(in AString aUsername,
                in AString aFriendUsername,
                in flockIListener aFlockListener);

  /**
   * Retrieves user information from the Digg Service.
   *
   * @param aUsername (in) name of user to retrieve information for
   * @param aFlockListener (in) listener to notify when activity is complete
   */
  void getUser(in AString aUsername, in flockIListener aFlockListener);

  /**
   * Retrieves the top stories .
   *
   * @param aResults (in) A property bag to put any results in.
   * @param aFlockListener (in) listener to notify when activity is complete
   */
  void getTopStories(in nsIWritablePropertyBag2 aResults,
                     in flockIListener aFlockListener);

};


/**
 * Digg Service
 */
[scriptable, uuid(2cf3495d-abcd-4e27-9a9f-74e6baada822)]
interface flockIDiggService : flockIWebService {
  /**
   * Loads page rank information for a given URL.
   *
   * @param aURL (in) url to retrieve page rank information for
   * @param aFlockListener (in) listener to retrieve information
   * @param aShouldGetTopStories (in) require top stories to refresh
   *
   * @see flockIDiggAPI#getDiggInformation
   */
  void loadDiggInfo(in AString aURL,
                    in flockIListener aFlockListener,
                    in PRBool aShouldGetTopStories);

  /**
   * Retrieves the top stories.
   *
   * @param aListener (in) listener to notify when activity is complete
   */
  void getTopStories(in flockIListener aListener);

  /**
   * Loads page rank information for a given Digg URL.
   *
   * @param aCleanTitle (in) Title from Digg URL, http://digg.com/{CLEAN_TITLE}
   * @param aFlockListener (in) listener to notify when activity is complete
   *
   * @see flockIDiggAPI#getDiggInfoByCleanTitle
   */
  void getDiggInfoByCleanTitle(in AString aCleanTitle,
                               in flockIListener aFlockListener);
  

  /**
   * Retrieves friend activity information from the Digg Service batch format.
   *
   * @param aAccount (in) current logged in digg account
   * @param aFriendsIds (in) list of friends Ids
   * @param aFlockListener (in) listener to notify when activity is complete
   */
  void getFriendsActivity(in flockISocialAccount aAccount,
                          in nsIPropertyBag aFriendsIds,
                          in flockIListener aFlockListener);

  /**
   * Determines if friend determined by aUsername is friend or not 
   *
   * @param aUsername (in) username of the first user to compare
   * @param aFriendUsername (in) username of the second user to compare
   * @param aFlockListener (in) listener to notify when activity is complete
   */
  void isFriend(in AString aUsername,
                in AString aFriendUsername,
                in flockIListener aFlockListener);

};
