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@4: // under the terms of "Eclipse Public License v1.0" williamr@2: // which accompanies this distribution, and is available williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.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@4: @file 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 williamr@2: #include 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@4: 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@4: williamr@4: IMPORT_C void GetRawFieldL(RStringF aFieldName, TPtrC8& aRawFieldData) const; williamr@4: 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@4: IMPORT_C TInt SetField(RStringF aFieldName, THTTPHdrVal aFieldValue); williamr@4: 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@4: IMPORT_C TInt SetField(RStringF aFieldName, THTTPHdrVal aFieldValue, williamr@4: RStringF aParamName, THTTPHdrVal aParamValue); 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@4: williamr@4: IMPORT_C TInt SetRawField(RStringF aFieldName, const TDesC8& aRawFieldData, const TDesC8& aFieldSeparator); 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@4: friend class CHttpClientTransaction; williamr@4: friend class CHttpClientTransactionImpl; 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__