/*
* Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
* Name          : CSIPSecChallenge.h
* Part of       : SIPSec/DigestPlugin
* Version       : SIP/6.0
*
*/




/**
 @internalComponent
*/

#ifndef __CSIPSEC_CHALLENGE_H__
#define __CSIPSEC_CHALLENGE_H__

// INCLUDES
#include "CSIPSecDigest.h"
#include "sipsecrequestdata.h"
#include "CSIPSecUserRecord.h"
#include "SipStackServerDefs.h"

// FORWARD DECLARATIONS
class CSIPAuthenticateHeaderBase;
class MSIPSecAlgorithm;
class TSIPSecDigestCtxSetup;
class MSIPSecUser;


// CLASS DECLARATION

/**
 * @brief Class representing challenge received in 401/407 response
 * 
 * @class CSIPSecChallenge CSIPSecChallenge.h "CSIPSecChallenge.h"
 *
 * This class is a base class for challenge, whose inherited classes implement
 * functionality of algotithm defined in challenge.
 * Class provides functions for populating common values to credentials
 * (created from this challenge)
 * This class also provides functions for resolving type of challenge, realm
 * and content (SIP authenticate header)
 *
 * Inherited class must implement methods:
 * - Algorithm, which provides digest calculation interface
 * - VerifyType, that checks the challenge type is correct
 */
 class CSIPSecChallenge : public CBase 
    {
public: // Constructors and destructor

    /**
    * Destructor
    */
    virtual ~CSIPSecChallenge();

public: // New pure virtual functions

    /**
    * Returns algorithm
    * @return Algorithm
    */
    virtual MSIPSecAlgorithm& Algorithm() = 0;

	/**
    * Checks that the type is correct.
    * @param aType Record type
    * @leave KErrPermissionDenied if aType is not correct.
    */
	virtual void VerifyTypeL( CSIPSecUserRecord::TType aType ) const = 0;

	/**
    * Creates a new CSIPSecUserRecord.
    * @param aRealm Realm
    * @param aUser SIPSec user who is processing the SIP response that leads to
    *		 	   creating a new user record.
    * @param aRegistrationId Registration id
    * @param aTransactionId Transaction id of the SIP response
    * @param aResponseCode Response code of SIP response
    */
	virtual CSIPSecUserRecord*
		CreateUserRecordL( const TDesC8& aRealm,
						   const MSIPSecUser& aUser,
						   TRegistrationId aRegistrationId,
			      		   TTransactionId aTransactionId,
			      		   TUint aResponseCode ) const = 0;

public: // New functions

	/**
    * Populates credentials
    * @param aContext Digest context    
    */
    void PopulateCredentialsL( TSIPSecDigestCtxSetup& aContext ) const;

    /**
    * Returns the type of challenge
    * @return Type of challenge
    */
    CSIPSecDigest::TChallengeType Type() const;

    /**
    * Returns the realm of challenge
    * @return Realm
    */
    const TDesC8& Realm() const;

    /**
    * Returns a modifiable content of the challenge (SIP authenticate header).
    * @return Content of challenge
    */
    CSIPAuthenticateHeaderBase& Content();

    /**
    * Returns a non-modifiable content of the challenge (SIP authenticate
    * header).
    * @return Content of challenge
    */
    const CSIPAuthenticateHeaderBase& Content() const;		

	/**
    * Check if the qop exists
    * @return ETrue if qop exists, EFalse otherwise
    */
	TBool HasQop() const;

	/**
    * Gets the qop as descriptor.
    * @return qop as descriptor, or empty descriptor if qop doesn't exist
    */
	const TDesC8& QopDescriptor() const;

	/**
    * Gets the owner of this challenge
    * @return Owner of the challenge. Ownership is not transferred.
    */
    const MSIPSecUser* Owner() const;

	/**
    * Sets the owner of this challenge
    * @return Owner. Ownership is not transferred.
    */
    void SetOwner( const MSIPSecUser* aOwner );

protected: //methods

    /**
    * Constructor
    * @param aType the type of challenge
    * @param aQop qop of the challenge
    */
    CSIPSecChallenge( CSIPSecDigest::TChallengeType aType,
    				  CSIPSecRequestData::TQop aQop );
    
    /**
	* Second phase constructor
	* @param aAuthenticateHeader authenticate header 
	*/
	void ConstructL( CSIPAuthenticateHeaderBase& aAuthenticateHeader );
     
    /**
    * Gets the qop value.
    * @return qop value
    */
	CSIPSecRequestData::TQop Qop() const;	

private:

	/**
    * Copies the parameter from challenge to authorization header.
    * @param aContext Digest context
    * @param aParam String pool constant of the parameter name    
    */
	void FillCredentialParamL( TSIPSecDigestCtxSetup& aContext,
							   TInt aParam ) const;

private: // Data

	// Owned
    CSIPAuthenticateHeaderBase* iAuthenticateHeader;

    CSIPSecDigest::TChallengeType iType;

	// Qop to be used for the challenge.	
	CSIPSecRequestData::TQop iQop;

    // Owner of this challenge. Not owned.
	const MSIPSecUser* iOwner;

	// For testing purposes
#ifdef CPPUNIT_TEST
    friend class CSIPSecChallengeTest;
#endif
    };

#endif //end of __CSIPSEC_CHALLENGE_H__

// End of File