/*
 * 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 "nsISupports.idl"
#include "nsISimpleEnumerator.idl"

#include "flockIListener.idl"
#include "nsIVariant.idl"
#include "nsIPropertyBag.idl"
#include "nsIStringBundle.idl"

interface flockIWebServiceAccount;


/**
 * Represents a third-party web service which supports user accounts.  This is
 * the base web service interface, and should be implemented by all web service
 * components.
 *
 * More documentation here:
 * http://wiki.flock.com/wiki/Accounts_Management
 *
 * @see flockIWebServiceAccount
 * @see flockIWebServiceManager
 * @see flockIManageableWebService
 */
[scriptable, uuid(e40ad26e-d2af-4a90-8bb1-85432c0fa6b0)]
interface flockIWebService : nsISupports {

  /** Descriptive title for the service, as recognized by end user */
  readonly attribute AString title;

  /** Internal name for the service, all lowercase, no punctuation */
  readonly attribute AString shortName;

  /** Standard favicon URL (chrome, or web) for this service */
  readonly attribute AString icon;

  /** Url to which to take the user for this service */
  readonly attribute AString url;

  /** Expose the contractId for matching with Identities */
  readonly attribute AString contractId;

  /** RDF node id for this service */
  readonly attribute AString urn;

  /** Whether Flock must know the account password for this service */
  readonly attribute boolean needPassword;

  /**
   * Possible value for the 'status' attribute.  STATUS_DOWN indicates that
   * Flock thinks this service is not currently available.
   *
   * @see status
   */
  const long STATUS_DOWN = 0;

  /**
   * Possible value for the 'status' attribute.  STATUS_UNKNOWN indicates that
   * Flock hasn't determined whether the service is currently available.
   *
   * @see status
   */
  const long STATUS_UNKNOWN = 1;

  /**
   * Possible value for the 'status' attribute.  STATUS_UP indicates that Flock
   * thinks this service is currently available.
   *
   * @see status
   */
  const long STATUS_UP = 2;

  /**
   * Flag indicating status of the web service.  Possible values are
   * STATUS_DOWN, STATUS_UNKNOWN, STATUS_UP.
   *
   * @see STATUS_DOWN
   * @see STATUS_UNKNOWN
   * @see STATUS_UP
   */
  readonly attribute long status;

  /**
   * A service may provide a localized resource. Use this method to gain access
   * to this resource.
   */
  nsIStringBundle getStringBundle();

  /**
   * A service may support multiple accounts per user.  Use this method to tell
   * Flock about an existing user account with this service.
   *
   * PRECONDITIONS:
   *  - The account must already exist with the service provider.  This
   *    function does *not* actually register a new account with the service
   *    provider.
   *  - The login/password for the account must already be registered with
   *    the flockAccountUtils service and must be retrievable with a call to
   *    {flockIAccountUtils}.getPassword(<service.URN>:<accountID>).
   *
   * @param aAccountID (in) The unique identifier used by this service to refer
   *        to this account.  This is sometimes equivalent to the login string,
   *        but not always.
   * @param aIsTransient (in) Boolean indicating whether this account should be
   *        created as a "transient" account.  (Transient accounts will exist
   *        only for this browser session.)
   * @param aListener (in) An optional flockIListener that can respond to
   *        success or failure of the add operation.
   * @return An account object which implements flockIWebServiceAccount.
   *
   * @see flockIListener
   */
  flockIWebServiceAccount addAccount(in AString aAccountID,
                                     in boolean aIsTransient,
                                     in flockIListener aListener);

  /**
   * Use this method to have Flock forget the account details for an existing
   * user account.
   *
   * @param aUrn (in) The RDF node id for the account to be forgotten.
   * @see flockIWebServiceAccount.remove
   */
  void removeAccount(in AString aUrn);

  /**
   * Retrieve a flockIWebServiceAccount object for the account with the
   * specified RDF node id.
   *
   * @param aUrn (in) the RDF node id for the account.
   * @return An account object which implements flockIWebServiceAccount.
   */
  flockIWebServiceAccount getAccount(in AString aUrn);

  /**
   * Retrieve a flockIWebServiceAccount object for the first matching
   * authenticated account.
   *
   * @return An account object which implements flockIWebServiceAccount.
   *         Returns null if no account exist or no account is authenticated;
   *         returns the first matching account if several accounts are
   *         authenticated.
   */
  flockIWebServiceAccount getAuthenticatedAccount();

