--- /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 <e32std.h>
+#include <stringpool.h>
+#include <http/thttphdrval.h>
+
+// 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<TCookieAttribute> 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 <Cookie.inl>
+
+#endif // __CCOOKIE_H__