/*

    File:       ChallengeHandler.h

    Contains:   Base class for handling various authentication challenges.

    Written by: DTS

    Copyright:  Copyright (c) 2011 Apple Inc. All Rights Reserved.

    Disclaimer: IMPORTANT: This Apple software is supplied to you by Apple Inc.

                ("Apple") in consideration of your agreement to the following

                terms, and your use, installation, modification or

                redistribution of this Apple software constitutes acceptance of

                these terms.  If you do not agree with these terms, please do

                not use, install, modify or redistribute this Apple software.

                In consideration of your agreement to abide by the following

                terms, and subject to these terms, Apple grants you a personal,

                non-exclusive license, under Apple's copyrights in this

                original Apple software (the "Apple Software"), to use,

                reproduce, modify and redistribute the Apple Software, with or

                without modifications, in source and/or binary forms; provided

                that if you redistribute the Apple Software in its entirety and

                without modifications, you must retain this notice and the

                following text and disclaimers in all such redistributions of

                the Apple Software. Neither the name, trademarks, service marks

                or logos of Apple Inc. may be used to endorse or promote

                products derived from the Apple Software without specific prior

                written permission from Apple.  Except as expressly stated in

                this notice, no other rights or licenses, express or implied,

                are granted by Apple herein, including but not limited to any

                patent rights that may be infringed by your derivative works or

                by other works in which the Apple Software may be incorporated.

                The Apple Software is provided by Apple on an "AS IS" basis. 

                APPLE MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING

                WITHOUT LIMITATION THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,

                MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING

                THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN

                COMBINATION WITH YOUR PRODUCTS.

                IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT,

                INCIDENTAL OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED

                TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

                DATA, OR PROFITS; OR BUSINESS INTERRUPTION) ARISING IN ANY WAY

                OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION

                OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY

                OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY OR

                OTHERWISE, EVEN IF APPLE HAS BEEN ADVISED OF THE POSSIBILITY OF

                SUCH DAMAGE.

*/

// This is an abstract base class that represents a generic mechanism for handling 

// NSURLAuthenticationChallenges.  It does very little work; the bulk of the work 

// is done by the various concrete subclasses (such as AuthenticationChallengeHandler). 

// The only real work done here is to maintain a register of challenge handler 

// classes that stand ready to handle various types of challenges.

// IMPORTANT

// This is /not/ a UIViewController subclass because certain challenges are 

// resolved without a presenting a full view controller (for example, those 

// that can be resolved with a UIAlertView).

#import <UIKit/UIKit.h>

@protocol ChallengeHandlerDelegate;

@interface ChallengeHandler : NSObject

{

    NSURLAuthenticationChallenge *  _challenge;

    UIViewController *              _parentViewController;

    NSURLCredential *               _credential;

    id<ChallengeHandlerDelegate>    _delegate;

    BOOL                            _running;

}

+ (BOOL)supportsProtectionSpace:(NSURLProtectionSpace *)protectionSpace;

    // Returns true if we have a challenge handler that will handle challenges 

    // in the specified protection space.

+ (ChallengeHandler *)handlerForChallenge:(NSURLAuthenticationChallenge *)challenge parentViewController:(UIViewController *)parentViewController;

    // Returns a challenge handler that's prepared to handle the specified challenge 

    // (and that presents any modal view controllers on top of parentViewController). 

    // Alternatively, returns nil if no one is prepared to handle this challenge.

+ (NSURLCredential *)noCredential;

    // A special singleton value used to represent no credential.  When a challenge 

    // is resolved with this value, we call -continueWithoutCredentialForAuthenticationChallenge: 

    // rather than -useCredential:forAuthenticationChallenge:.

@property (nonatomic, retain, readonly)  NSURLAuthenticationChallenge * challenge;

@property (nonatomic, retain, readonly)  UIViewController *             parentViewController;

    // These are the values supplied during construction.

@property (nonatomic, retain, readonly)  NSURLCredential *              credential;

    // This represents the credential being used to resolve the challenge.  If the 

    // challenge UI is still running, this will be nil.  Once the challenge UI 

    // is done (that is, the challenge handler has called the -challengeHandlerDidFinish: 

    // delegate method, or you've called -stop yourself), this will be nil, or 

    // +noCredential, or an actual credential. 

@property (nonatomic, assign, readwrite) id<ChallengeHandlerDelegate>   delegate;

@property (nonatomic, assign, readonly, getter=isRunning)  BOOL         running;

    // This is YES if the challenge UI is currently being displayed.

- (void)start;

    // Starts the challenge UI running.  This transitions isRunning from YES 

    // to NO (although it may transition straight back again, see the next point). 

    // 

    // This may call the -challengeHandlerDidFinish: delegate method immediately.

    // 

    // Do not call this twice on the same challenge.

- (void)stopWithCredential:(NSURLCredential *)credential;

- (void)stop;

    // Stops the challenge handler running and sets the credential to the value 

    // specified.  -stop is equivalent to -stopWithCredential: with a nil credential. 

    // This can be called either by the challenge UI (when the user completes the 

    // UI, just before calling the -challengeHandlerDidFinish: delegate method) or 

    // by the client (when external forces cause the challenge to no longer be 

    // relevant).  It shuts down the UI and transitions isRunning from YES to NO. 

    //

    // It's not legal to call this on a challenge that hasn't been started.

    // It's legal to call this on a challenge that's already been stopped.

- (void)resolve;

    // Called by the client after the challenge has stopped to actually apply the 

    // credential to the NSURLAuthenticationChallenge.

// The following methods are typically used by folks implementating concrete subclasses 

// of ChallengeHandler.

+ (void)registerHandlers;

    // Called by the handler registry within ChallengeHandler to request that the 

    // concrete subclass register itself.

- (id)initWithChallenge:(NSURLAuthenticationChallenge *)challenge parentViewController:(UIViewController *)parentViewController;

    // You can call this directly if you like, but mostly this is called by 

    // +handlerForChallenge:parentViewController: to initialise an instance of 

    // a concrete challenge handler class.

    //

    // A concrete implementation can return nil to opt out of this specific challenge 

    // (in which case +handlerForChallenge:parentViewController: will try to find 

    // another appropriate challenge handler class).

- (void)didStart;

    // In general a subclass will override this to create its UI.

- (void)willFinish;

    // In general a subclass will override this to shut down its UI.

- (void)didFinish;

    // This is typically not used by a subclasses.

+ (void)registerHandlerClass:(Class)handlerClass forAuthenticationMethod:(NSString *)authenticationMethod;

    // Subclasses call this to register themselves for consideration by 

    // +handlerForChallenge:parentViewController:.

    //

    // It is acceptable for register yourself twice for the same authentication method.  

    // The second registration is treated as a no-op.

+ (void)deregisterHandlerClass:(Class)handlerClass forAuthenticationMethod:(NSString *)authenticationMethod;

    // Subclasses call this to deregister themselves.  This is useful for 

    // the ServerTrustChallengeHandler, which deregisters itself if the 

    // user has specified that we use the default trust evaluation process.

    //

    // It is acceptable to deregister yourself even if you've not registered 

    // yourself.

@end

@protocol ChallengeHandlerDelegate <NSObject>

@required

- (void)challengeHandlerDidFinish:(ChallengeHandler *)handler;

    // Called by the challenge handler when the user completes the challenge 

    // UI.  The result of the challenge will be available via the credential

    // property.  Call -resolve to apply this to the NSURLAuthenticationChallenge.

    //

    // isRunning will be NO by the time this is called.

@end