/*
 * 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 "nsIDOMHTMLDocument.idl"
#include "nsIDOMHTMLElement.idl"
#include "nsIDOMHTMLFormElement.idl"
#include "nsIPassword.idl"
#include "nsIPropertyBag.idl"
#include "nsISimpleEnumerator.idl"
#include "nsISupports.idl"
#include "nsITransferable.idl"

#include "flockIBookmarkWebService.idl"
#include "flockIWebDetective.idl"
#include "flockIWebService.idl"


/**
 * Interface for tracking origins of passwords.  Right now we only track
 * signup vs. not.
 */
[scriptable, uuid(25e096fa-dd6f-4405-b983-4d064192f04c)]
interface flockIPassword : nsIPassword {
  attribute AString formType;
};


/**
 * Interface for the flockAccountUtils service.  Various helpful functions for
 * doing Accounts and Services stuff.
 *
 * More documentation here:
 * http://wiki.flock.com/index.php?title=Danphe:AccountsAndServices
 */
[scriptable, uuid(2549A53E-258B-45D7-B52F-1E121AB8309C)]
interface flockIAccountUtils : nsISupports {
  /**
   * Determines whether an activated account exists for the specified service.
   */
  boolean activatedAccountExists(in AString aServiceURN);

  /**
   * Clears the temporary password with the specified key from memory.  Note
   * that these temporary passwords are stored in memory only and as such will
   * not persist beyond the current browser session as it is.  This method
   * provides an extra peace-of-mind security measure of explicitly purging it
   * when it is no longer needed.
   *
   * @param aKey (in) The unique hash key of the temp password entry to delete
   * @see getTempPassword
   * @see setTempPassword
   */
  void clearTempPassword(in AString aKey);

  /**
   * Makes sure that the specified account has isAuthenticated==TRUE, and that
   * all other accounts with the same service have isAuthenitcated==FALSE.
   *
   * @param aAccountURN (in) The RDF node id of an account.
   *
   * @return The previous value of isAuthenticated for the specified account.
   */
  boolean ensureOnlyAuthenticatedAccount(in AString aAccountURN);

  /**
   * Call this before logging in to the specified account to ensure that there
   * are no other accounts logged in to this service. If an authenticated
   * account is found, the user will be prompted to confirm a forced logout of
   * that account.
   *
   * @param aAccountURN (in) The RDF node id of an account.
   *
   * @return true if there are no authenticated accounts or we successfully log
   *         out of an authenticated account.
   */
  boolean ensureNoAuthenticatedAccountsBeforeLogin(in AString aAccountURN);

  /**
   * Searches Flock's data store for an account for the specified service with
   * the specified account ID.
   *
   * @param aServiceURN (in) The RDF node id for the service
   * @param aAccountID (in) The unique account identifier used by the web
   *        service
   * @return The RDF node id of the account, if a match is found.
   */
  AString getAccountURNById(in AString aServiceURN, in AString aAccountID);

  /**
   * Searches for a matching login stored in the password manager.
   *
   * @return The RDF node id of the account, if a match is found.
   */
  AString getAccountURNByLogin(in AString aServiceURN, in AString aLogin);

  /**
   * Retrieves all the accounts that Flock knows of for a given service, as an
   * enumerator of flockIWebServiceAccounts.
   *
   * @param aServiceContractID (in) the contract ID of the service for which we
   *        want to enumerate accounts
   * @return nsISimpleEnumerator of flockIWebServiceAccount objects.
   */
  nsISimpleEnumerator getAccountsForService(in AString aServiceContractID);

  /**
   * Retrieves all the flockIWebService services that implement the interface
   * specified by aWebServiceInterface, as an enumerator of flockIWebServices.
   *
   * @param aWebServiceInterface (in) the web service interface name for which
   *                                  we want to enumerate services
   * @return nsISimpleEnumerator of flockIWebService objects.
   */
  nsISimpleEnumerator getWebServicesByInterface(in AString aWebServiceInterface);

  /**
   * Retrieves all the accounts that implement the interface specified by
   * aInterface, as an enumerator of flockIWebServiceAccounts.
   *
   * @param aServiceInterface (in) the web service interface name for which we
   *        want to enumerate accounts
   * @return nsISimpleEnumerator of flockIWebServiceAccount objects.
   */
  nsISimpleEnumerator getAccountsByInterface(in AString aServiceInterface);

  /**
   * Checks if any accounts are configured.
   *
   * return true if any configured accounts found, false otherwise.
   */
  boolean doAccountsExist();

