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

#include "flockIBookmarkWebService.idl"
#include "flockIManageableWebService.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 flockIWebService
 */
[scriptable, uuid(249fbe6e-3e63-4339-bea2-67a72149d89f)]
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 flockIManageableWebService aService,
                                 in nsIDOMDocument aDocument );
  /**
   * This will be called to notify that the WSM has created 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 WSM has created removed an account
   * @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 flockIManageableWebService interface.  It
 * must also call registerWebService().
 *
 * More documentation here:
 * http://wiki.flock.com/index.php?title=Danphe:AccountsAndServices
 *
 * @see flockIManageableWebService
 */
[scriptable, uuid(9D7E9CFA-6144-490A-BD86-9178E8F025C6)]
interface flockIWebServiceManager : nsISupports {
  /**
   * Starts up all web service componentents in the "wsm-startup" category.
   */
  void instantiateAll();

  /**
   * Registers a flockIManageableWebService to be managed.
   *
   * PRECONDITION:
   *  - The service MUST have its .urn property set before calling this.
   *
   * @param aService (in) The service to be managed.
   */
  void registerWebService(in flockIManageableWebService aService);

  /**
   * Un-registers a service, meaning that the Web Service Manager will STOP
   * managing that service.
   *
   * @param aService (in) The service to stop managing.
   */
  void unregisterWebService(in flockIManageableWebService aService);
  
  /**
   * Adds an account listener to listen for onAccountCreated, onAccountRemoved,
   * and onAccountAuthChange events on an account.
   *
   * @param aListener (in) The listener callback object.
   */
  void addListener(in flockIWebServiceAccountListener aListener);
  
  /**
   * Removes the account listener for listening for onAccountCreated, onAccountRemoved,
   * and onAccountAuthChange events on an account.
   *
   * @param aListener (in) The listener callback object to be removed.
   */
  void removeListener(in flockIWebServiceAccountListener aListener);

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