// Copyright (c) 2008-2009 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:
//

#ifndef __RHTTPMESSAGEPARSER_H__
#define __RHTTPMESSAGEPARSER_H__

#include <e32base.h>

class CHttpMessageParser;
class MHttpMessageParserObserver;

class RHttpMessageParser
/**
The RHttpMessageParser class provides parsing functionality for HTTP/1.1 
messages as defined in RFC2616. The HTTP/1.1 protocol specifies that the CR
LF sequence is the end of line (eol) marker for all protocol elements except
the entity-body. The parser tolerates some deviation from this, as the RFC
recommends in section 19.3 - a LF without the leading CR can also be parsed
as an eol marker.

The parser does not process any header fields. Therefore it needs to be told
if an entity body is expected. If one is then the parser needs to know if it
is chunk-encoded and if not what the expected size is.

With a chunked entity body the parser de-chunks the body data - the observer
does not need to parse a chunked body.

The parser needs an observer (MHttpMessageParserObserver). The observer 
supplies the buffers containing the unparsed http message data. The observer
must ensure that the buffers it supplies to the parser remain valid until the
parser notifies it that it has parsed the entire contents of that buffer.

The parser is initially in the Idle state waiting to be notified of available
meesage data. When it is notified, the parser obtains the data and moves
into the ParsingStartLine state.

Whichever state it is in, the parser will notify the observer when it has
parsed the entire contents of the current data buffer. It will then wait to
be told that there is more data available. When it has been given the next 
part of the message data it continues parsing.

In the ParsingStartLine state the parser looks for the first eol marker. 
This delimits the start-line. Once found the observer is notified and the
parser moves into the ParsingHeaders state.

In the ParsingHeaders state the parser searches for header field lines. 
These lines are delimited by eol markers. In HTTP/1.1 it is possible to fold
header field values over multiple lines if the continuation line is followed
by a SP or HT. In this case the eol marker is part of LWS and is ignored. 
Also any eol markers that are part of LWS are omitted from the header field
data given to the observer.

The header field section is completed once an empty line is parsed. The
observer is informed and it should supply the parser with the necessary
info about the entity body. If no entity body is expected then the parser 
moves to the MessageComplete state. If a non-encoded entity body is expected
then the parser moves to the ReadingBodyData state. If a chunk-encoded 
entity body is expected then the parser moves to the ParsingChunkSize state.

In the ReadingBodyData state the parser extracts the specified length of 
entity body data. The observer is notified of each chunk body data parsed. 
It is possible for the entity body data to be received in several parts due
to segmentation at the transport layer, Once all the entity body data has 
been received the parser notifies the observer that the entity body is 
complete. The parser moves to MessageComplete state.

Note that although the parser will have notified the obserer that it has 
finished with the current data packet that held some entity body data, the
observer should only release that data packet once it itself has no more use
for the entity body data it has been given. Failure to do this will result
in the buffer containing the received entity body chunks being invalid. The
same is true when receiving a chunked entity body.

In the ParsingChunkSize the parser searches for a chunk-size component as 
defined in RFC2616 section 3.6.1. The chunk-size component is delimited by
an eol marker. An optional chunk-extension component can be present between
the chunk-size and the eol marker - the parser will ignore any 
chunk-extension components. The chunk-size is a hex number specifying the 
size of the subsequent chunk-data component. A chunk-size of value zero 
indicates a last-chunk token - there are no subsequent chunk-data components
and the parser moves to the ParsingTrailerHeaders state. A chunk-size of any
other value indicates a subsequent chunk-data component and the parser moves
to the ParsingChunkData state.

In the ParsingChunkData state the parser extracts the length of entity body
data specified in the preceeding chunk-size component. The observer is 
notified of each chunk of entity body data. Note that a chunk-data component
can be segmented in the transport layer resulting in the observer being 
notified more than once for a given chunk-data component. The observer will
not notice any disparate behaviour between receiving an entity body that has 
not been chunk-encoded and one that has. Once the entire chunk-data has been 
received the parser moves to the ParsingChunkSize state.

The ParsingTrailerHeaders state is very similar to the ParsingHeaders state.
The observer is notified of each header field and the trailer headers 
section is delimited by an empty line. The observer is notified of the end
of the trailer headers section and the parser moves to MessageComplete state.

In the MessageComplete state the parser notifies the observer that the
message is complete. The observer is presented with any remaining data in 
the current data packet. This can be either excess data indicating a mal-
formed message or the start of a pipelined message. In either case if the 
observer wishes to use that data it must not release the current data packet
as that will invalidate the data.
@see		MHttpMessageParserObserver
*/
	{
public:	// methods

	inline RHttpMessageParser();

	IMPORT_C void OpenL(MHttpMessageParserObserver& aObserver);
	IMPORT_C void Close();
	IMPORT_C void ReceivedMessageData();
	IMPORT_C void CompletedBodyDataL();
	IMPORT_C void Reset();
	IMPORT_C void Flush ();
	IMPORT_C TBool CompleteMessage ( const TDesC8& aData );

private:	// methods

	IMPORT_C void Reserved_RHttpMessageParser();

private:	// attributes

	CHttpMessageParser*		iImplementation;

	};

inline RHttpMessageParser::RHttpMessageParser()
: iImplementation(NULL)
	{
	}
	
#endif // __RHTTPMESSAGEPARSER_H__