CHeaderField Class Reference

class CHeaderField : public CBase

Generalised internal representation of a single HTTP header field. The field's value may be contained as raw data as received by HTTP, or in a object-oriented parsed form, which is accessible to the client via the class API.

Each field has a type and a (potentially complex) value. The type must be chosen at construction time, and remains the same during the header's lifetime.

Simple headers are represented using a single 'part'. Several factory methods are provided for each type the part can take; e.g.

	Max-Forwards: 3							-- a single integer value
	Location: http://ayg.com/				-- a single string token value
	Expires: Mon, 15 Jan 2001 10:30:25 GMT	-- a single date/time value
	

More complex headers are possible (see the RFC2116 for many more examples) which are built up from several parts; e.g.

	Accept: text/wml, application/vnd.wap.wmlc	-- a header with two string token parts
	Allow: GET, POST, HEAD						-- a header with three string token parts
	

Multiple parts are supported by the CHeaderFieldPart class.

Furthermore, some headers allow parameters to be supplied in the form of attribute-value pairs. These may be present on any part of the header, according to the syntax defined in the RFC; e.g.

	Accept-Charset: utf-8; q=0.8, us-ascii; q=0.2
	Cache-Control: maxage=6000
	

Parameters are supported by the CHeaderFieldParam class.

The classes CHeaderField, CHeaderFieldPart and CHeaderFieldParam are internal header representations and will only be manipulated by protocol handlers and filters. Only the RHTTPHeaders and THTTPHdrVal classes are intended for use by the Client. RHTTPHeaders THTTPHdrVal CHeaderFieldPart CHeaderFieldParam

Inherits from

Public Member Functions
~CHeaderField()
TInt AddPart(CHeaderFieldPart *)
voidAddPartL(CHeaderFieldPart *)
voidBeginRawDataL(TInt)
voidCommitRawData()
TInt ConvertToParsedFormat()
voidInsertPartL(CHeaderFieldPart *, TInt)
RStringF Name()
CHeaderField *New(RStringF, CHeaders &)
CHeaderField *NewL(RStringF, CHeaders &)
CHeaderField *NewL(RStringF, CHeaders &, THTTPHdrVal)
CHeaderField *NewL(RStringF, CHeaders &, const TDesC8 &)
TInt NumPartsL()
TInt Part(TInt, CHeaderFieldPart *&)
CHeaderFieldPart *PartL(TInt)
THeaderFieldPartIter PartsL()
IMPORT_C voidRawDataL(TPtrC8 &)
TInt RemovePartL(CHeaderFieldPart *)
TInt RemovePartL(TInt)
voidSetPartL(CHeaderFieldPart *, TInt)
TInt SplitValueAndParameterArray()
voidWriteRawDataL(const TDesC8 &)
voidWriteRawDataL(TChar)
Private Member Functions
CHeaderField(RStringF, CHeaders &)
voidClearParsedData()
voidClearRawData()
voidConstructL(const TDesC8 &)
voidConvertToParsedFormatL()
voidConvertToRawFormatL()
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Private Member Enumerations
enumTDataState { ENoDataSupplied = 0x00, EDataInRawForm = 0x01, EDataParsedOK = 0x02, EDataParseError = 0x03 }
Private Attributes
const CHeaderCodec &iCodec
TDataState iDataParseState
RPointerArray< CHeaderFieldPart >iElementArray
RStringF iName
CHeaders *iOwner
RPointerArray< CHeaderFieldParam >iParameterArray
RPointerArray< CHeaderFieldPart >iParts
TInt iRawChunkSize
HBufC8 *iRawData

Constructor & Destructor Documentation

CHeaderField(RStringF, CHeaders &)

CHeaderField(RStringFaHeaderFieldName,
CHeaders &aOwner
)[private]

Standard constructor. Used when client constructs headers.

Parameters

RStringF aHeaderFieldNameA string table reference to the header field's name.
CHeaders & aOwnerThe header fields collection that this field belongs to

~CHeaderField()

~CHeaderField()[virtual]

D'tor

Member Functions Documentation

AddPart(CHeaderFieldPart *)

TInt AddPart(CHeaderFieldPart *aPart)

Parameters

CHeaderFieldPart * aPart

AddPartL(CHeaderFieldPart *)

voidAddPartL(CHeaderFieldPart *aPart)
Add a part to the header. It is appended after any existing parts. Simple headers have just one part; they could be constructed using the 'single part' NewL() methods.
leave
KErrNoMemory - insufficient free memory to create an instance of the class, or any classes needed to create subclasses for parsing
leave
KErrNotSupported - if decoding for this header field can't be made

Parameters

