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 __MHTTPDATASUPPLIER_H__ williamr@2: #define __MHTTPDATASUPPLIER_H__ williamr@2: williamr@2: // System includes williamr@2: #include williamr@2: williamr@2: williamr@2: //##ModelId=3C4C187903E5 williamr@2: class MHTTPDataSupplier williamr@2: /** williamr@2: A data supplier - This class is used to deliver the response data williamr@2: to the client, and is also used by the client to supply request williamr@2: body data to HTTP in POST transactions. Data is supplied in a williamr@2: number of parts. When a part is available it can be retreived williamr@2: with GetNextDataPart. The returned descriptor will remain valid until williamr@2: ReleaseData is called. williamr@2: williamr@2: To use this class to supply POST data, you have a number of williamr@2: options. If the post data needs to be URL Form encoded, you should williamr@2: use CHTTPFormEncoder, which will do the encoding and interface to williamr@2: the MHTTPDataSupplier for you. If you have all the data available, williamr@2: return its length in OverallDataSize, and pass back all the data williamr@2: from GetNextDataPart, returning ETrue to indicate that this is the williamr@2: last part. williamr@2: williamr@2: If you don't want to form all the data at once, but know how much williamr@2: you'll eventualy have, return the total length from williamr@2: OverallDataSize. When GetNextDataPart is first called, return the williamr@2: first part. If GetNextDataPart is called again before ReleaseData, williamr@2: you should still return the first part. Only when ReleaseData is williamr@2: called should you move to the second part. If you don't know the williamr@2: total size of the data, the procedure is the same but you should williamr@2: return KErrNotFound from OverallDataSize. williamr@2: williamr@2: When the next part is available, clients should call williamr@2: RHTTPTransaction::NotifyNewRequestBodyPartL to inform HTTP that williamr@2: the new data is available. They can do this from ReleaseData if williamr@2: more data is instantly available, or in some applications they may williamr@2: need to call it some time later when the next part has been williamr@2: assembled. williamr@2: williamr@2: Filter writers should note that the MHTTPDataSupplier interface is williamr@2: designed to be used by 1 client, as 1 component needs to know when williamr@2: to call ReleaseData(). However, filters can be written to williamr@2: transform the data in some way. For instance, a filter could be williamr@2: written to automaticaly handle a particular content encoding. When williamr@2: this filter first receives a GotResponseBodyData, it should take a williamr@2: copy of the response's body and replace the body with a williamr@2: MHTTPDataSupplier supplied by the filter. The filter should then williamr@2: receive the data from HTTP via the saved data supplier and give it williamr@2: to the client via its own data supplier. williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: { williamr@2: public: williamr@2: /** Obtain a data part from the supplier. The data is guaranteed williamr@2: to survive until a call is made to ReleaseData(). williamr@2: @param aDataPart - the data part williamr@2: @return ETrue if this is the last part. EFalse otherwise */ williamr@2: //##ModelId=3C4C187A0026 williamr@2: virtual TBool GetNextDataPart(TPtrC8& aDataPart) = 0; williamr@2: williamr@2: /** Release the current data part being held at the data williamr@2: supplier. This call indicates to the supplier that the part williamr@2: is no longer needed, and another one can be supplied, if williamr@2: appropriate. */ williamr@2: //##ModelId=3C4C187A0025 williamr@2: virtual void ReleaseData() = 0; williamr@2: williamr@2: /** Obtain the overall size of the data being supplied, if known williamr@2: to the supplier. Where a body of data is supplied in several williamr@2: parts this size will be the sum of all the part sizes. If williamr@2: the size is not known, KErrNotFound is returned; in this case williamr@2: the client must use the return code of GetNextDataPart to find williamr@2: out when the data is complete. williamr@2: williamr@2: @return A size in bytes, or KErrNotFound if the size is not known. */ williamr@2: //##ModelId=3C4C187A001D williamr@2: virtual TInt OverallDataSize() = 0; williamr@2: williamr@2: /** Reset the data supplier. This indicates to the data supplier that it should williamr@2: return to the first part of the data. This could be used in a situation where williamr@2: the data consumer has encountered an error and needs the data to be supplied williamr@2: afresh. Even if the last part has been supplied (i.e. GetNextDataPart has williamr@2: returned ETrue), the data supplier should reset to the first part. williamr@2: williamr@2: If the supplier cannot reset it should return an error code; otherwise it should williamr@2: return KErrNone, where the reset will be assumed to have succeeded*/ williamr@2: //##ModelId=3C4C187A001C williamr@2: virtual TInt Reset() = 0; williamr@2: williamr@2: private: williamr@2: // Some reserved methods for future expansion (e.g. better support williamr@2: // for ZCD) williamr@2: //##ModelId=3C4C187A001B williamr@2: inline virtual void MHDS_Reserved1(); williamr@2: //##ModelId=3C4C187A0012 williamr@2: inline virtual void MHDS_Reserved2(); williamr@2: //##ModelId=3C4C187A0011 williamr@2: inline virtual void MHDS_Reserved3(); williamr@2: }; williamr@2: williamr@2: inline void MHTTPDataSupplier::MHDS_Reserved1() williamr@2: {} williamr@2: williamr@2: inline void MHTTPDataSupplier::MHDS_Reserved2() williamr@2: {} williamr@2: williamr@2: inline void MHTTPDataSupplier::MHDS_Reserved3() williamr@2: {} williamr@2: williamr@2: #endif // __MHTTPDATASUPPLIER_H__