/*

* Copyright (c) 2006-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        : siphttpdigest.h

* Part of     : SIP Client

* Interface   : SDK API, SIP Client API

* Version     : 2.0

*

*/

#ifndef CSIPHTTPDIGEST_H

#define CSIPHTTPDIGEST_H

// INCLUDES 

#include <e32base.h>

// FORWARD DECLARATIONS

class CSIP;

class MSIPHttpDigestChallengeObserver;

class MSIPHttpDigestChallengeObserver2;

class CSIPClientTransaction;

class CSIPRefresh;

// CLASS DECLARATION

/**

* @publishedAll

* @released

*

* Class for managing SIP HTTP Digest security settings.

* Class provides functions for setting/removing

* HTTP Digest security mechanism related parameters.

* If the user does not use the class for the providing credentials for the

* received challenges, an error will be returned to the original request in

* case it was challenged.

* 

* Note that the user will be asked to provide credentials one realm

* at the time.

*

*  @lib sipclient.lib

*/

class CSIPHttpDigest : public CBase

	{

	public: // Constructors and destructor

		/**

		* Two-phased constructor.

		* @param aSIP a handle to SIP server

		* @param aObserver an observer for the received challenges

		* @return New object, ownership is transferred.

		*/

		IMPORT_C static CSIPHttpDigest*

			NewL(CSIP& aSIP,

				 MSIPHttpDigestChallengeObserver& aObserver);

		/**

		* Two-phased constructor.

		* @param aSIP a handle to SIP server

		* @param aObserver an observer for the received challenges

		* @return New object, ownership is transferred.

		*/

		IMPORT_C static CSIPHttpDigest*

			NewLC(CSIP& aSIP,

				  MSIPHttpDigestChallengeObserver& aObserver);

		/**

		* Two-phased constructor.

		* @param aSIP a handle to SIP server

		* @param aObserver2 an observer for the received challenges

		* @return New object, ownership is transferred.

		*/

		IMPORT_C static CSIPHttpDigest*

			NewL(CSIP& aSIP,

				 MSIPHttpDigestChallengeObserver2& aObserver2);

		/**

		* Two-phased constructor.

		* @param aSIP a handle to SIP server

		* @param aObserver2 an observer for the received challenges

		* @return New object, ownership is transferred.

		*/

		IMPORT_C static CSIPHttpDigest*

			NewLC(CSIP& aSIP,

				  MSIPHttpDigestChallengeObserver2& aObserver2);

		IMPORT_C ~CSIPHttpDigest();

	public: // New functions

        /**

		* Sets credentials for the realm of the outbound proxy.

		* Must be used in case the realm is the realm of the outbound proxy and

		* the request for credentials was received from callback

		* MSIPHttpDigestChallengeObserver::ChallengeReceived.		

		* The user can set credentials only upon request from the

		* SIP implementation.

		* @pre aOutboundProxy, aRealm, aUsername and aPasswd must not be empty

		*	   descriptors.

		* @param aOutboundProxy an outbound proxy (FQDN or IP address)

		* @param aRealm servers's realm

		* @param aUsername user's name

		* @param aPasswd user's password for the given server's realm

		* @leave KErrNoMemory if out of memory

		* @leave KErrArgument if some of the parameters is an empty descriptor

		* @leave KErrSIPResourceNotAvailable if a required object has been

		*		 deleted

		*/

		IMPORT_C void SetCredentialsL(const TDesC8& aOutboundProxy,

			                          const TDesC8& aRealm,

			                          const TDesC8& aUsername,

			                          const TDesC8& aPasswd);

        /**

		* Sets parameters for the realm.

		* Should be used in case the realm is not a realm of an outbound proxy 

		* and the request for credentials was received from callback

		* MSIPHttpDigestChallengeObserver::ChallengeReceived.		

		* The user can set credentials only upon request from the

		* SIP implementation.

		* @pre aRealm, aUsername and aPasswd must not be empty descriptors.

		* @param aRealm servers's realm

		* @param aUsername user's name

		* @param aPasswd user's password for the given server's realm

		* @leave KErrNoMemory if out of memory

		* @leave KErrArgument if some of the parameters is an empty descriptor

		* @leave KErrSIPResourceNotAvailable if a required object has been

		*		 deleted

		*/

		IMPORT_C void SetCredentialsL(const TDesC8& aRealm,

			                          const TDesC8& aUsername,

			                          const TDesC8& aPasswd);

        /**

		* Sets credentials for the realm for the specific transaction.

		* Must be used when the request for credentials was received 

		* from callback MSIPHttpDigestChallengeObserver2::ChallengeReceived with 

		* CSIPClientTransaction as the parameter.

		* @pre aRealm, aUsername and aPasswd must not be empty descriptors.

		* @param aTransaction the transaction that was passed as a parameter

		*        to MSIPHttpDigestChallengeObserver2::ChallengeReceived

		* @param aOutboundProxy an outbound proxy (FQDN or IP address) if

		*        the challenge received had Proxy-Authenticate-header(s).

		*        Otherwise KNullDesC8 should passed.

		* @param aRealm servers's realm

		* @param aUsername user's name

		* @param aPasswd user's password for the given server's realm

		* @leave KErrNoMemory if out of memory

		* @leave KErrArgument if some of the parameters is an empty descriptor

		* @leave KErrSIPResourceNotAvailable if a required object has been

		*		 deleted

		*/

		IMPORT_C void SetCredentialsL(const CSIPClientTransaction& aTransaction,

		                              const TDesC8& aOutboundProxy,

			                          const TDesC8& aRealm,

			                          const TDesC8& aUsername,

			                          const TDesC8& aPasswd);

        /**

		* Sets credentials for the realm for the specific refresh.

		* Must be used when the request for credentials was received 

		* from callback MSIPHttpDigestChallengeObserver2::ChallengeReceived with 

		* CSIPRefresh as the parameter.

		* @pre aRealm, aUsername and aPasswd must not be empty descriptors.

		* @param aRefresh the refresh that was passed as a parameter

		*        to MSIPHttpDigestChallengeObserver2::ChallengeReceived

		* @param aOutboundProxy an outbound proxy (FQDN or IP address) if

		*        the challenge received had Proxy-Authenticate-header(s).

		*        Otherwise KNullDesC8 should passed.

		* @param aRealm servers's realm

		* @param aUsername user's name

		* @param aPasswd user's password for the given server's realm

		* @leave KErrNoMemory if out of memory

		* @leave KErrArgument if some of the parameters is an empty descriptor

		* @leave KErrSIPResourceNotAvailable if a required object has been

		*		 deleted

		*/

		IMPORT_C void SetCredentialsL(const CSIPRefresh& aRefresh,

		                              const TDesC8& aOutboundProxy,

			                          const TDesC8& aRealm,

			                          const TDesC8& aUsername,

			                          const TDesC8& aPasswd);

        /**

		* Removes all set credentials for the realm.

		* Must not be used if the user implements 

		* MSIPHttpDigestChallengeObserver2.

		* @pre aRealm must not be an empty descriptor

		* @param aRealm servers's realm

		* @return KErrNone if no error

		*		  KErrArgument if aRealm is an empty descriptor

		*		  KErrNoMemory if out of memory

		*		  KErrNotFound if the given realm was not found

        */

		IMPORT_C TInt RemoveCredentials(const TDesC8& aRealm);

        /**

		* Removes all set credentials by the user.

		* Must not be used if the user implements 

		* MSIPHttpDigestChallengeObserver2.		

		* @return KErrNone if succesful; KErrNoMemory if out of memory 

        */

		IMPORT_C TInt RemoveCredentials();

		/**

		* Sets the observer	to listen for the possible received challenges. 

		* Replaces the existing MSIPHttpDigestChallengeObserver or

		* MSIPHttpDigestChallengeObserver2.

		* @param aObserver an observer for the received challenges. 

		*/

		IMPORT_C void SetObserver(MSIPHttpDigestChallengeObserver& aObserver);

		/**

		* Sets the observer	to listen for the possible received challenges. 

		* Replaces the existing MSIPHttpDigestChallengeObserver or

		* MSIPHttpDigestChallengeObserver2.

		* @param aObserver an observer for the received challenges. 

		*/

		IMPORT_C void SetObserver(MSIPHttpDigestChallengeObserver2& aObserver);		

		/**

		* Ignores the challenge for the realm. As a result the error will be

		* generated to the original SIP request. 

		* @pre aRealm must not be an empty descriptor

		* @param aRealm a realm for which the challenge was ignored

		* @return KErrNone if no error

		*		  KErrNotFound if the given realm was not found

		*		  KErrArgument if aRealm is an empty descriptor

		*/

		IMPORT_C TInt IgnoreChallenge(const TDesC8& aRealm);

		/**

		* Ignores the challenge for the realm for the specific transaction.

		* As a result KErrForbidden will be generated 

		* to the original SIP request.

		* @pre aRealm must not be an empty descriptor

		* @param aTransaction the transaction that was passed as a parameter

		*        to MSIPHttpDigestChallengeObserver2::ChallengeReceived		

		* @param aRealm a realm for which the challenge was ignored

		* @return KErrNone if no error

		*		  KErrNotFound if the given realm was not found

		*		  KErrArgument if aRealm is an empty descriptor

		*/

		IMPORT_C TInt IgnoreChallenge(const CSIPClientTransaction& aTransaction,

		                              const TDesC8& aRealm);

		/**

		* Ignores the challenge for the realm for the specific refresh.

		* As a result the error will be generated 

		* to the original SIP request.

		* @pre aRealm must not be an empty descriptor

		* @param aRefresh the refresh that was passed as a parameter

		*        to MSIPHttpDigestChallengeObserver2::ChallengeReceived		

		* @param aRealm a realm for which the challenge was ignored

		* @return KErrNone if no error

		*		  KErrNotFound if the given realm was not found

		*		  KErrArgument if aRealm is an empty descriptor

		*/

		IMPORT_C TInt IgnoreChallenge(const CSIPRefresh& aRefresh,

		                              const TDesC8& aRealm);

	public: // New functions, for internal use

		void CSIPDeleted();

	private: // Constructors

        CSIPHttpDigest(CSIP& aSIP);

		CSIPHttpDigest(const CSIPHttpDigest& aHttpDigest);

		CSIPHttpDigest& operator=(const CSIPHttpDigest& aHttpDigest);

		void ConstructL(MSIPHttpDigestChallengeObserver& aObserver);

		void ConstructL(MSIPHttpDigestChallengeObserver2& aObserver2);

    private: // New functions

		TInt RemoveCredentialParams(const TDesC8& aRealm) const;

		void SetCredentialParamsL(TUint32 aRequestId,

		                          TUint32 aRefreshId,

		                          const TDesC8& aOutboundProxy,

		                          const TDesC8& aRealm,

				                  const TDesC8& aUsername,

				                  const TDesC8& aPasswd) const;		

		TInt IgnoreChallenge(TUint32 aRequestId,

		                     TUint32 aRefreshId,

		                     const TDesC8& aRealm);       

    private: // Data

        CSIP* iSIP;

	private: // For testing purposes

#ifdef CPPUNIT_TEST

	    friend class CSIP_Test;

#endif

	};

#endif // CSIPHTTPDIGEST_H