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

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


/**
 * This is the listener object to signal account events to listening parties.
 * Things we are interested in are : new account creation, account auth
 * change, and account removal. This is useful for UI especially.
 *
 * @see flockILoginWebService
 */
[scriptable, uuid(b338bb3e-482d-49f9-8e56-cbbf5c164ba5)]
interface flockIWebServiceAccountListener : nsISupports {
  /**
   * This will be called to notify that the WSM has created a new account
   *
   * @param aAccount (in) flockIWebServiceAccount, the newly created account
   * @param aDocument (in) nsIDOMDocument, the document that was used to
   *        confirm the account, which will be used to determine which tab to
   *        show the user notification in 
   */
  void onAccountCreated(in flockIWebServiceAccount aAccount,
                        in nsIDOMDocument aDocument);

  /**
   * This will be called to notify that the WSM has found an account,
   * but couldn't create it because the password is missing (bug 6404).
   *
   * @param aService (in) flockIWebService, the service found
   * @param aDocument (in) nsIDOMDocument, the document where the account
   *        was detected, which will be used to determine which tab to
   *        show the user notification in 
   */
  void onAccountPasswordMissing(in flockILoginWebService aService,
                                in nsIDOMDocument aDocument);

  /**
   * This will be called to notify that the WSM has removed an account.
   * NOTE: THIS IS NOT IMPLEMENTED YET
   *
   * @param aAccount (in) flockIWebServiceAccount, the removed account
   */
  void onAccountRemoved(in flockIWebServiceAccount aAccount);  
  
  /**
   * This will be called to notify that the auth state of an account has
   * changed.
   *
   * @param aAccount (in) flockIWebServiceAccount, the account that was logged
   *        in/out
   */
  void onAccountAuthChange(in flockIWebServiceAccount aAccount);
};

 
/**
 * The Web Service Manager is a singleton service for managing web service
 * components.
 *
 * "Management" in this case means providing some common workflow logic for
 * login detection and account creation.  It also means designating certain
 * web service components as special handlers -- for example designating a
 * primary bookmark service account, since only one bookmark account can be
 * used at a time to synchronize a user's bookmarks.
 *
 * In order to be managed by the Web Service Manager, the web service component
 * in question must implement the flockILoginWebService interface.
 *
 * More documentation here:
 * http://developer.flock.com/wiki/Accounts_Management
 *
 * @see flockILoginWebService
 */
[scriptable, uuid(BD22190C-28E9-11DD-880C-856955D89593)]
interface flockIWebServiceManager : nsISupports {
  /**
   * Starts up all web service componentents in the "wsm-startup" category.
   */
  void instantiateAll();

  /**
   * Adds an account to the list of accounts for which notifications
   * are to be suppressed.
   *
   * @param aAccountUrn (in) URN of Account
   */
  void suppressNotiesForAccount(in AString aAccountUrn);

  /**
   * Returns whether notifications may be shown for the given account.
   *
   * @param aAccountUrn (in) URN of Account
   */
  boolean isShowingNotiesForAccount(in AString aAccountUrn);

  /**
   * Adds an account listener to listen for onAccountCreated, onAccountRemoved,
   * and onAccountAuthChange events on an account.
   *
   * @param aWSAccountListener (in) The listener callback object.
   */
  void addListener(in flockIWebServiceAccountListener aWSAccountListener);
  
  /**
   * Removes the account listener for listening for onAccountCreated, onAccountRemoved,
   * and onAccountAuthChange events on an account.
   *
   * @param aWSAccountListener (in) The listener
                                     callback object to be removed.
   */
  void removeListener(in flockIWebServiceAccountListener aWSAccountListener);

  /**
   * Tells WSM to automatically make accounts with the specified service
   * permanent (non-transient), as long as the account is created within a
   * period of one hour from the time this function was called.
   */
  void autoKeepAccountForService(in AString aServiceURN);
};
