nsIHttpChannelAuthProvider.idl (3025B)
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* vim: set sw=2 ts=8 et tw=80 : */ 3 /* This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this 5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 7 #include "nsICancelable.idl" 8 9 interface nsIHttpChannel; 10 interface nsIHttpAuthenticableChannel; 11 12 /** 13 * nsIHttpChannelAuthProvider 14 * 15 * This interface is intended for providing authentication for http-style 16 * channels, like nsIHttpChannel and nsIWebSocket, which implement the 17 * nsIHttpAuthenticableChannel interface. 18 * 19 * When requesting pages AddAuthorizationHeaders MUST be called 20 * in order to get the http cached headers credentials. When the request is 21 * unsuccessful because of receiving either a 401 or 407 http response code 22 * ProcessAuthentication MUST be called and the page MUST be requested again 23 * with the new credentials that the user has provided. After a successful 24 * request disconnect MUST be called. 25 */ 26 27 [uuid(788f331b-2e1f-436c-b405-4f88a31a105b)] 28 interface nsIHttpChannelAuthProvider : nsICancelable 29 { 30 /** 31 * Initializes the http authentication support for the channel. 32 * Implementations must hold a weak reference of the channel. 33 */ 34 [must_use] void init(in nsIHttpAuthenticableChannel channel); 35 36 /** 37 * Upon receipt of a server challenge, this function is called to determine 38 * the credentials to send. 39 * 40 * @param httpStatus 41 * the http status received. 42 * @param sslConnectFailed 43 * if the last ssl tunnel connection attempt was or not successful. 44 * @param callback 45 * the callback to be called when it returns NS_ERROR_IN_PROGRESS. 46 * The implementation must hold a weak reference. 47 * 48 * @returns NS_OK if the credentials were got and set successfully. 49 * NS_ERROR_IN_PROGRESS if the credentials are going to be asked to 50 * the user. The channel reference must be 51 * alive until the feedback from 52 * nsIHttpAuthenticableChannel's methods or 53 * until disconnect be called. 54 */ 55 [must_use] void processAuthentication(in unsigned long httpStatus, 56 in boolean sslConnectFailed); 57 58 /** 59 * Add credentials from the http auth cache. 60 * 61 * @param dontUseCachedWWWCreds 62 * When true, the method will not add any Authorization headers from 63 * the auth cache. 64 */ 65 [must_use] void addAuthorizationHeaders(in boolean dontUseCachedWWWCreds); 66 67 /** 68 * Cancel pending user auth prompts and release the callback and channel 69 * weak references. 70 */ 71 [must_use] void disconnect(in nsresult status); 72 73 /** 74 * Clear the proxy ident to not consider it invalid on re-athentication. 75 * Called when the channel finds out its transaction has been internally 76 * restarted. 77 */ 78 void clearProxyIdent(); 79 };