  boolean isTransient(in AString aURN);

  nsIDOMHTMLElement getElementByAttribute( in nsIDOMHTMLElement aAncestorElement,
                                           in AString aAttributeName,
                                           in AString aAttributeValue );


  /**
   * Retrieves the contract ID of the service associated with the specified
   * account URN.
   *
   * @param aAccountURN (in) The RDF node id of an account.
   * @return The service contract ID, as a string.
   */
  AString getServiceIDForAccountURN(in AString aAccountURN);

  /**
   * Create an account on the given service. Should only be called by the
   * service itself. For some services, the accountId and the username
   * may be the same.
   *
   * @param aService (in) Service responsible for the new account.
   * @param aAccountId (in) AccountId on the service.
   * @param aUsername (in) Username on the service.
   * @param aUrl (in) The URL of the account; usually corresponds to the
   *        profile page of the user on the service, or a dashboard page.
   *        If null, defaults to the service URL.
   * @param aIsTransient (in) Whether the account should be created transient
   *        or not. At the end of the session, all transient accounts are
   *        deleted.
   * @return RDF id of the newly created account.
   */
  AString createAccount(in flockIWebService aService,
                        in AString aAccountId,
                        in AString aUsername,
                        in AString aUrl,
                        in boolean aIsTransient);

  /**
   * Adds parameters that are custom to account coop object defined by aAccountUrn
   * @param aList (in) list of parameters to add to account
   * @param aAccountUrn (in) id of account
   */
  void addCustomParamsToAccount(in nsIPropertyBag aList,
                                in AString aAccountUrn);

  /**
   * *** DEPRECATED ****
   * Please use flockIWebServiceAccount.getCustomParam() instead
   *
   * Gets value of account parameter aParamName
   * @param aParamName (in) parameter to return
   * @param aAccountUrn (in) id of account
   * @return nsIVariant value that corresponds to aParam
   */
  nsIVariant getAccountCustomParam(in AString aAccountUrn,
                                   in AString aParamName);

  /**
   * *** DEPRECATED ****
   * Please use flockIWebServiceAccount.getAllCustomParams() instead
   *
   * Gets all custom account parameters
   * @param aAccountUrn (in) id of account
   */
  nsIPropertyBag getAllAccountCustomParams(in AString aAccountUrn);

  /**
   * *** DEPRECATED ****
   * Please use flockIWebServiceAccount.setCustomParam() instead
   *
   * sets value of account parameter aParamName
   * @param aParamName (in) parameter to return
   * @param aAccountUrn (in) id of account
   * @param aValue (in) new value for parameter
   */
  void setAccountCustomParamValue(in AString aAccountUrn,
                                  in AString aParamName,
                                  in nsIVariant aValue);

  /**
   * Remove (or "forget") an account and its associated identities.
   *
   * @param aAccountUrn (in) RDF id of the account to forget.
   */
  void removeAccount(in AString aAccountUrn);

  /**
   * Removes all configured accounts from the RDF, after first calling
   * .logout() on each account to be removed.
   *
   * return true if any configured accounts found, false otherwise.
   */
  void removeAllAccounts();

  AString getCookie(in AString aHost, in AString aCookieName);

  /**
   * Iterates through the nsICookieManager#enumerator list of cookies returns
   * the value of the first cookie that matches aHost, aName and aPath.
   */
  AString getCookieValue(in AString aHost, in AString aName, in AString aPath);

  /**
   * Retrieves the password with the specified hash key.  This method looks
   * first in the temporary password hash, and if not found there then it looks
   * in Password Manager.
   */
  nsIPassword getPassword(in AString aKey);

  /**
   * Determine if the password manager has a password stored for *any* host in
   * the specified domain.
   *
   * @param aDomain (in) web domain to check for passwords in.
   * @return nsIPassword object if a password is found, otherwise Null
   */
  nsIPassword getPasswordForAnyHost(in AString aDomain);

  flockIBookmarkWebServiceAccount getActiveBookmarkAccount();

  /**
   * DEPRECATED
   *
   * Use flockIWebService.getAuthenticatedAccount
   */
  AString getFirstAuthenticatedAccountForService(in AString aServiceContractID);

  /**
   * Retrieves the first password entry found in Password Manager for the given
   * host.
   */
  nsIPassword getFirstPasswordForHost(in AString aHost);

