1 /*

     2 * Copyright (c) 2002 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 "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Declaration of classes CCookie

    15 *               

    16 *

    17 */

    18 

    19 

    20 #ifndef __CCOOKIE_H__

    21 #define __CCOOKIE_H__

    22 

    23 // INCLUDE FILES

    24 	// System includes

    25 #include <e32std.h>

    26 #include <stringpool.h>

    27 #include <http/thttphdrval.h>

    28 

    29 // FORWARD DECLARATIONS

    30 

    31 class RHTTPHeaders;

    32 class TUriC8;

    33 

    34 // CONSTANTS

    35 

    36 // Attribute prefix : we have to pack cookies when either passing them over

    37 // client-server boundaries or writing them into a file. When this happens we

    38 // put each attribute of a cookie in the destination buffer as follows :

    39 // prefix + attribute value + IsDefaulted,

    40 // where prefix is a number that holds the length of the attribute to be

    41 // stored. This prefix is a TInt.

    42 const TInt KCookieAttributePrefixLength = sizeof( TInt );

    43 const TInt KCookieAttributeDefaultedLength = sizeof( TInt );

    44 const TInt KCookieAttributeFoundLength = sizeof( TInt );

    45 

    46 

    47 // This is the maximum number of attributes that may be defined in a cookie.

    48 // TBD : should not we treat EExpires and EMaxAge attributes as one variable?

    49 const TInt KCookieMaxAttributeCount = 13;

    50 

    51 // CLASS DECLARATION

    52 

    53 /** Class to store the data that makes up a cookie

    54 */

    55 class CCookie : public CBase

    56 	{

    57 	public :

    58 		/** Enumeration of all the elements of data that make up a cookie

    59 		*/

    60 		enum TCookieAttributeName

    61 			{

    62 			EName,			// Name of the cookie - mandatory

    63 			EValue,			// Value associated with the name - mandatory

    64 			EComment,		// Comment which can be displayed to the user

    65 			ECommentURI,	// A URI which can be visited for more information

    66 			EDiscard,		// Flag indicating that the cookie should be discarded

    67 			EDomain,		// Domain which this cookie applies to

    68 			EMaxAge,		// Age after which this cookie should be deleted

    69 			EPath,			// Path which this cookie applies to

    70 			EPort,			// Port numbers that this cookie applies to

    71 			ESecure,		// Flag indicating this cookie should only be used

    72 							// for secure transactions

    73 			EVersion,		// Version of style of cookie - mandatory

    74 			EExpires,		// Time after which this cookie should be deleted -

    75 							// Netscape cookies only

    76             EDate,          // Date when the response header containing the 

    77                             // cookie was generated. It is important to know it 

    78                             // for correct age calculation.

    79             //EAge,           // The age of the cookie as estimated by the cache

    80 			};

    81 

    82 	public :	// exported methods

    83 		/**

    84 		* Constructor.

    85 		* @param aRequestHeaders A collection of header fields associated

    86 		* with the current HTTP message,

    87 		* @param aPartIndex The index of the part in the header,

    88 		* @param aFieldName The HTTP header name,

    89 		* @param aStringPool The current string pool,

    90 		* @param aUri HTTP request's URI.

    91 		*/

    92 		IMPORT_C static CCookie* NewL( RHTTPHeaders aRequestHeaders,

    93 									 TInt aPartIndex,

    94 									 RStringF aFieldName,

    95 									 RStringPool aStringPool,

    96 									 const TUriC8& aUri );

    97 	 	/**

    98 		* Returns a descriptor which is equivalent to the input descriptor,

    99 		* but without the surrounding quotation marks. This method always

   100 		* returns the appropriate string even if there are no quotation marks,

   101 		* or at least one of them is missing.

   102 		* This is required because cookie attributes may be surrounded

   103 		* by double quotes.

   104 		* @param aDes The descriptor to be cleaned.

   105 		* @return Descriptor which points to the part of aDes with no quotes

   106 		*/

   107 		static TPtrC8 RemoveQuotes( const TDesC8& aDes );			 

   108 		/**

   109 		* Constructor.

   110 		* @param aStringPool The current string pool.

   111 		*/

   112 		IMPORT_C static CCookie* NewL( RStringPool aStringPool );

   113 

   114 

   115 		/**

   116 		* Standard destructor.

   117 		*/

   118 		IMPORT_C virtual ~CCookie();

   119 

   120 

   121 		/**

   122 		* This method writes the cookie (i.e. its attributes) into the

   123 		* specified part of the HTTP header. The method may leave if writing

   124 		* is not successful (e.g. when RHTTPHeaders::SetParamL leaves) or if

   125 		* the cookie is not properly initialized.

   126 		* @param aRequestHeaders The current HTTP header collection to which we

   127 		* add this cookie,

   128 		* @param aPartIndex The part of the header.

   129 		*/

   130 		IMPORT_C void AddToRequestL( RHTTPHeaders aRequestHeaders,

   131 									TInt aPartIndex ) const;

   132 		

   133 

   134 		/** Attribute retrieves the value of an attribute

   135 		* @param	aAttributeName	Identifies the attribute 

   136 		* @param	aAttributeVal	The value being retrieved

   137 		* @return	An error code. KErrNotFound will indicate that the cookie

   138 		* doesn't contain the specified attribute.

   139 		*/

   140 		IMPORT_C TInt Attribute( TCookieAttributeName aAttributeName,

   141 								THTTPHdrVal& aAttributeVal ) const;

   142 

   143 

   144 		/** SetAttribute sets an attribute on the cookie. 

   145 		* Adding an attribute where one exists will replace the existing one

   146 		* @param aAttributeName identifies the attribute 

   147 		* @param aAttributeVal the value being set

   148 		* @return An error code

   149 		*/

   150 		IMPORT_C TInt SetAttribute( TCookieAttributeName aAttributeName,

   151 									const THTTPHdrVal& aAttributeVal );

   152 		

   153 

   154 	public :	// public inline methods

   155 		/**

   156 		* Did this cookie come from a SetCookie2 header?

   157 		* @return Flag indicating if this cookie was received in SetCookie2

   158 		* header (rather than a SetCookie header).

   159 		*/

   160 		inline TBool FromCookie2() const;

   161 

   162 

   163 		/**

   164 		* Did this cookie come from a Netscape-version header?

   165 		* @return Flag indicating if this cookie was received 

   166         * in a Netscape-version header

   167 		*/

   168 		inline TBool FromNetscapeVersion() const;

   169 

   170 

   171 		/**

   172 		* Use this method to specify whether this cookie came from a SetCookie2

   173 		* header.

   174 		* @param aFromCookie2 ETrue, if the cookie came from a SetCookie2

   175 		* header, EFalse otherwise.

   176 		*/

   177 		inline void SetCookie2( TBool aFromCookie2 );

   178 

   179 

   180 		/**

   181 		* Use this method to specify whether this cookie is a Netscape style

   182 		* one or an RFC compliant.

   183 		* @param aFromNetscape ETrue, if the cookie is a Netscape style one, 

   184 		* EFalse otherwise.

   185 		*/

   186         inline void SetFromNetscape( TBool aFromNetscape );

   187 

   188 

   189 		/**

   190 		* Returns the number of bytes this cookie would require if it was

   191 		* stored in a flat buffer and one attribute followed the other.

   192 		* Note : the attributes are stored in a way that we first write out

   193 		* the size (TInt) of the attribute in question and then the attribute

   194 		* value. E.g. assuming a NAME attribute with the value of SESSIONID, we

   195 		* write out 9 as the length of NAME (again, stored as TInt) and then

   196 		* write out the value of NAME (i.e. SESSIONID).

   197 		* @param aSuppressDefaulted If ETrue, the method does not add the

   198 		* size of defaulted attributes to the overall size of the cookie.

   199 		* @return The size of the cookie.

   200 		*/

   201 		inline TInt Size( TBool aSuppressDefaulted ) const;

   202 

   203 

   204 	public :	// public methods

   205 		/** Attribute retrieves the value of an attribute

   206 		* @param	aAttributeName	Identifies the attribute 

   207 		* @param	aAttributeVal	The value being retrieved

   208 		* @param	aDefaulted	A TBool indicating whether the current 

   209 		*	attribute's value is defaulted or specified.

   210 		* @return	An error code. KErrNotFound will indicate that the cookie

   211 		* doesn't contain the specified attribute.

   212 		*/

   213 		TInt Attribute( TCookieAttributeName aAttributeName,

   214 						THTTPHdrVal& aAttributeVal,

   215 						TBool& aDefaulted ) const;

   216 

   217 

   218 		/** SetAttribute sets an attribute on the cookie. 

   219 		* Adding an attribute where one exists will replace the existing one

   220 		* @param aAttributeName identifies the attribute 

   221 		* @param aAttributeVal the value being set

   222 		* @param aDefaulted a TBool indicating whether it is a defaulted 

   223 		* or a supplied value

   224 		* @return An error code

   225 		*/

   226 		TInt SetAttribute(  TCookieAttributeName aAttributeName,

   227 							const THTTPHdrVal& aAttributeVal,

   228 							TBool aDefaulted );

   229         

   230 

   231 		/**

   232 		* Removes a cookie attribute. The attribute is closed, removed from

   233 		* the attribute list and the cookie size is also updated.

   234 		* @param aAttributeName identifies the attribute

   235 		*/

   236 		void RemoveAttribute( TCookieAttributeName aAttributeName );

   237 		

   238         /**

   239         * Copy from an already existing one.

   240         * @param aCopyFrom The already existing CCookie object

   241         */

   242         void CopyFromL( const CCookie& aCopyFrom  );

   243 

   244         /**

   245         * Returns this cookie's StringPool.

   246         */

   247         RStringPool StringPool();

   248 

   249 

   250 		/**

   251 		* Returns whether This cookie has expired or not.

   252         * @return	TBool indicating whether the cookie had expired or not.

   253 		*/

   254 		TBool Expired() const;

   255 

   256 

   257 		/**

   258 		* Returns whether This cookie is persistent or not.

   259         * @return	TBool indicating whether the cookie is persistent or not.

   260 		*/

   261 		TBool Persistent() const;

   262 

   263 

   264         /**

   265         * Returns whether the cookie's Version attribute is known or not.

   266         * @return TBool indicating the cookies's Version attribute's notoriety.

   267         */

   268         TBool IsUnknownVersion() const;

   269 

   270 

   271 	private :	// class for internal use

   272         /**

   273         * Determines if the cookie had expired in case of Netscape style

   274         * Method may leave with 

   275         *   KErrNoMemory 

   276         *   KErrNotFound, if parsing the date string fails (not a well formed string)

   277         * @param aAttrVal The THTTPHdrVal holding the Expires date as a string

   278         * @return A TBool holding the result

   279         */

   280         TBool ExpiredNetscapeL( THTTPHdrVal aAttrVal ) const;

   281 

   282         /**

   283         * Tokenize a string.

   284         * @return actual number of tokens

   285         * @param aString string to be tokenized

   286         * @param aTokenSeparators separator characters

   287         * @param aTokenCount expected number of tokens

   288         * @param aTokens position of token separators found in aString

   289         */

   290         TInt FindTokens( const TDesC8& aString, 

   291                          const TDesC8& aTokenSeparators, 

   292                          const TInt aTokenCount, 

   293                          TInt* aTokens ) const;

   294 		/**

   295 		* Class to store the name, value and the size of the value

   296 		* of an individual cookie attribute

   297 		*/

   298 		class TCookieAttribute

   299 			{

   300 			public :	// constructor

   301 				/**

   302 				* Constructor that initialises the name, value and size

   303 				* attributes.

   304 				* @param aName Identifies the attribute to be set

   305 				* @param aHdrVal The value of the attribute.

   306 				*/

   307 				TCookieAttribute( TCookieAttributeName aName,

   308 								const THTTPHdrVal& aHdrVal, 

   309 								TBool aDefaulted = EFalse );

   310 

   311 				/**

   312 				* Default constructor. It creates an uninitialized cookie

   313 				* attribute that may be initialized by the common = operator.

   314 				*/

   315 				TCookieAttribute();

   316 

   317 			public :	// accessor methods

   318 						// note that there are no 'set' methods as the only way

   319 						// to initialize a cookie attribute (apart from calling

   320 						// the detailed constructor) is using the = operator.

   321 				/**

   322 				* Get the name of the cookie attribute.

   323 				*/

   324 				TCookieAttributeName Name() const;

   325 

   326 				/**

   327 				* Get the value of the cookie attribute.

   328 				*/

   329 				const THTTPHdrVal& Value() const;

   330 

   331 				/**

   332 				* Get the size of the cookie attribute in bytes.

   333 				*/

   334 				TInt Size() const;

   335 

   336 				/**

   337 				* Gets whether the attribute is defulted or specified.

   338 				*/

   339 				TBool Defaulted() const;

   340 

   341 			public :	// other common methods

   342 				/**

   343 				* Closes an attribute - used to ensure string attributes are

   344 				* properly closed on destruction.

   345 				*/

   346 				void Close();

   347 

   348 			private :	// data members

   349 				/** The cookie attribute

   350 				*/

   351 				TCookieAttributeName iName;

   352 

   353 				/** The value of this attribute

   354 				*/

   355 				THTTPHdrVal iValue;

   356 

   357 				/**

   358 				* The size of this attribute in bytes. If this attribute

   359 				* refers to a string (folded or normal), then it is the length

   360 				* of the string, otherwise it contains the size in bytes

   361 				* returned by sizeof() operator.

   362 				*/

   363 				TInt iSize;

   364 

   365 				/**

   366 				* Stores that this attribute is defaulted ( ETrue )

   367 				* or was originally supplied ( EFalse )

   368 				* Needed to be able to decide whether the attribute should be 

   369 				* added when returning cookies to server

   370 				*/

   371 				TBool iDefaulted;

   372 				};

   373 

   374 	private :	// constructor

   375 		/**

   376 		* Constructor.

   377 		* @param aStringPool The current string pool.

   378 		*/

   379 		CCookie( RStringPool aStringPool );

   380 

   381 		/**

   382 		* Constructor.

   383 		* @param aRequestHeaders A collection of header fields associated

   384 		* with the current HTTP message,

   385 		* @param aPartIndex The index of the part in the header,

   386 		* @param aFieldName The HTTP header name,

   387 		* @param aUri HTTP request's URI.

   388 		*/

   389 		void ConstructL( RHTTPHeaders aRequestHeaders,

   390 						 TInt aPartIndex,

   391 						 RStringF aFieldName,

   392 						 const TUriC8& aUri );

   393 

   394 	private :	// common internal methods

   395 		/**

   396 		* When the cookie does not have a Path attribute, we have to add

   397 		* a default Path attribute. This method does this addition.

   398 		* @param aUri An initialized URI parser.

   399 		*/

   400 		void AddDefaultPathL( const TUriC8& aUri );

   401 

   402 		/** Finds the specified attribute in this cookie

   403 			@param aAttribute		

   404 			@param aAttributeName	

   405 			@return The index in iAttributes of the specified attribute.

   406 			KErrNotFound indicates that the cookie does not contain the

   407 			attribute.

   408 		*/

   409 		TInt FindAttribute( TCookieAttributeName aAttributeName,

   410 							TCookieAttribute& aAttribute ) const;

   411 

   412         /**

   413         *

   414         */

   415         TInt GetLocalOffset( HBufC8* aDate, TInt& aHour, 

   416                              TInt& aMinute, TInt& aLength ) const;

   417 

   418         /**

   419         *

   420         */

   421         TInt GetMilitaryOffset( HBufC8* aDate, TInt& aHour ) const;

   422 

   423         /**

   424         *

   425         */

   426         TInt GetTimeZone( HBufC8* aDate, TInt& aHour, 

   427                          TInt& aLength ) const;

   428 

   429 

   430         /**

   431         * Takes an HTTP header date-time information and returnes it in a 

   432         * format supported by TTime. 

   433         */

   434         HBufC8* GetCleanedDateTimeLC( HBufC8* aDate ) const;

   435 

   436 		/**

   437 		* Removes a cookie attribute. The attribute is closed, removed from

   438 		* the attribute list and the cookie size is also updated.

   439 		* @param aIndex The position of the cooke attribute in the attribute

   440 		* list.

   441 		*/

   442 		void RemoveAttribute( TInt aIndex );

   443 

   444 	private :	// data members

   445 		/** String pool that can be used by this cookie

   446 		*/

   447 		RStringPool iStringPool;

   448 		

   449 		/** Array of the attributes of this cookie

   450 		*/

   451 		RArray<TCookieAttribute> iAttributes;

   452 

   453 		/**

   454 		* Flag indicating whether this cookie was received in a

   455 		* SetCookie2 header

   456 		*/

   457 		TBool iSetCookie2;

   458 

   459         /**

   460 		* Flag indicating whether this cookie is Netscape or RFC compliant

   461 		* It is important to know it as they have different fields,

   462         * different defaulting and handling.

   463 		*/

   464 		TBool iNetscape;

   465 

   466 		TInt iSize;

   467 		TTime iReceivedTime;

   468 	};

   469 

   470 #include <Cookie.inl>

   471 

   472 #endif //	__CCOOKIE_H__