williamr@2: // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@2: // 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
williamr@2: // which accompanies this distribution, and is available
williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2:  @file RHTTPHeaders.h
williamr@2:  @warning : This file contains Rose Model ID comments - please do not delete
williamr@2: */
williamr@2: 
williamr@2: #ifndef	__RHTTPHEADERS_H__
williamr@2: #define	__RHTTPHEADERS_H__
williamr@2: 
williamr@2: // System includes
williamr@2: #include <http/thttphdrfielditer.h>
williamr@2: #include <http/thttphdrval.h>
williamr@2: 
williamr@2: 
williamr@2: //##ModelId=3C4C1880001A
williamr@2: class RHTTPHeaders
williamr@2: /** 
williamr@2: The collection of headers (or more correctly, header fields)
williamr@2: associated with a message. Header (fields) can be created, read and
williamr@2: modified. They may be composed of several parts (by repeated
williamr@2: invocations of API methods, see below) and may be assigned one or
williamr@2: more parameters.  Individual field parts and parameters take
williamr@2: values described using THTTPHdrVal.
williamr@2: @publishedAll
williamr@2: @released
williamr@2: @see RHTTPMessage
williamr@2: @see THTTPHdrVal
williamr@2: */
williamr@2: 	{
williamr@2:  public:
williamr@2: 	/** Default constructor
williamr@2: 	*/
williamr@2: 	//##ModelId=3C4C18800088
williamr@2: 	inline RHTTPHeaders();
williamr@2: 
williamr@2: 	/**Getter methods
williamr@2: 		Methods for reading data.
williamr@2: 	*/
williamr@2: 	//@{
williamr@2: 	/** Obtain the number of parts in the named header field's value,
williamr@2: 		Simple headers are created with a single part following one
williamr@2: 		call to SetFieldL. Subsequent calls to SetFieldL create
williamr@2: 		additional parts if the field exists already.
williamr@2: 		@leave KErrNoMemory
williamr@2: 		@param aFieldName The header name
williamr@2: 		@return The number of parts, or zero if the field does not exist.  */
williamr@2: 	//##ModelId=3C4C18800081
williamr@2: 	IMPORT_C TInt FieldPartsL(RStringF aFieldName) const;
williamr@2: 
williamr@2: 	/** Obtain the named header field's value. The index
williamr@2: 		of a part within the field must be specified. Parts are indexed
williamr@2: 		from 0 and fields with only one part return the entire field for index 0
williamr@2: 		@param aFieldName The header name
williamr@2: 		@param aPartIdx The index of the part
williamr@2: 		@param aHeaderValue The header field value
williamr@2: 		@return An error condition. Returns KErrNotFound if there is not  a field with the 
williamr@2: 				specifed field name
williamr@2: 	*/
williamr@2: 	//##ModelId=3C4C18800079
williamr@2: 	IMPORT_C TInt GetField(RStringF aFieldName, 
williamr@2: 								  TInt aPartIdx, THTTPHdrVal& aHeaderValue) const;
williamr@2: 
williamr@2: 	/** Obtain an Raw representation of the named header
williamr@2: 		field's value.  Note that general client use of this method is
williamr@2: 		strongly discouraged since it exposes the Raw representation of particular headers.  
williamr@2: 		However it may be needed for some cases where received headers could not be
williamr@2: 		decoded by HTTP.  It will normally be used internally when
williamr@2: 		preparing header data to be transmitted with a request.
williamr@2: 		Note that this API may not return the field values for all the headers.
williamr@2: 		@param aFieldName The field name, e.g, 'Content-Type'
williamr@2: 		@param aRawFieldData The field's data content, in an appropriate Raw form 
williamr@2: 		@return An error condition. Returns KErrNotFound if there is not  a field with the 
williamr@2: 				specifed field name
williamr@2: 	*/
williamr@2: 	//##ModelId=3C4C18800076
williamr@2: 	IMPORT_C TInt GetRawField(RStringF aFieldName, 
williamr@2: 							   TPtrC8& aRawFieldData) const;
williamr@2: 
williamr@2: 	/** Obtain the value of a named parameter, associated with the
williamr@2: 		named header field.  An optional index to a part within the
williamr@2: 		header field may be supplied, if not it is assumed that it is
williamr@2: 		the first part.
williamr@2: 		@param aFieldName The header name
williamr@2: 		@param aParamName The parameter name
williamr@2: 		@param aReturn The returned value. Note that this
williamr@2: 		must be Copy()d by the caller, if it wants to keep the value.
williamr@2: 		@param aPartIdx The optional index of the part
williamr@2: 		@return An error condition. Returns KErrNotFound if there is not  a field with the 
williamr@2: 				specifed field name  */
williamr@2: 	//##ModelId=3C4C1880006C
williamr@2: 	IMPORT_C TInt GetParam(RStringF aFieldName, 
williamr@2: 								  RStringF aParamName, 
williamr@2: 								  THTTPHdrVal& aReturn,
williamr@2: 								  TInt aPartIdx = 0) const;
williamr@2: 
williamr@2: 	/** Access the fields within this header collection, via an
williamr@2: 		iterator.  Each application of the iterator returns the name
williamr@2: 		of the next field type.  This may then be accessed via
williamr@2: 		RHTTPHeaders methods.
williamr@2: 		@return The iterator.  */
williamr@2: 	//##ModelId=3C4C1880006B
williamr@2: 	IMPORT_C THTTPHdrFieldIter Fields() const;
williamr@2: 	//@}
williamr@2: 
williamr@2: 	/** Setter Methods
williamr@2: 		Methods for writing data.
williamr@2: 	*/
williamr@2: 	//@{
williamr@2: 	/** Set a named field in the header.  On the first instance that
williamr@2: 		this API method is used for a given field name, the first will
williamr@2: 		be created.  On subsequent calls, the same field will be
williamr@2: 		extended to have several parts, with a new part created to
williamr@2: 		hold the supplied value.
williamr@2: 		@param aFieldName The field name, e.g, 'Content-Type'
williamr@2: 		@param aFieldValue The field value, e.g. 'text/html' */
williamr@2: 	//##ModelId=3C4C18800060
williamr@2: 	IMPORT_C void SetFieldL(RStringF aFieldName, THTTPHdrVal aFieldValue);
williamr@2: 
williamr@2: 	/** Set a named field in the header, and associate with it the
williamr@2: 		supplied parameter. If the field doesn't already exist it will
williamr@2: 		be created along with a parameter; if it does exist, then a
williamr@2: 		new part will be created along with the parameter.
williamr@2: 		@param aFieldName The field name, e.g. 'Accept'
williamr@2: 		@param aFieldValue The field value. e.g. 'text/plain'
williamr@2: 		@param aParamName The parameter name, e.g. 'q'
williamr@2: 		@param aParamValue The parameter value, e.g. '0.3' */
williamr@2: 	//##ModelId=3C4C18800063
williamr@2: 	IMPORT_C void SetFieldL(RStringF aFieldName, THTTPHdrVal aFieldValue,
williamr@2: 							RStringF aParamName, THTTPHdrVal aParamValue);
williamr@2: 
williamr@2: 	/** Set a parameter in an existing header. 
williamr@2: 		@param aFieldName The field name, e.g. 'Accept'
williamr@2: 		@param aPartIdx The part of the header to add the parameter to
williamr@2: 		@param aParamName The parameter name, e.g. 'q'
williamr@2: 		@param aParamValue The parameter value, e.g. '0.3'
williamr@2: 		@leave KErrNotFoud if the field, or the part within the field doesn't exist
williamr@2: 	*/
williamr@2: 	//##ModelId=3C4C18800058
williamr@2: 	IMPORT_C void SetParamL(RStringF aFieldName, RStringF aParamName, THTTPHdrVal aParamValue, TInt aPartIdx);
williamr@2: 
williamr@2: 	/** Set a named field in the header to contain the supplied Raw header
williamr@2: 		data. If the header already exists then a LF and the new data will be added to the existing data. This is used to
williamr@2: 		indicate that there are multiple instances of this header
williamr@2: 
williamr@2: 
williamr@2: 		Note that general client use of this method is strongly
williamr@2: 		discouraged since it exposes the raw representation of particular headers.  
williamr@2: 		However it may be needed for some cases where headers to be transmitted have no encoding known
williamr@2: 		to HTTP.  It will normally be used internally when receiving data from a service provider.
williamr@2: 		@param aFieldName The field name, e.g, 'Content-Type'
williamr@2: 		@param aRawFieldData The field's data content, in a raw form
williamr@2: 		@param aFieldSeparator The header field separator
williamr@2: 	*/
williamr@2: 	//##ModelId=3C4C1880004F
williamr@2: 	IMPORT_C void SetRawFieldL(RStringF aFieldName, 
williamr@2: 							   const TDesC8& aRawFieldData,
williamr@2: 							   const TDesC8& aFieldSeparator);
williamr@2: 
williamr@2: 	/** Remove, entirely, the named header field from the header
williamr@2: 		collection. All its parts and associated parameters (where
williamr@2: 		they exist) are also removed.
williamr@2: 		@param aFieldName The field name.
williamr@2: 		@return KErrNone if the removal is successful; KErrNotFound if
williamr@2: 		the field didn't exist within the headers.  */
williamr@2: 	//##ModelId=3C4C1880004D
williamr@2: 	IMPORT_C TInt RemoveField(RStringF aFieldName);
williamr@2: 
williamr@2: 	/** Remove a single part of a header field. Just the part and any associated paramters are removed. If this 
williamr@2: 		results in no parts being present in the header then it will also be removed
williamr@2: 		@param aFieldName The header name
williamr@2: 		@param aIndex The particular part of the field to be removed
williamr@2: 		@return KErrNone if the removal is sucessful; KErrNotFound if the header didn't exist. No exception is raised if 
williamr@2: 		the particular value is not found as part of that header */
williamr@2: 	//##ModelId=3C4C18800043
williamr@2: 	IMPORT_C TInt RemoveFieldPart(RStringF aFieldName, TInt aIndex);
williamr@2: 
williamr@2: 	/** Remove all the fields of this header collection
williamr@2: 	*/
williamr@2: 	//##ModelId=3C4C18800042
williamr@2: 	IMPORT_C void RemoveAllFields();
williamr@2: 
williamr@2: 	//@}
williamr@2: 
williamr@2: 
williamr@2: private:
williamr@2: 	friend class CHeaders;
williamr@2: 	//##ModelId=3C4C1880003A
williamr@2: 	CHeaders* iImplementation;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: inline RHTTPHeaders::RHTTPHeaders()
williamr@2: 		: iImplementation(NULL)
williamr@2: 	{
williamr@2: 	}
williamr@2: 
williamr@2: 
williamr@2: #endif  // __RHTTPHEADERS_H__