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

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

/**
 * Interface for the flockAccountUtils service.  Various helpful functions for
 * doing Accounts and Services stuff.
 *
 * More documentation here:
 * http://developer.flock.com/wiki/Accounts_Management
 */
[scriptable, uuid(5e88735f-8956-46b2-a600-1bc910da7896)]
interface flockIAccountUtils : nsISupports {
  /**
   * 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 isAuthenticated==FALSE.
   *
   * @param aAccount (in) The XPCOM account.
   *
   * @return The previous value of isAuthenticated for the specified account.
   */
  boolean ensureOnlyAuthenticatedAccount(in flockIWebServiceAccount aAccount);

  /**
   * 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 aAccount (in) The XPCOM account.
   *
   * @return TRUE if there are no authenticated accounts or we successfully log
   *         out of an authenticated account; else FALSE.
   */
  boolean
  ensureNoAuthenticatedAccountsBeforeLogin(in flockIWebServiceAccount aAccount);

  /**
   * Searches Flock's data store for an account for the specified service with
   * the specified account ID.
   *
   * @param aService (in) The XPCOM 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.
   */
  flockIWebServiceAccount getAccountById(in flockIWebService aService,
                                         in AString aAccountId);

  /**
   * Searches for a matching login stored in the Login Manager.
   *
   * @return The XPCOM account, if a match is found.
   */
  flockIWebServiceAccount getAccountByLogin(in flockIWebService aService,
                                            in AString aLogin);

  /**
   * Retrieves a flockIWebService service given its short name.
   *
   * @param aShortname (in) the short name for the service.
   * @return flockIWebService.
   *
   * @see flockIWebService
   */
  flockIWebService getServiceFromShortname(in AString aShortname);

  /**
   * 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.
   *
   * @see flockIWebService
   */
  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.
   *
   * @see flockIWebServiceAccount
   */
  nsISimpleEnumerator getAccountsByInterface(in AString aServiceInterface);

  /**
   * Checks if any accounts are configured.
   *
   * return TRUE if any configured accounts found; else FALSE.
   */
  boolean doAccountsExist();

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

  /**
   * 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);

  /**
   * 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.
   *
   * @see flockIWebServiceAccount#logout
   * @see flockIWebServiceAccount#remove
   */
  void removeAllAccounts();

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

  /**
   * 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 Login Manager.
   */
  nsILoginInfo getPassword(in AString aKey);

  /**
   * Retrieves the first password entry found in Login Manager for the given
   * host.
   */
  nsILoginInfo 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 flockILoginInfo object, or null if the entry was not found
   *
   * @see clearTempPassword
   * @see setTempPassword
   */
  flockILoginInfo 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 nsILoginInfo object with the username and password, for
   *         convenience
   */
  nsILoginInfo makeTempPasswordPermanent(in AString aKey);

  /**
   * Sets the isAuthenticated RDF property to FALSE for all accounts associated
   * with the specified service.
   */
  void markAllAccountsAsLoggedOut(in flockIWebService aService);

  /**
   * Simple wrapper for the Login Manager addLogin() method.
   *
   * @see nsILoginManager#addLogin
   */
  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 Login 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 Login Manager for the specified host.
   */
  void removeAllPasswordsForHost(in AString aHost);

  /**
   * Delete the password entry in Login Manager for the specified hash key.
   *
   * @param aKey (in) The unique hash key of the password entry to retrieve
   * @return nsILoginInfo object, or null if the entry was not found
   */
  nsILoginInfo removePassword(in AString aHost);

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

  /**
   * Looks for the named Web Detective rules file under the 'detect' folder in
   * the user's profile dir, and loads it into Web Detective. If does not exist
   * it first copies it from the "aSubDir" folder in the app's profile dir.
   *
   * [ Note that this will only work with XML rules files shipped with the
   * application.]
   *
   * More usage documentation here:
   * http://developer.flock.com/wiki/Web_Detective
   *
   * This can be used by app-managed Extensions. Other extensions will not be
   * able to call this function, and should instead manually load the XML rules
   * files into Web Detective using {flockIWebDetective}.loadFromChrome()
   *
   * @param aDetectionFileName (in) Name (not path) of the XML file to load.
   * @param aSubDir (in) Sub directory in app's profile dir.(e.g "res/detect")
   * @return A handle to the Web Detective service.
   */
  flockIWebDetective loadWebDetectiveFile(in AString aDetectionFileName,
                                          in AString aSubDir);
  /**
   * Takes an enumeration of cookie descriptors and removes any stored cookies
   * matching those descriptors.
   *
   * @param aCookies (in) nsISimpleEnumerator of nsICookie objects
   *
   * @see nsICookie
   */
  void removeCookies(in nsISimpleEnumerator aCookies);

  /**
   * Determines whether the People Sidebar is open, and more specifically
   * whether it is open to a particular service tab.
   *
   * @return null if the sidebar is closed or 
   *         the contractId of the opened tab (or "all" if the All tab is open).
   */
  AString peopleSidebarOpen();

  /**
   * @return TRUE if the primary account is logged in and has new messages
   */
  boolean primaryAccountIsHot();
};