CHeaderFieldPart * aPartThe part to be added. The header takes ownership of the new part.

BeginRawDataL(TInt)

voidBeginRawDataL(TIntaChunkSize =  KHttpDefaultRawChunkSize )
Start setting Raw data in the header. Leaves if initial Raw buffer allocation fails. The optional parameter specifies the size to be used for Raw data chunk allocation. Note this is for use only by the header codec.
leave
KErrNoMemory - insufficient free memory buffer allocation

Parameters

TInt aChunkSize =  KHttpDefaultRawChunkSize

ClearParsedData()

voidClearParsedData()[private]

ClearRawData()

voidClearRawData()[private]

CommitRawData()

voidCommitRawData()

Commit the Raw data. The parsed header parts and parameters are removed. Note this is for use only by the header codec.

ConstructL(const TDesC8 &)

voidConstructL(const TDesC8 &aRawData)[private]

Phase Two construction. This variant copies-to-keep the supplied Raw data buffer.

Parameters

const TDesC8 & aRawDataAn 8-bit buffer containing raw header data received by HTTP.

ConvertToParsedFormat()

TInt ConvertToParsedFormat()

ConvertToParsedFormatL()

voidConvertToParsedFormatL()[private]
Create the part objects that represent the header field's value, by parsing the Raw data received by HTTP. The Raw data is removed after conversion completes successfully.
leave
KErrNotSupported if a codec that supports encoding this header cannot be found

ConvertToRawFormatL()

voidConvertToRawFormatL()[private]
Create an Raw encoding of the header's field name and value. This is done using the Codec, which must be supplied prior to this call. The part data is removed after conversion to the Raw format.
leave
KErrNotSupported if a codec that supports encoding this header cannot be found
Constructors and second-phase construction

InsertPartL(CHeaderFieldPart *, TInt)

voidInsertPartL(CHeaderFieldPart *aPart,
TIntaIndex
)
Insert a part into the header. It is inserted at the specified index - i.e. to insert a new part at the start of the header, aIndex should be set to 0.
leave
KErrNoMemory - insufficient free memory to create an instance of the class, or any classes needed to create subclasses for parsing
leave
KErrNotSupported - if decoding for this header field can't be made

Parameters

CHeaderFieldPart * aPartThe part to be inserted. The header takes ownership of the new part.
TInt aIndexThe index at which the part is to be inserted.

Name()

RStringF Name()const [inline]

Obtain the name of the header field, e.g. Accept

New(RStringF, CHeaders &)

CHeaderField *New(RStringFaHeaderFieldName,
CHeaders &aOwner
)[static]

Parameters

RStringF aHeaderFieldName
CHeaders & aOwner

NewL(RStringF, CHeaders &)

CHeaderField *NewL(RStringFaHeaderFieldName,
CHeaders &aOwner
)[static]
Create a new header field that has no value yet.
leave
KErrNoMemory - insufficient free memory to create an instance of the class.

Parameters

RStringF aHeaderFieldNameThe header field type.
CHeaders & aOwnerThe header fields collection that this field belongs to

NewL(RStringF, CHeaders &, THTTPHdrVal)

CHeaderField *NewL(RStringFaHeaderFieldName,
CHeaders &aOwner,
THTTPHdrValaVal
)[static]
Create a new header field with a single part, whose HTTP value is specified.
leave
KErrNoMemory - insufficient free memory to create an instance of the class, or any classes needed to create subclasses for parsing
leave
KErrNotSupported - if decoding for this header field can't be made

Parameters

RStringF aHeaderFieldNameThe header field type.
CHeaders & aOwnerThe header fields collection that this field belongs to
THTTPHdrVal aValThe header field value. A copy is taken when storing.

NewL(RStringF, CHeaders &, const TDesC8 &)

CHeaderField *NewL(RStringFaHeaderFieldName,
CHeaders &aOwner,
const TDesC8 &aRawData
)[static]
Create a new header field from the supplied Raw data using the specified transaction codec.
leave
KErrNoMemory - insufficient free memory to create an instance of the class, or any classes needed to create subclasses for parsing
leave
KErrNotSupported - if decoding for this header field can't be made

Parameters

RStringF aHeaderFieldNameThe header field type.
CHeaders & aOwnerThe header fields collection that this field belongs to
const TDesC8 & aRawDataThe raw data buffer, as a descriptor

NumPartsL()

TInt NumPartsL()
Obtain the number of parts in this header
leave
KErrNoMemory - insufficient free memory for object creation when decoding parts
leave
KErrNotSupported - if decoding when counting parts fails

Part(TInt, CHeaderFieldPart *&)

TInt Part(TIntaindex,
CHeaderFieldPart *&aPart
)

