// 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 __RHTTPMESSAGECOMPOSER_H__
#define __RHTTPMESSAGECOMPOSER_H__

#include <e32std.h>

class CHttpMessageComposer;
class MHttpMessageComposerObserver;

class RHttpMessageComposer
/**	
The RHttpMessageComposer class provides functionality for creating 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 composer does not process any header fields or start-line tokens. 
Therefore it needs to be told if headers and/or an entity body is expected. 
If the message does contain an entity body and the body data is streamed the
composer will apply the chunked transfer encoding to the entity body.

The composer needs an observer (MHttpMessageComposerObserver). The observer 
supplies the message info such as the start-line tokens, header field tokens
and other message info. An MHTTPDataSupplier object is used to supply the 
entity body data if there is one. The observer must ensure that the 
descriptors containing the tokens it supplies remain valid until the composer
notifies it that the message is complete.

The composer is initially in the Idle state waiting to be notified of 
available message info. When it is notified, the composer moves into the 
CreatingStartLine state.

In the CreatingStartLine state the composer obtains the start-line tokens 
from the observer. These are added to the current data buffer. The composer
asks its observer if the message has any headers. If there are headers the 
composer moves to the CreatingHeaders state otherwise it moves to the
CreatingEndOfHeaders state.

In the CreatingHeaders state the composer adds header fields to the current
data buffer. The observer provides the header field tokens for the field name
and field value. The composer will not fold header field values onto multiple
lines unless the provided field token already contains folded field values.
The observer also informs the composer if the provided field info is for the
last header field. If this is the case the composer moves into the 
CreatingEndOfHeaders state, otherwise it remains in the CreatingHeaders state.

In the CreatingEndOfHeaders state the composer adds an empty line to the 
current data buffer to mark the end of the header fields section. The current
data buffer is ready to be sent and the composer informs its observer of this.
The composer moves into the PendingEntityBody and waits for the observer to
notify it that it has finished with the current data buffer.

In the PendingEntityBody state the releases the current data buffer. It then
asks its observer if the message has an entity body. If there is no entity 
body or if it is zero length then the composer moves to PendingIdle state. 
If there is an entity body and the size is known the composer moves to the 
SendEntityData state. If the entity body size is unknown, implying streamed
entity body data, the composer moves to the CreatingChunkSize state.

In the SendEntityBody state the composer gets the next entity body data part
from the data supplier for the entity body. It sets this data as the current
send buffer and notifies the observer that message data is ready. A check is
made to see that if the data supplier claims that this is the last data part 
that all the specified amount of entity body data has been sent. If this is 
not true the observer will receive an error code of KErrCorrupt. The composer
moves to PendingReleaseData state and waits for the observer to notify it 
that it has finished with the current data buffer.

In the PendingReleaseData state the composer notifies the entity body data
supplier that it has finished with the current data part. If all the 
specified entity body data has been sent the composer moves to the 
PendingIdle state. If there is more entity body data to send the composer
moves to the SendEntityData and waits for the observer to notify it that 
there is more message info available.

In the CreatingChunkSize state the composer adds the size of the following
chunk-data component to the current send buffer as defined in RFC2616 
section 3.6.1. The send buffer wil contain the empty line delimiting the 
previous chunk-data component if this is not the first chunk-size component
to be sent. The composer notifies its observer that message data is ready. 
The composer moves into the SendChunkData state and waits for the observer 
to notify it that it has finished with the current data buffer.

If the chunk-data is zero-length then the chunk-size component is not added
to the send buffer.	

In the SendChunkData state the composer releases the current data buffer. It
then gets the chunk-data from the data supplier for the entity body. It sets
this data as the current buffer. The observer is only notified that message 
data is ready if the chunk-data is not zer-length. The composer moves into 
the PendingReleaseChunk state and waits for the observer to notify it that 
it has finished with the current data buffer.

In the PendingReleaseChunk state the composer notifies the entity body data
supplier that it has finished with the current data part. If that was the 
last part of the entity body data the composer adds the last-chunk component
to the current data buffer. It then asks the observer if the message has any 
trailer headers. If there are trailer headers then the composer moves to the 
CreatingTrailers state. Otherwise the composer moves to the 
CreatingEndOfTrailers state. 

If there is more entity body data to follow the composer moves to the 
CreatingChunkSize state and waits for the observer to notify it that there is 
more message info available.

In the CreatingTrailers state the composer adds trailer header fields to the 
current data buffer. The observer provides the trailer header field tokens 
for the field name and field value. The composer will not fold header field 
values onto multiple lines unless the provided field token already contains 
folded field values. The observer also informs the composer if the provided 
field info is for the last trailer header field. If this is the case the 
composer moves into the CreatingEndOfTrailers state, otherwise it remains in 
the CreatingTrailers state.

In the CreatingEndOfTrailers state the composer adds an empty line to the 
current data buffer to mark the end of the trailer header fields section. 
The current data buffer is ready to be sent and the composer informs its 
bserver of this. The composer moves into the PendingEndOfChunkedBody and 
waits for the observer to notify it that it has finished with the current 
data buffer.

In the PendingEndOfChunkedBody the composer releases the current data buffer
and moves into the PendingIdle state. 

In the PendingIdle state the composer informs its observer that the message
is complete. The composer moves to the Idle state.
@see		MHttpMessageComposerObserver
*/
	{
public:	// methods

	inline RHttpMessageComposer();

	IMPORT_C void OpenL(MHttpMessageComposerObserver& aObserver);
	IMPORT_C void Close();
	IMPORT_C void MessageInfoAvailable();
	IMPORT_C void GetMessageData(TPtrC8& aData);
	IMPORT_C void ReleaseMessageData();
	IMPORT_C void Reset();
	IMPORT_C TBool CheckMessagePendingComplete();

private:	// methods

	IMPORT_C void Reserved_RHttpMessageComposer();

private:	// attributes

	CHttpMessageComposer*	iImplementation;

	};

inline RHttpMessageComposer::RHttpMessageComposer()
: iImplementation(NULL)
	{
	}

#endif	// __RHTTPMESSAGECOMPOSER_H__