/*
 * 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 "nsIDOMHTMLFormElement.idl"
#include "nsIPassword.idl"

#include "flockIWebService.idl"


/**
 * Represents a web service that can be managed by the Web Service Manager.
 *
 * Implementing this interface is insufficient for a web service component to
 * be managed by the Web Service Manager.  The component must also explicitly
 * register itself by calling the registerWebService() method of
 * flockIWebServiceManager.
 *
 * More documentation here:
 * http://wiki.flock.com/index.php?title=Danphe:AccountsAndServices
 *
 * @see flockIWebServiceManager
 */
[scriptable, uuid(b2c2757f-f41e-4c71-bf20-b5da1ee3f5b4)]
interface flockIManageableWebService : flockIWebService {
  /** Comma-separated list of web domains owned by the service */
  readonly attribute AString domains;
  /** URL to redirect the user when we want him to log in */
  readonly attribute AString loginURL;

  /**
   * Determine whether the specified document represents a successful login.
   * No distinction is made between the first login landing page and subsequent
   * pages.  In other words, this function should return TRUE as long as the
   * aDocument represents a page in a logged-in state.
   *
   * This function may assume that .ownsDocument() has already been called on
   * the document in question, and has returned TRUE.
   *
   * @return TRUE iff aDocument reveals that the use is logged in to this
   *         web service.
   * @see ownsDocument
   */
  boolean docRepresentsSuccessfulLogin(in nsIDOMHTMLDocument aDocument);

  /**
   * Retrieve the account ID represented by aDocument.  The account in question
   * may or may not be known by Flock.
   *
   * This function may assume that .docRepresentsSuccessfulLogin() has already
   * been called on the same document, and has returned TRUE.
   *
   * @param aDocument (in) an HTML document object
   * @return The account ID as a string, or else null if an account ID can not
   *         be determined.
   * @see docRepresentsSuccessfulLogin
   */
  AString getAccountIDFromDocument(in nsIDOMHTMLDocument aDocument);

  /**
   * Retrieve the login credentials from an HTML form.
   *
   * This function may assume that .ownsLoginForm() has already been called on
   * the form in question, and has returned TRUE.
   *
   * @param aForm (in) the HTML form to check
   * @return An nsIPassword object with the login/password, or else null if the
   *         login/password can not be determined.
   * @see ownsLoginForm
   */
  nsIPassword getCredentialsFromForm(in nsIDOMHTMLFormElement aForm);

  /**
   * Indicates whether the specified document is one that the service 'owns' or
   * cares about.
   *
   * Note that if the service has provided a value for the 'domains' attribute,
   * then this function will only get called for documents whose URL falls
   * within the specified domains... so doing a domain check again in this
   * function would be redundant.
   *
   * @param aDocument (in) an HTML document to check
   * @return TRUE iff the service cares about this document/URL, else FALSE
   * @see domains
   */
  boolean ownsDocument(in nsIDOMHTMLDocument aDocument);

  /**
   * Indicated whether the specified HTML form is one that the service 'owns'
   * or cares about.  This could be because it's a login, sign-up or
   * change-password form.
   *
   * NOTE: it is incorrect to assume that ownsDocument has already passed for
   * the form's document, or that the form's domain has been checked.  This
   * function must do all necessary checks to ensure that the form in question
   * is actually a login form for this service.
   *
   * @param aForm (in) an HTML form to check
   * @return TRUE iff this is a login form for this service, else FALSE
   */
  boolean ownsLoginForm(in nsIDOMHTMLFormElement aForm);

  /**
   * Gives the service an opportunity to update the status of it's account(s).
   * In particular, this should detect whether account(s) are logged in or
   * logged out, and update the isAuthenticated RDF property of those accounts
   * as appropriate.
   *
   * This function may assume that .ownsDocument() has already been called for
   * the document in question, and has returned TRUE.
   *
   * @param aDocument (in) an HTML document to check
   * @param aAcctURN (in) the RDF node ID of an account which has already been
   *        detected as logged in on this page.  If not provided, then no
   *        account was detected as being logged in for aDocument.
   * @see ownsDocument
   */
  void updateAccountStatusFromDocument(in nsIDOMHTMLDocument aDocument,
                                       in AString aAcctURN);

  /**
   * Returns a string derived from the current state of session cookies for
   * service.  This is used to determine whether the user is still logged in
   * to the same account, in cases where we can't tell that simply by looking
   * at the document.
   */
  AString getSessionValue();
};
