/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 *
 * 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.
 *
 * The Original Code is Mozilla code.
 *
 * The Initial Developer of the Original Code is Zero-Knowledge Systems,
 * Inc.  Portions created by Zero-Knowledge are Copyright (C) 2000
 * Zero-Knowledge Systems, Inc.  All Rights Reserved.
 *
 * Contributor(s): 
 */

#include "nsISupports.idl"
#include "nsIAuthPrompt.idl"
#include "nsIURL.idl"

[scriptable,uuid(adf74d2a-1dd1-11b2-b129-f3154be37959)]
interface nsIAuthenticator : nsISupports
{
    /**
     * @param uri The URI for which authentication is required.
     * @param uri The protocol, for selecting authentication-style.  Variant
     *            protocols, such as http/https and imap/imaps will likely all
     *            use the primary protocol name ("http", "imap"), to reduce
     *            
     * @param challenge The complete value of the WWW-Authenticate header from
     *                  the response.
     * @param username The username provided in the prehost portion of the URI,
     *                 if any.
     * @param password The password provided in the prehost portion of the URI,
     *                 if any.
     * @param prompter  The standard prompter for interacting with the user.
     * @param 
     * @return The complete authentication value to return.  For Basic HTTP
     *         auth, as an example, the returned string would be
     *         "Basic BASE64(<user>:<pass>)".  The format is dependent on the
     *         provided protocol parameter.
     */
    string authenticate(in nsIURI uri, in string protocol, in string challenge,
                        in wstring username, in wstring password,
                        in nsIAuthPrompt prompter);

  /**
   * No interaction with the user required.  This indicates that the 
   * authenticate method can be called with a null prompter argument, though
   * calling code should strive to provide it if at all possible.  (While
   * interaction with the user may not be _required_, it might still be
   * desire
   */
  const PRUint32 INTERACTION_NONE = 0;

  /**
   * Standard username and optional password required, and the caller should
   * prompt for it.
   */
  const PRUint32 INTERACTION_STANDARD = 1;

  /**
   * Custom interaction required: Mozilla must provide a non-null prompter
   * argument when calling authenticate.
   */
  const PRUint32 INTERACTION_CUSTOM = 2;

  /**
   * What kind of interaction with the user does this authentication method
   * require?
   */
  readonly attribute PRUint32 interactionType;
};
