/*
 * 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 "flockIAccountUtils.idl"
#include "flockIWebService.idl"

/**
 * An authentication manager is responsible for coordinating the auth states of
 * multiple related accounts according to known sets of rules.
 *
 * @see flockILoginWebService
 * @see flockIWebServiceAccount
 */
[scriptable, uuid(22397448-c6fc-4bc4-8317-76f3fc391234)]
interface flockIAuthenticationManager : nsISupports {
  /**
   * Designates a particular service as belonging to a particular network.  This
   * means that account auth states for aServiceID are related to account auth
   * states for other services sharing the same aNetworkName.
   */
  void joinNetwork(in AString aServiceID, in AString aNetworkName);

  /**
   * Checks to see if we already have a known password for a given account ID
   * within a given network.
   *
   * @param aServiceID (in) Contract ID of the service that has been logged out,
   *        from which the network is derived.
   * @param aAccountId (in) ID of the account, which will be common across all
   *        services in the same network.
   * @return null if no matching password was found
   */
  flockILoginInfo findPasswordFromRelatedAccount(in AString aServiceID,
                                                 in AString aAccountId);

  /**
   * Tells the authentication manager that a particular account is either
   * logged in or logged out.  The authentication manager is then responsible
   * for determining whether any other configured accounts need to have their
   * auth states updated as a result.
   */
  void reportAccountAuthState(in flockIWebServiceAccount aAccount,
                              in boolean aIsLoggedIn);

  /**
   * Tells the authentication manager that a complete authentication has been
   * detected, meaning that ALL accounts with the same ID in that network are
   * logged in.
   */
  void reportCompleteLoginToNetwork(in flockIWebServiceAccount aAccount);

  /**
   * Tells the authentication manager that a complete de-authentication has been
   * detected.  The authentication manager is then responsible for ensuring that
   * all related accounts are logged out.
   *
   * @param aServiceID (in) Contract ID of the service that has been logged out,
   *        from which the network is derived.
   */
  void reportCompleteLogoutFromNetwork(in AString aServiceID);
};