Parameters

TInt aindex
CHeaderFieldPart *& aPart

PartL(TInt)

CHeaderFieldPart *PartL(TIntaIndex)
Access the header value parts by index
leave
KErrNoMemory - insufficient free memory for object creation when decoding parts
leave
KErrNotSupported - if decoding when counting parts fails

Parameters

TInt aIndexThe index of the desired part. 0 references the first one.

PartsL()

THeaderFieldPartIter PartsL()
Access the header value parts via an iterator
leave
KErrNoMemory - insufficient free memory for object creation when decoding parts
leave
KErrNotSupported - if decoding when counting parts fails

RawDataL(TPtrC8 &)

IMPORT_C voidRawDataL(TPtrC8 &aRawData)
Get the Raw header representation. This will flip the internal state of the header, if it's not already in Raw form. Requires a Codec to be set.
leave
KErrNoMemory - insufficient free memory for object creation when decoding parts
leave
KErrNotSupported - if decoding when counting parts fails

Parameters

TPtrC8 & aRawData

RemovePartL(CHeaderFieldPart *)

TInt RemovePartL(CHeaderFieldPart *aPart)
Remove the specified part from the header.
leave
KErrNoMemory - insufficient free memory to create an instance of the class, or any classes needed to create subclasses for parsing
leave
KErrNotSupported - if decoding for this header field can't be made

Parameters

CHeaderFieldPart * aPartThe part to be removed. The header deletes the removed part.

RemovePartL(TInt)

TInt RemovePartL(TIntaIndex)
Remove the indexed part from the header
leave
KErrNoMemory - insufficient free memory to create an instance of the class, or any classes needed to create subclasses for parsing
leave
KErrNotSupported - if decoding for this header field can't be made

Parameters

TInt aIndexAn index to the part to be removed. The header deletes the removed part.

SetPartL(CHeaderFieldPart *, TInt)

voidSetPartL(CHeaderFieldPart *aPart,
TIntaIndex
)

Set a part in the header. It replaces any existing parts at the specified index. Note this is for use only by the header codec, when converting Raw data into parsed header parts from parsed Raw data. This function may leave with any of the system wide error codes, if the attempt to append this part to the internal list fails. Setters

Parameters

CHeaderFieldPart * aPartThe part to be added. The header takes ownership of the new part.
TInt aIndexThe index of the part you are replacing

SplitValueAndParameterArray()

TInt SplitValueAndParameterArray()

WriteRawDataL(const TDesC8 &)

voidWriteRawDataL(const TDesC8 &aData)
Add more Raw data, supplied as a descriptor. The buffer is extended as necessary. Leaves if buffer allocation fails. Note this is for use only by the header codec.
leave
KErrNoMemory - insufficient free memory buffer allocation

Parameters

const TDesC8 & aData

WriteRawDataL(TChar)

voidWriteRawDataL(TCharaData)
Add more Raw data, supplied as a single character. The buffer is extended as necessary. Leaves if buffer allocation fails. Note this is for use only by the header codec.
leave
KErrNoMemory - insufficient free memory buffer allocation

Parameters

TChar aData

Member Enumerations Documentation

Enum TDataState

Enumeration of the states in which this header's value data can exist.

Enumerators

ENoDataSupplied = 0x00

the header object is not populated with data after construction

EDataInRawForm = 0x01

the data is in it's raw form, i.e. not accessible by part

EDataParsedOK = 0x02

the data is in it's client representation, i.e. parsed into parts.

EDataParseError = 0x03

the data could not be parsed so remains in Raw form

Member Data Documentation

const CHeaderCodec & iCodec

const CHeaderCodec &iCodec[private]

Codec used to convert this header

TDataState iDataParseState

TDataState iDataParseState[private]

Has this header been parsed yet? did it parse correctly?

RPointerArray< CHeaderFieldPart > iElementArray

RPointerArray< CHeaderFieldPart >iElementArray[private]

RStringF iName

RStringF iName[private]

Name of this header (a reference into the string table)

CHeaders * iOwner

CHeaders *iOwner[private]

Headers collection that owns this field

RPointerArray< CHeaderFieldParam > iParameterArray

RPointerArray< CHeaderFieldParam >iParameterArray[private]

RPointerArray< CHeaderFieldPart > iParts

RPointerArray< CHeaderFieldPart >iParts[private]

Header data - in parsed format. TodoIs it worth this being a union?

TInt iRawChunkSize

TInt iRawChunkSize[private]

Size of data chunk used when allocating and extending the Raw data buffer

HBufC8 * iRawData

HBufC8 *iRawData[private]

Header data - in Raw format. TodoIs it worth this being a union?