netwerk/base/public/nsIAuthInformation.idl

   1 /* ***** BEGIN LICENSE BLOCK *****
   2  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3  *
   4  * The contents of this file are subject to the Mozilla Public License Version
   5  * 1.1 (the "License"); you may not use this file except in compliance with
   6  * the License. You may obtain a copy of the License at
   7  * http://www.mozilla.org/MPL/
   8  *
   9  * Software distributed under the License is distributed on an "AS IS" basis,
  10  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11  * for the specific language governing rights and limitations under the
  12  * License.
  13  *
  14  * The Original Code is mozilla.org Necko code.
  15  *
  16  * The Initial Developer of the Original Code is
  17  * Christian Biesinger <cbiesinger@web.de>.
  18  * Portions created by the Initial Developer are Copyright (C) 2006
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *  Google Inc.
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsISupports.idl"
  39
  40 /**
  41  * A object that hold authentication information. The caller of
  42  * nsIAuthPrompt2::promptUsernameAndPassword or
  43  * nsIAuthPrompt2::promptPasswordAsync provides an object implementing this
  44  * interface; the prompt implementation can then read the values here to prefill
  45  * the dialog. After the user entered the authentication information, it should
  46  * set the attributes of this object to indicate to the caller what was entered
  47  * by the user.
  48  */
  49 [scriptable, uuid(0d73639c-2a92-4518-9f92-28f71fea5f20)]
  50 interface nsIAuthInformation : nsISupports
  51 {
  52   /** @name Flags */
  53   /* @{ */
  54   /**
  55    * This dialog belongs to a network host.
  56    */
  57   const PRUint32 AUTH_HOST = 1;
  58
  59   /**
  60    * This dialog belongs to a proxy.
  61    */
  62   const PRUint32 AUTH_PROXY = 2;
  63
  64   /**
  65    * This dialog needs domain information. The user interface should show a
  66    * domain field, prefilled with the domain attribute's value.
  67    */
  68   const PRUint32 NEED_DOMAIN = 4;
  69
  70   /**
  71    * This dialog only asks for password information. Authentication prompts
  72    * SHOULD NOT show a username field. Attempts to change the username field
  73    * will have no effect. nsIAuthPrompt2 implementations should, however, show
  74    * its initial value to the user in some form. For example, a paragraph in
  75    * the dialog might say "Please enter your password for user jsmith at
  76    * server intranet".
  77    *
  78    * This flag is mutually exclusive with #NEED_DOMAIN.
  79    */
  80   const PRUint32 ONLY_PASSWORD = 8;
  81   /* @} */
  82
  83   /**
  84    * Flags describing this dialog. A bitwise OR of the flag values
  85    * above.
  86    *
  87    * It is possible that neither #AUTH_HOST nor #AUTH_PROXY are set.
  88    *
  89    * Auth prompts should ignore flags they don't understand; especially, they
  90    * should not throw an exception because of an unsupported flag.
  91    */
  92   readonly attribute unsigned long flags;
  93
  94   /**
  95    * The server-supplied realm of the authentication as defined in RFC 2617.
  96    * Can be the empty string if the protocol does not support realms.
  97    * Otherwise, this is a human-readable string like "Secret files".
  98    */
  99   readonly attribute AString realm;
 100
 101   /**
 102    * The authentication scheme used for this request, if applicable. If the
 103    * protocol for this authentication does not support schemes, this will be
 104    * the empty string. Otherwise, this will be a string such as "basic" or
 105    * "digest". This string will always be in lowercase.
 106    */
 107   readonly attribute AUTF8String authenticationScheme;
 108
 109   /**
 110    * The initial value should be used to prefill the dialog or be shown
 111    * in some other way to the user.
 112    * On return, this parameter should contain the username entered by
 113    * the user.
 114    * This field can only be changed if the #ONLY_PASSWORD flag is not set.
 115    */
 116   attribute AString username;
 117
 118   /**
 119    * The initial value should be used to prefill the dialog or be shown
 120    * in some other way to the user.
 121    * The password should not be shown in clear.
 122    * On return, this parameter should contain the password entered by
 123    * the user.
 124    */
 125   attribute AString password;
 126
 127   /**
 128    * The initial value should be used to prefill the dialog or be shown
 129    * in some other way to the user.
 130    * On return, this parameter should contain the domain entered by
 131    * the user.
 132    * This attribute is only used if flags include #NEED_DOMAIN.
 133    */
 134   attribute AString domain;
 135 };
 136