  /**
   * Retrieve the temporary password entry stored (in-memory) with the
   * specified hash key.
   *
   * @param aKey (in) The unique hash key of the temp password entry to
   *        retrieve
   * @return nsIPassword object, or null if the entry was not found
   * @see clearTempPassword
   * @see setTempPassword
   */
  nsIPassword getTempPassword(in AString aKey);

  /**
   * Removes a temporily in-memory password and puts in into Password
   * Manager for real.
   *
   * @param aKey (in) The unique hash key of the temp password make permanent
   * @return an nsIPassword object with the username and password, for
   *         convenience
   */
  nsIPassword makeTempPasswordPermanent(in AString aKey);

  /**
   * Sets the isLoggedIn RDF property to FALSE for
   * the specified account.
   */
  void markAccountAsLoggedOut(in AString aAccountURN);

  /**
   * Sets the isLoggedIn RDF property to FALSE for all accounts associated with
   * the specified service.
   */
  void markAllAccountsAsLoggedOut(in AString aServiceContractID);

  /**
   * Simple wrapper for the Password Manager addUser() method.
   *
   * @see nsIPasswordManager
   */
  void setPassword(in AString aHost, in AString aUser, in AString aPassword);

  /**
   * Set a temporary password to be kept in memory for this browser session, or
   * until specifically purged using the clearTempPassword() method.  Note that
   * these passwords are specifically NOT stored using Password Manager because
   * that is not guaranteed to clear them after this browser session.
   *
   * @param aKey (in) The unique hash key of the temp password entry to store
   * @param aUser (in) The username used for login
   * @param aPassword (in) The password string
   * @param aFormType (in) The type of form where the password was captured from
   * @see clearTempPassword
   * @see getTempPassword
   */
  void setTempPassword(in AString aKey, in AString aUser, in AString aPassword,
                       in AString aFormType);

  /**
   * Deletes all password entries in Password Manager for the specified host.
   */
  void removeAllPasswordsForHost(in AString aHost);

  /**
   * Creates a Coop notification in the specified notification stream.
   *
   * @param aStreamUrn (in) RDF id of the notification stream to use
   * @param aNotificationUrn (in) RDF id of the notification to be raised --
   *        necessary to avoid duplicates
   * @param aNotificationProps (in) nsIPropertyBag object containing all the
   *        properties to be set on the notification object
   */
  void raiseNotification( in AString aStreamUrn,
                          in AString aNotificationUrn,
                          in nsIPropertyBag aNotificationProps );

  /**
   * Tries ripping through an HTML Form DOM to find a username and password.
   *
   * @param aForm (in) HTML Form element to look under
   * @return nsIPassword object if a likely un/pw pair is found, otherwise null
   */
  nsIPassword extractPasswordFromHTMLForm(in nsIDOMHTMLFormElement aForm);

  /**
   * Attach specific meta-data to a document for later use.  Fields are
   * identified by a category and name, and have a simple string value.
   *
   * @see getDocumentDecoration
   */
  void decorateDocument( in nsIDOMHTMLDocument aDocument,
                         in AString aCategory,
                         in AString aName,
                         in AString aValue );

  /**
   * Retreive specific meta-data that was previously placed on a document
   * using decorateDocument().
   *
   * @see decorateDocument
   */
  AString getDocumentDecoration( in nsIDOMHTMLDocument aDocument,
                                 in AString aCategory,
                                 in AString aName );

  /**
   * Looks for the named Web Detective rules file under the 'detect' folder in
   * the user's profile dir, and loads it into Web Detective.
   *
   * [ Note that this will only work with XML rules files shipped with the
   * application.  Extensions will not be able to call this function, and
   * should instead manually load the XML rules files into Web Detective using
   * {flockIWebDetective}.loadDetectFile() ]
   *
   * @param aDetectionFileName (in) Name (not path) of the XML file to load.
   * @return A handle to the Web Detective service.
   *
   * @see flockIWebDetective
   *
   * More usage documentation here:
   * http://wiki.flock.com/index.php?title=Danphe:WebDetective
   */
  flockIWebDetective useWebDetective(in AString aDetectionFileName);

  /**
   * Takes an enumeration of cookie descriptors and removes any stored cookies
   * matching those descriptors.
   *
   * @param aCookies (in) nsISimpleEnumerator of nsICookie objects
   */
  void removeCookies(in nsISimpleEnumerator aCookies);

  /**
   * Determines whether or not the people sidebar is open
   */
  boolean isPeopleSidebarOpen();
};
