epoc32/include/siphttpdigest.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     1 /*
     2 * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
     3 * All rights reserved.
     4 * This component and the accompanying materials are made available
     5 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
     6 * which accompanies this distribution, and is available
     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
     8 *
     9 * Initial Contributors:
    10 * Nokia Corporation - initial contribution.
    11 *
    12 * Contributors:
    13 *
    14 * Description:
    15 * Name        : siphttpdigest.h
    16 * Part of     : SIP Client
    17 * Interface   : SDK API, SIP Client API
    18 * Version     : 2.0
    19 *
    20 */
    21 
    22 
    23 
    24 #ifndef CSIPHTTPDIGEST_H
    25 #define CSIPHTTPDIGEST_H
    26 
    27 // INCLUDES 
    28 #include <e32base.h>
    29 #include "_sipcodecdefs.h"
    30 
    31 // FORWARD DECLARATIONS
    32 class CSIP;
    33 class MSIPHttpDigestChallengeObserver;
    34 class MSIPHttpDigestChallengeObserver2;
    35 class CSIPClientTransaction;
    36 class CSIPRefresh;
    37 
    38 // CLASS DECLARATION
    39 
    40 /**
    41 * @publishedAll
    42 * @released
    43 *
    44 * Class for managing SIP HTTP Digest security settings.
    45 * Class provides functions for setting/removing
    46 * HTTP Digest security mechanism related parameters.
    47 * If the user does not use the class for the providing credentials for the
    48 * received challenges, an error will be returned to the original request in
    49 * case it was challenged.
    50 * 
    51 * Note that the user will be asked to provide credentials one realm
    52 * at the time.
    53 *
    54 *  @lib sipclient.lib
    55 */
    56 class CSIPHttpDigest : public CBase
    57 	{
    58 	public: // Constructors and destructor
    59 	
    60 		/**
    61 		* Two-phased constructor.
    62 		* @param aSIP a handle to SIP server
    63 		* @param aObserver an observer for the received challenges
    64 		* @return New object, ownership is transferred.
    65 		*/
    66 		IMPORT_C static CSIPHttpDigest*
    67 			NewL(CSIP& aSIP,
    68 				 MSIPHttpDigestChallengeObserver& aObserver);
    69 				 
    70 		/**
    71 		* Two-phased constructor.
    72 		* @param aSIP a handle to SIP server
    73 		* @param aObserver an observer for the received challenges
    74 		* @return New object, ownership is transferred.
    75 		*/
    76 		IMPORT_C static CSIPHttpDigest*
    77 			NewLC(CSIP& aSIP,
    78 				  MSIPHttpDigestChallengeObserver& aObserver);
    79 
    80 		/**
    81 		* Two-phased constructor.
    82 		* @param aSIP a handle to SIP server
    83 		* @param aObserver2 an observer for the received challenges
    84 		* @return New object, ownership is transferred.
    85 		*/
    86 		IMPORT_C static CSIPHttpDigest*
    87 			NewL(CSIP& aSIP,
    88 				 MSIPHttpDigestChallengeObserver2& aObserver2);
    89 				 
    90 		/**
    91 		* Two-phased constructor.
    92 		* @param aSIP a handle to SIP server
    93 		* @param aObserver2 an observer for the received challenges
    94 		* @return New object, ownership is transferred.
    95 		*/
    96 		IMPORT_C static CSIPHttpDigest*
    97 			NewLC(CSIP& aSIP,
    98 				  MSIPHttpDigestChallengeObserver2& aObserver2);
    99 				  
   100 		IMPORT_C ~CSIPHttpDigest();
   101 
   102 	public: // New functions
   103 
   104         /**
   105 		* Sets credentials for the realm of the outbound proxy.
   106 		* Must be used in case the realm is the realm of the outbound proxy and
   107 		* the request for credentials was received from callback
   108 		* MSIPHttpDigestChallengeObserver::ChallengeReceived.		
   109 		* The user can set credentials only upon request from the
   110 		* SIP implementation.
   111 		* @pre aOutboundProxy, aRealm, aUsername and aPasswd must not be empty
   112 		*	   descriptors.
   113 		* @param aOutboundProxy an outbound proxy (FQDN or IP address)
   114 		* @param aRealm servers's realm
   115 		* @param aUsername user's name
   116 		* @param aPasswd user's password for the given server's realm
   117 		* @leave KErrNoMemory if out of memory
   118 		* @leave KErrArgument if some of the parameters is an empty descriptor
   119 		* @leave KErrSIPResourceNotAvailable if a required object has been
   120 		*		 deleted
   121 		*/
   122 		IMPORT_C void SetCredentialsL(const TDesC8& aOutboundProxy,
   123 			                          const TDesC8& aRealm,
   124 			                          const TDesC8& aUsername,
   125 			                          const TDesC8& aPasswd);
   126         /**
   127 		* Sets parameters for the realm.
   128 		* Should be used in case the realm is not a realm of an outbound proxy 
   129 		* and the request for credentials was received from callback
   130 		* MSIPHttpDigestChallengeObserver::ChallengeReceived.		
   131 		* The user can set credentials only upon request from the
   132 		* SIP implementation.
   133 		* @pre aRealm, aUsername and aPasswd must not be empty descriptors.
   134 		* @param aRealm servers's realm
   135 		* @param aUsername user's name
   136 		* @param aPasswd user's password for the given server's realm
   137 		* @leave KErrNoMemory if out of memory
   138 		* @leave KErrArgument if some of the parameters is an empty descriptor
   139 		* @leave KErrSIPResourceNotAvailable if a required object has been
   140 		*		 deleted
   141 		*/
   142 		IMPORT_C void SetCredentialsL(const TDesC8& aRealm,
   143 			                          const TDesC8& aUsername,
   144 			                          const TDesC8& aPasswd);
   145 
   146         /**
   147 		* Sets credentials for the realm for the specific transaction.
   148 		* Must be used when the request for credentials was received 
   149 		* from callback MSIPHttpDigestChallengeObserver2::ChallengeReceived with 
   150 		* CSIPClientTransaction as the parameter.
   151 		* @pre aRealm, aUsername and aPasswd must not be empty descriptors.
   152 		* @param aTransaction the transaction that was passed as a parameter
   153 		*        to MSIPHttpDigestChallengeObserver2::ChallengeReceived
   154 		* @param aOutboundProxy an outbound proxy (FQDN or IP address) if
   155 		*        the challenge received had Proxy-Authenticate-header(s).
   156 		*        Otherwise KNullDesC8 should passed.
   157 		* @param aRealm servers's realm
   158 		* @param aUsername user's name
   159 		* @param aPasswd user's password for the given server's realm
   160 		* @leave KErrNoMemory if out of memory
   161 		* @leave KErrArgument if some of the parameters is an empty descriptor
   162 		* @leave KErrSIPResourceNotAvailable if a required object has been
   163 		*		 deleted
   164 		*/
   165 		IMPORT_C void SetCredentialsL(const CSIPClientTransaction& aTransaction,
   166 		                              const TDesC8& aOutboundProxy,
   167 			                          const TDesC8& aRealm,
   168 			                          const TDesC8& aUsername,
   169 			                          const TDesC8& aPasswd);
   170 
   171         /**
   172 		* Sets credentials for the realm for the specific refresh.
   173 		* Must be used when the request for credentials was received 
   174 		* from callback MSIPHttpDigestChallengeObserver2::ChallengeReceived with 
   175 		* CSIPRefresh as the parameter.
   176 		* @pre aRealm, aUsername and aPasswd must not be empty descriptors.
   177 		* @param aRefresh the refresh that was passed as a parameter
   178 		*        to MSIPHttpDigestChallengeObserver2::ChallengeReceived
   179 		* @param aOutboundProxy an outbound proxy (FQDN or IP address) if
   180 		*        the challenge received had Proxy-Authenticate-header(s).
   181 		*        Otherwise KNullDesC8 should passed.
   182 		* @param aRealm servers's realm
   183 		* @param aUsername user's name
   184 		* @param aPasswd user's password for the given server's realm
   185 		* @leave KErrNoMemory if out of memory
   186 		* @leave KErrArgument if some of the parameters is an empty descriptor
   187 		* @leave KErrSIPResourceNotAvailable if a required object has been
   188 		*		 deleted
   189 		*/
   190 		IMPORT_C void SetCredentialsL(const CSIPRefresh& aRefresh,
   191 		                              const TDesC8& aOutboundProxy,
   192 			                          const TDesC8& aRealm,
   193 			                          const TDesC8& aUsername,
   194 			                          const TDesC8& aPasswd);
   195 			            
   196         /**
   197 		* Removes all set credentials for the realm.
   198 		* Must not be used if the user implements 
   199 		* MSIPHttpDigestChallengeObserver2.
   200 		* @pre aRealm must not be an empty descriptor
   201 		* @param aRealm servers's realm
   202 		* @return KErrNone if no error
   203 		*		  KErrArgument if aRealm is an empty descriptor
   204 		*		  KErrNoMemory if out of memory
   205 		*		  KErrNotFound if the given realm was not found
   206         */
   207 		IMPORT_C TInt RemoveCredentials(const TDesC8& aRealm);
   208 		
   209         /**
   210 		* Removes all set credentials by the user.
   211 		* Must not be used if the user implements 
   212 		* MSIPHttpDigestChallengeObserver2.		
   213 		* @return KErrNone if succesful; KErrNoMemory if out of memory 
   214         */
   215 		IMPORT_C TInt RemoveCredentials();
   216 					                                                        
   217 		/**
   218 		* Sets the observer	to listen for the possible received challenges. 
   219 		* Replaces the existing MSIPHttpDigestChallengeObserver or
   220 		* MSIPHttpDigestChallengeObserver2.
   221 		* @param aObserver an observer for the received challenges. 
   222 		*/
   223 		IMPORT_C void SetObserver(MSIPHttpDigestChallengeObserver& aObserver);
   224 		
   225 		/**
   226 		* Sets the observer	to listen for the possible received challenges. 
   227 		* Replaces the existing MSIPHttpDigestChallengeObserver or
   228 		* MSIPHttpDigestChallengeObserver2.
   229 		* @param aObserver an observer for the received challenges. 
   230 		*/
   231 		IMPORT_C void SetObserver(MSIPHttpDigestChallengeObserver2& aObserver);		
   232 		
   233 		/**
   234 		* Ignores the challenge for the realm. As a result the error will be
   235 		* generated to the original SIP request. 
   236 		* @pre aRealm must not be an empty descriptor
   237 		* @param aRealm a realm for which the challenge was ignored
   238 		* @return KErrNone if no error
   239 		*		  KErrNotFound if the given realm was not found
   240 		*		  KErrArgument if aRealm is an empty descriptor
   241 		*/
   242 		IMPORT_C TInt IgnoreChallenge(const TDesC8& aRealm);
   243 
   244 		/**
   245 		* Ignores the challenge for the realm for the specific transaction.
   246 		* As a result KErrForbidden will be generated 
   247 		* to the original SIP request.
   248 		* @pre aRealm must not be an empty descriptor
   249 		* @param aTransaction the transaction that was passed as a parameter
   250 		*        to MSIPHttpDigestChallengeObserver2::ChallengeReceived		
   251 		* @param aRealm a realm for which the challenge was ignored
   252 		* @return KErrNone if no error
   253 		*		  KErrNotFound if the given realm was not found
   254 		*		  KErrArgument if aRealm is an empty descriptor
   255 		*/
   256 		IMPORT_C TInt IgnoreChallenge(const CSIPClientTransaction& aTransaction,
   257 		                              const TDesC8& aRealm);
   258 
   259 		/**
   260 		* Ignores the challenge for the realm for the specific refresh.
   261 		* As a result the error will be generated 
   262 		* to the original SIP request.
   263 		* @pre aRealm must not be an empty descriptor
   264 		* @param aRefresh the refresh that was passed as a parameter
   265 		*        to MSIPHttpDigestChallengeObserver2::ChallengeReceived		
   266 		* @param aRealm a realm for which the challenge was ignored
   267 		* @return KErrNone if no error
   268 		*		  KErrNotFound if the given realm was not found
   269 		*		  KErrArgument if aRealm is an empty descriptor
   270 		*/
   271 		IMPORT_C TInt IgnoreChallenge(const CSIPRefresh& aRefresh,
   272 		                              const TDesC8& aRealm);
   273 
   274 	public: // New functions, for internal use
   275 
   276 		void CSIPDeleted();
   277 
   278 	private: // Constructors
   279 
   280         CSIPHttpDigest(CSIP& aSIP);
   281 		CSIPHttpDigest(const CSIPHttpDigest& aHttpDigest);
   282 		CSIPHttpDigest& operator=(const CSIPHttpDigest& aHttpDigest);
   283 
   284 		void ConstructL(MSIPHttpDigestChallengeObserver& aObserver);
   285 		
   286 		void ConstructL(MSIPHttpDigestChallengeObserver2& aObserver2);
   287        
   288     private: // New functions
   289     
   290 		TInt RemoveCredentialParams(const TDesC8& aRealm) const;
   291 
   292 		void SetCredentialParamsL(TUint32 aRequestId,
   293 		                          TUint32 aRefreshId,
   294 		                          const TDesC8& aOutboundProxy,
   295 		                          const TDesC8& aRealm,
   296 				                  const TDesC8& aUsername,
   297 				                  const TDesC8& aPasswd) const;		
   298 		
   299 		TInt IgnoreChallenge(TUint32 aRequestId,
   300 		                     TUint32 aRefreshId,
   301 		                     const TDesC8& aRealm);       
   302           
   303     private: // Data
   304 
   305         CSIP* iSIP;
   306 
   307 	private: // For testing purposes
   308 
   309 	    UNIT_TEST(CSIP_Test)
   310 	};
   311 
   312 #endif // CSIPHTTPDIGEST_H