Add MSVC project and solution files
[moonshot-firefox.git] / nsIHttpMoonshot.idl
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3  * The contents of this file are subject to the Mozilla Public
4  * License Version 1.1 (the "License"); you may not use this file
5  * except in compliance with the License. You may obtain a copy of
6  * the License at http://www.mozilla.org/MPL/
7  * 
8  * Software distributed under the License is distributed on an "AS
9  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
10  * implied. See the License for the specific language governing
11  * rights and limitations under the License.
12  * 
13  * The Original Code is Mozilla.
14  * 
15  * The Initial Developer of the Original Code is Netscape
16  * Communications.  Portions created by Netscape Communications are
17  * Copyright (C) 2001 by Netscape Communications.  All
18  * Rights Reserved.
19  * 
20  * Contributor(s): 
21  *   Darin Fisher <darin@netscape.com> (original author)
22  */
23
24 #include "nsISupports.idl"
25
26 #include "nsIHttpChannel.idl"
27
28 /**
29  * nsIHttpAuthenticator
30  *
31  * Interface designed to allow for pluggable HTTP authentication modules.
32  * Implementations are registered under the ContractID:
33  *
34  *   "@mozilla.org/network/http-authenticator;1?scheme=<auth-scheme>"  
35  *
36  * where <auth-scheme> is the lower-cased value of the authentication scheme
37  * found in the server challenge per the rules of RFC 2617.
38  */
39 [scriptable, uuid(0f331436-8bc8-4c68-a124-d0253a19d06f)]
40 interface nsIHttpAuthenticator: nsISupports
41 {
42     /**
43      * Upon receipt of a server challenge, this function is called to determine
44      * whether or not the current user identity has been rejected.  If true,
45      * then the user will be prompted by the channel to enter (or revise) their
46      * identity.  Following this, generateCredentials will be called.
47      *
48      * If the IDENTITY_IGNORED auth flag is set, then the aInvalidateIdentity
49      * return value will be ignored, and user prompting will be suppressed.
50      *
51      * @param aChannel
52      *        the http channel that received the challenge.
53      * @param aChallenge
54      *        the challenge from the WWW-Authenticate/Proxy-Authenticate
55      *        server response header.  (possibly from the auth cache.)
56      * @param aProxyAuth
57      *        flag indicating whether or not aChallenge is from a proxy.
58      * @param aSessionState
59      *        see description below for generateCredentials.
60      * @param aContinuationState
61      *        see description below for generateCredentials.
62      * @param aInvalidateIdentity
63      *        return value indicating whether or not to prompt the user for a
64      *        revised identity.
65      */
66     void challengeReceived(in nsIHttpChannel aChannel,
67                            in string         aChallenge,
68                            in boolean        aProxyAuth,
69                            inout nsISupports aSessionState,
70                            inout nsISupports aContinuationState,
71                            out boolean       aInvalidatesIdentity);
72
73     /**
74      * Called to generate the authentication credentials for a particular
75      * server/proxy challenge.  This is the value that will be sent back
76      * to the server via an Authorization/Proxy-Authorization header.
77      *
78      * This function may be called using a cached challenge provided the
79      * authenticator sets the REUSABLE_CHALLENGE flag.
80      *
81      * @param aChannel
82      *        the http channel requesting credentials
83      * @param aChallenge
84      *        the challenge from the WWW-Authenticate/Proxy-Authenticate
85      *        server response header.  (possibly from the auth cache.)
86      * @param aProxyAuth
87      *        flag indicating whether or not aChallenge is from a proxy.
88      * @param aDomain
89      *        string containing the domain name (if appropriate)
90      * @param aUser
91      *        string containing the user name
92      * @param aPassword
93      *        string containing the password
94      * @param aSessionState
95      *        state stored along side the user's identity in the auth cache
96      *        for the lifetime of the browser session.  if a new auth cache
97      *        entry is created for this challenge, then this parameter will
98      *        be null.  on return, the result will be stored in the new auth
99      *        cache entry.  this parameter is non-null when an auth cache entry
100      *        is being reused.
101      * @param aContinuationState
102      *        state held by the channel between consecutive calls to
103      *        generateCredentials, assuming multiple calls are required
104      *        to authenticate.  this state is held for at most the lifetime of
105      *        the channel.
106      */
107     string generateCredentials(in nsIHttpChannel aChannel,
108                                in string         aChallenge,
109                                in boolean        aProxyAuth,
110                                in wstring        aDomain,
111                                in wstring        aUser,
112                                in wstring        aPassword,
113                                inout nsISupports aSessionState,
114                                inout nsISupports aContinuationState);
115
116     /**
117      * Flags defining various properties of the authenticator.
118      */
119     readonly attribute unsigned long authFlags;
120
121     /**
122      * A request based authentication scheme only authenticates an individual
123      * request (or a set of requests under the same authentication domain as
124      * defined by RFC 2617).  BASIC and DIGEST are request based authentication
125      * schemes.
126      */
127     const unsigned long REQUEST_BASED = (1<<0);
128
129     /**
130      * A connection based authentication scheme authenticates an individual
131      * connection.  Multiple requests may be issued over the connection without
132      * repeating the authentication steps.  Connection based authentication
133      * schemes can associate state with the connection being authenticated via
134      * the aContinuationState parameter (see generateCredentials).
135      */
136     const unsigned long CONNECTION_BASED = (1<<1);
137
138     /**
139      * The credentials returned from generateCredentials may be reused with any
140      * other URLs within "the protection space" as defined by RFC 2617 section
141      * 1.2.  If this flag is not set, then generateCredentials must be called
142      * for each request within the protection space.  REUSABLE_CREDENTIALS
143      * implies REUSABLE_CHALLENGE.
144      */
145     const unsigned long REUSABLE_CREDENTIALS = (1<<2);
146
147     /**
148      * A challenge may be reused to later generate credentials in anticipation
149      * of a duplicate server challenge for URLs within "the protection space"
150      * as defined by RFC 2617 section 1.2.
151      */
152     const unsigned long REUSABLE_CHALLENGE = (1<<3);
153
154     /**
155      * This flag indicates that the identity of the user is not required by
156      * this authentication scheme.
157      */
158     const unsigned long IDENTITY_IGNORED = (1<<10);
159
160     /**
161      * This flag indicates that the identity of the user includes a domain
162      * attribute that the user must supply.
163      */
164     const unsigned long IDENTITY_INCLUDES_DOMAIN = (1<<11);
165 };