diff -r 000000000000 -r b16258d2340f netprotocols_plat/cookie_manager_api/inc/cookie.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/netprotocols_plat/cookie_manager_api/inc/cookie.h Tue Feb 02 01:09:52 2010 +0200 @@ -0,0 +1,472 @@ +/* +* Copyright (c) 2002 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: Declaration of classes CCookie +* +* +*/ + + +#ifndef __CCOOKIE_H__ +#define __CCOOKIE_H__ + +// INCLUDE FILES + // System includes +#include +#include +#include + +// FORWARD DECLARATIONS + +class RHTTPHeaders; +class TUriC8; + +// CONSTANTS + +// Attribute prefix : we have to pack cookies when either passing them over +// client-server boundaries or writing them into a file. When this happens we +// put each attribute of a cookie in the destination buffer as follows : +// prefix + attribute value + IsDefaulted, +// where prefix is a number that holds the length of the attribute to be +// stored. This prefix is a TInt. +const TInt KCookieAttributePrefixLength = sizeof( TInt ); +const TInt KCookieAttributeDefaultedLength = sizeof( TInt ); +const TInt KCookieAttributeFoundLength = sizeof( TInt ); + + +// This is the maximum number of attributes that may be defined in a cookie. +// TBD : should not we treat EExpires and EMaxAge attributes as one variable? +const TInt KCookieMaxAttributeCount = 13; + +// CLASS DECLARATION + +/** Class to store the data that makes up a cookie +*/ +class CCookie : public CBase + { + public : + /** Enumeration of all the elements of data that make up a cookie + */ + enum TCookieAttributeName + { + EName, // Name of the cookie - mandatory + EValue, // Value associated with the name - mandatory + EComment, // Comment which can be displayed to the user + ECommentURI, // A URI which can be visited for more information + EDiscard, // Flag indicating that the cookie should be discarded + EDomain, // Domain which this cookie applies to + EMaxAge, // Age after which this cookie should be deleted + EPath, // Path which this cookie applies to + EPort, // Port numbers that this cookie applies to + ESecure, // Flag indicating this cookie should only be used + // for secure transactions + EVersion, // Version of style of cookie - mandatory + EExpires, // Time after which this cookie should be deleted - + // Netscape cookies only + EDate, // Date when the response header containing the + // cookie was generated. It is important to know it + // for correct age calculation. + //EAge, // The age of the cookie as estimated by the cache + }; + + public : // exported methods + /** + * Constructor. + * @param aRequestHeaders A collection of header fields associated + * with the current HTTP message, + * @param aPartIndex The index of the part in the header, + * @param aFieldName The HTTP header name, + * @param aStringPool The current string pool, + * @param aUri HTTP request's URI. + */ + IMPORT_C static CCookie* NewL( RHTTPHeaders aRequestHeaders, + TInt aPartIndex, + RStringF aFieldName, + RStringPool aStringPool, + const TUriC8& aUri ); + /** + * Returns a descriptor which is equivalent to the input descriptor, + * but without the surrounding quotation marks. This method always + * returns the appropriate string even if there are no quotation marks, + * or at least one of them is missing. + * This is required because cookie attributes may be surrounded + * by double quotes. + * @param aDes The descriptor to be cleaned. + * @return Descriptor which points to the part of aDes with no quotes + */ + static TPtrC8 RemoveQuotes( const TDesC8& aDes ); + /** + * Constructor. + * @param aStringPool The current string pool. + */ + IMPORT_C static CCookie* NewL( RStringPool aStringPool ); + + + /** + * Standard destructor. + */ + IMPORT_C virtual ~CCookie(); + + + /** + * This method writes the cookie (i.e. its attributes) into the + * specified part of the HTTP header. The method may leave if writing + * is not successful (e.g. when RHTTPHeaders::SetParamL leaves) or if + * the cookie is not properly initialized. + * @param aRequestHeaders The current HTTP header collection to which we + * add this cookie, + * @param aPartIndex The part of the header. + */ + IMPORT_C void AddToRequestL( RHTTPHeaders aRequestHeaders, + TInt aPartIndex ) const; + + + /** Attribute retrieves the value of an attribute + * @param aAttributeName Identifies the attribute + * @param aAttributeVal The value being retrieved + * @return An error code. KErrNotFound will indicate that the cookie + * doesn't contain the specified attribute. + */ + IMPORT_C TInt Attribute( TCookieAttributeName aAttributeName, + THTTPHdrVal& aAttributeVal ) const; + + + /** SetAttribute sets an attribute on the cookie. + * Adding an attribute where one exists will replace the existing one + * @param aAttributeName identifies the attribute + * @param aAttributeVal the value being set + * @return An error code + */ + IMPORT_C TInt SetAttribute( TCookieAttributeName aAttributeName, + const THTTPHdrVal& aAttributeVal ); + + + public : // public inline methods + /** + * Did this cookie come from a SetCookie2 header? + * @return Flag indicating if this cookie was received in SetCookie2 + * header (rather than a SetCookie header). + */ + inline TBool FromCookie2() const; + + + /** + * Did this cookie come from a Netscape-version header? + * @return Flag indicating if this cookie was received + * in a Netscape-version header + */ + inline TBool FromNetscapeVersion() const; + + + /** + * Use this method to specify whether this cookie came from a SetCookie2 + * header. + * @param aFromCookie2 ETrue, if the cookie came from a SetCookie2 + * header, EFalse otherwise. + */ + inline void SetCookie2( TBool aFromCookie2 ); + + + /** + * Use this method to specify whether this cookie is a Netscape style + * one or an RFC compliant. + * @param aFromNetscape ETrue, if the cookie is a Netscape style one, + * EFalse otherwise. + */ + inline void SetFromNetscape( TBool aFromNetscape ); + + + /** + * Returns the number of bytes this cookie would require if it was + * stored in a flat buffer and one attribute followed the other. + * Note : the attributes are stored in a way that we first write out + * the size (TInt) of the attribute in question and then the attribute + * value. E.g. assuming a NAME attribute with the value of SESSIONID, we + * write out 9 as the length of NAME (again, stored as TInt) and then + * write out the value of NAME (i.e. SESSIONID). + * @param aSuppressDefaulted If ETrue, the method does not add the + * size of defaulted attributes to the overall size of the cookie. + * @return The size of the cookie. + */ + inline TInt Size( TBool aSuppressDefaulted ) const; + + + public : // public methods + /** Attribute retrieves the value of an attribute + * @param aAttributeName Identifies the attribute + * @param aAttributeVal The value being retrieved + * @param aDefaulted A TBool indicating whether the current + * attribute's value is defaulted or specified. + * @return An error code. KErrNotFound will indicate that the cookie + * doesn't contain the specified attribute. + */ + TInt Attribute( TCookieAttributeName aAttributeName, + THTTPHdrVal& aAttributeVal, + TBool& aDefaulted ) const; + + + /** SetAttribute sets an attribute on the cookie. + * Adding an attribute where one exists will replace the existing one + * @param aAttributeName identifies the attribute + * @param aAttributeVal the value being set + * @param aDefaulted a TBool indicating whether it is a defaulted + * or a supplied value + * @return An error code + */ + TInt SetAttribute( TCookieAttributeName aAttributeName, + const THTTPHdrVal& aAttributeVal, + TBool aDefaulted ); + + + /** + * Removes a cookie attribute. The attribute is closed, removed from + * the attribute list and the cookie size is also updated. + * @param aAttributeName identifies the attribute + */ + void RemoveAttribute( TCookieAttributeName aAttributeName ); + + /** + * Copy from an already existing one. + * @param aCopyFrom The already existing CCookie object + */ + void CopyFromL( const CCookie& aCopyFrom ); + + /** + * Returns this cookie's StringPool. + */ + RStringPool StringPool(); + + + /** + * Returns whether This cookie has expired or not. + * @return TBool indicating whether the cookie had expired or not. + */ + TBool Expired() const; + + + /** + * Returns whether This cookie is persistent or not. + * @return TBool indicating whether the cookie is persistent or not. + */ + TBool Persistent() const; + + + /** + * Returns whether the cookie's Version attribute is known or not. + * @return TBool indicating the cookies's Version attribute's notoriety. + */ + TBool IsUnknownVersion() const; + + + private : // class for internal use + /** + * Determines if the cookie had expired in case of Netscape style + * Method may leave with + * KErrNoMemory + * KErrNotFound, if parsing the date string fails (not a well formed string) + * @param aAttrVal The THTTPHdrVal holding the Expires date as a string + * @return A TBool holding the result + */ + TBool ExpiredNetscapeL( THTTPHdrVal aAttrVal ) const; + + /** + * Tokenize a string. + * @return actual number of tokens + * @param aString string to be tokenized + * @param aTokenSeparators separator characters + * @param aTokenCount expected number of tokens + * @param aTokens position of token separators found in aString + */ + TInt FindTokens( const TDesC8& aString, + const TDesC8& aTokenSeparators, + const TInt aTokenCount, + TInt* aTokens ) const; + /** + * Class to store the name, value and the size of the value + * of an individual cookie attribute + */ + class TCookieAttribute + { + public : // constructor + /** + * Constructor that initialises the name, value and size + * attributes. + * @param aName Identifies the attribute to be set + * @param aHdrVal The value of the attribute. + */ + TCookieAttribute( TCookieAttributeName aName, + const THTTPHdrVal& aHdrVal, + TBool aDefaulted = EFalse ); + + /** + * Default constructor. It creates an uninitialized cookie + * attribute that may be initialized by the common = operator. + */ + TCookieAttribute(); + + public : // accessor methods + // note that there are no 'set' methods as the only way + // to initialize a cookie attribute (apart from calling + // the detailed constructor) is using the = operator. + /** + * Get the name of the cookie attribute. + */ + TCookieAttributeName Name() const; + + /** + * Get the value of the cookie attribute. + */ + const THTTPHdrVal& Value() const; + + /** + * Get the size of the cookie attribute in bytes. + */ + TInt Size() const; + + /** + * Gets whether the attribute is defulted or specified. + */ + TBool Defaulted() const; + + public : // other common methods + /** + * Closes an attribute - used to ensure string attributes are + * properly closed on destruction. + */ + void Close(); + + private : // data members + /** The cookie attribute + */ + TCookieAttributeName iName; + + /** The value of this attribute + */ + THTTPHdrVal iValue; + + /** + * The size of this attribute in bytes. If this attribute + * refers to a string (folded or normal), then it is the length + * of the string, otherwise it contains the size in bytes + * returned by sizeof() operator. + */ + TInt iSize; + + /** + * Stores that this attribute is defaulted ( ETrue ) + * or was originally supplied ( EFalse ) + * Needed to be able to decide whether the attribute should be + * added when returning cookies to server + */ + TBool iDefaulted; + }; + + private : // constructor + /** + * Constructor. + * @param aStringPool The current string pool. + */ + CCookie( RStringPool aStringPool ); + + /** + * Constructor. + * @param aRequestHeaders A collection of header fields associated + * with the current HTTP message, + * @param aPartIndex The index of the part in the header, + * @param aFieldName The HTTP header name, + * @param aUri HTTP request's URI. + */ + void ConstructL( RHTTPHeaders aRequestHeaders, + TInt aPartIndex, + RStringF aFieldName, + const TUriC8& aUri ); + + private : // common internal methods + /** + * When the cookie does not have a Path attribute, we have to add + * a default Path attribute. This method does this addition. + * @param aUri An initialized URI parser. + */ + void AddDefaultPathL( const TUriC8& aUri ); + + /** Finds the specified attribute in this cookie + @param aAttribute + @param aAttributeName + @return The index in iAttributes of the specified attribute. + KErrNotFound indicates that the cookie does not contain the + attribute. + */ + TInt FindAttribute( TCookieAttributeName aAttributeName, + TCookieAttribute& aAttribute ) const; + + /** + * + */ + TInt GetLocalOffset( HBufC8* aDate, TInt& aHour, + TInt& aMinute, TInt& aLength ) const; + + /** + * + */ + TInt GetMilitaryOffset( HBufC8* aDate, TInt& aHour ) const; + + /** + * + */ + TInt GetTimeZone( HBufC8* aDate, TInt& aHour, + TInt& aLength ) const; + + + /** + * Takes an HTTP header date-time information and returnes it in a + * format supported by TTime. + */ + HBufC8* GetCleanedDateTimeLC( HBufC8* aDate ) const; + + /** + * Removes a cookie attribute. The attribute is closed, removed from + * the attribute list and the cookie size is also updated. + * @param aIndex The position of the cooke attribute in the attribute + * list. + */ + void RemoveAttribute( TInt aIndex ); + + private : // data members + /** String pool that can be used by this cookie + */ + RStringPool iStringPool; + + /** Array of the attributes of this cookie + */ + RArray iAttributes; + + /** + * Flag indicating whether this cookie was received in a + * SetCookie2 header + */ + TBool iSetCookie2; + + /** + * Flag indicating whether this cookie is Netscape or RFC compliant + * It is important to know it as they have different fields, + * different defaulting and handling. + */ + TBool iNetscape; + + TInt iSize; + TTime iReceivedTime; + }; + +#include + +#endif // __CCOOKIE_H__