  /**
   * Determines if the service should be hidden from view.  Services are not
   * disabled, this just prevents them from being promoted in the UI.
   *
   * @return true if service should be hidden.
   */
  boolean isHidden();

   /**
   * Retrieve an enumeration of all the known accounts for this service.
   *
   * @return nsISimpleEnumerator of flockIWebServiceAccount objects.
   */
  nsISimpleEnumerator getAccounts();

  /**
   * Log out from all accounts (remove cookies and deauth API if needed)
   */
  void logout();

};


/**
 * This is the account interface associated with flockIWebService.  It is the
 * base web service account interface, and should be implemented by all web
 * service accounts.
 *
 * More documentation here:
 * http://wiki.flock.com/index.php?title=Danphe:AccountsAndServices
 *
 * @see flockIWebService
 */
[scriptable, uuid(362fbfea-b889-442f-8d69-6be0f4c4c31c)]
interface flockIWebServiceAccount : nsISupports {

  /** RDF node id for this account */
  readonly attribute AString urn;

  /**
   * Calling this method will set the 'isPollable' RDF attribute for this
   * account to TRUE, which means that Flock will try to poll the account for
   * content.
   *
   * @param aListener (in) A flockIListener, optional, which may respond to
   *        success or failure conditions.
   *
   * @see flockIListener
   */
  void activate(in flockIListener aListener);

  /**
   * Calling this method will set the 'isPollable' RDF attribute for this
   * account to FALSE, which means that Flock will NOT try to poll the account
   * for content.
   *
   * @param aListener (in) A flockIListener, optional, which may respond to
   *        success or failure conditions.
   *
   * @see flockIListener
   */
  void deactivate(in flockIListener aListener);

  /**
   * Get a handle to the flockIWebService associated with this account.
   */
  flockIWebService getService();

  /**
   * Log in to the account, using stored username and password.
   *
   * @param aListener (in) A flockIListener, optional, which may respond to
   *        success or failure conditions.
   *
   * @see flockIListener
   */
  void login(in flockIListener aListener);

  /**
   * Log out of the account.
   *
   * @param aListener (in) A flockIListener, optional, which may respond to
   *        success or failure conditions.
   *
   * @see flockIListener
   */
  void logout(in flockIListener aListener);

  /**
   * Accounts are usually initially created in a "transient" state, meaning
   * that they will only last for the duration of the current browser session.
   * This method makes the account non-transient.
   */
  void keep();

  /**
   * Return true if the account is logged in, false otherwise.
   */
  boolean isAuthenticated();

  /**
   * Gets value of account parameter aParamName customParams list
   * ** see  flockIUtils.addCustomParamsToAccount() **
   * @param aParamName (in) parameter to return
   * candidates of parameters :
   * accountId
   * avatar
   * name
   * statusMessage
   * lastUpdateDate
   * nextRefresh
   * accountMessages 
   * authToken
   * @return nsIVariant value that corresponds to aParam for this account
   */
  nsIVariant getParam(in AString aParamName);

  /**
   * Gets value of a default param of account
   * @param aParamName (in) parameter to return
   * candidates of parameters :
   * accountId
   * avatar
   * name
   * statusMessage
   * lastUpdateDate
   * nextRefresh
   * accountMessages 
   * authToken
   * @return void
   */
   void setParam(in AString aParamName,
                 in nsIVariant aValue);

 /**
  * Gets value of account parameter aParamName customParams list
  * ** see  flockIUtils.addCustomParamsToAccount() **
  * @param aParamName (in) parameter to return
  * @return nsIVariant value that corresponds to aParam for this account
  */
  nsIVariant getCustomParam(in AString aParamName);

  /**
   * Gets all custom account parameters
   * ** see  flockIUtils.addCustomParamsToAccount() **
   * @return nsIPropertyBag of all custom params for this account
   */
  nsIPropertyBag getAllCustomParams();

  /**
   * sets value of account parameter aParamName
   * ** see  flockIUtils.addCustomParamsToAccount() **
   * @param aParamName (in) parameter to return
   * @param aValue (in) new value for parameter
   * @return void
   */
  void setCustomParam(in AString aParamName,
                      in nsIVariant aValue);
};
