epoc32/include/http/mhttpdatasupplier.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     1 // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
     2 // All rights reserved.
     3 // This component and the accompanying materials are made available
     4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
     5 // which accompanies this distribution, and is available
     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
     7 //
     8 // Initial Contributors:
     9 // Nokia Corporation - initial contribution.
    10 //
    11 // Contributors:
    12 //
    13 // Description:
    14 //
    15 
    16 
    17 
    18 /**
    19  @file MHTTPDataSupplier.h
    20  @warning : This file contains Rose Model ID comments - please do not delete
    21 */
    22 
    23 #ifndef	__MHTTPDATASUPPLIER_H__
    24 #define	__MHTTPDATASUPPLIER_H__
    25 
    26 // System includes
    27 #include <e32base.h>
    28 
    29 
    30 //##ModelId=3C4C187903E5
    31 class MHTTPDataSupplier
    32 /** 
    33 A data supplier - This class is used to deliver the response data
    34 to the client, and is also used by the client to supply request
    35 body data to HTTP in POST transactions. Data is supplied in a
    36 number of parts. When a part is available it can be retreived
    37 with GetNextDataPart. The returned descriptor will remain valid until
    38 ReleaseData is called. 
    39 
    40 To use this class to supply POST data, you have a number of
    41 options. If the post data needs to be URL Form encoded, you should
    42 use CHTTPFormEncoder, which will do the encoding and interface to
    43 the MHTTPDataSupplier for you. If you have all the data available,
    44 return its length in OverallDataSize, and pass back all the data
    45 from GetNextDataPart, returning ETrue to indicate that this is the
    46 last part. 
    47 
    48 If you don't want to form all the data at once, but know how much
    49 you'll eventualy have, return the total length from
    50 OverallDataSize. When GetNextDataPart is first called, return the
    51 first part. If GetNextDataPart is called again before ReleaseData,
    52 you should still return the first part. Only when ReleaseData is
    53 called should you move to the second part. If you don't know the
    54 total size of the data, the procedure is the same but you should
    55 return KErrNotFound from OverallDataSize.
    56 
    57 When the next part is available, clients should call
    58 RHTTPTransaction::NotifyNewRequestBodyPartL to inform HTTP that
    59 the new data is available. They can do this from ReleaseData if
    60 more data is instantly available, or in some applications they may
    61 need to call it some time later when the next part has been
    62 assembled.
    63 
    64 Filter writers should note that the MHTTPDataSupplier interface is
    65 designed to be used by 1 client, as 1 component needs to know when
    66 to call ReleaseData(). However, filters can be written to
    67 transform the data in some way. For instance, a filter could be
    68 written to automaticaly handle a particular content encoding. When
    69 this filter first receives a GotResponseBodyData, it should take a
    70 copy of the response's body and replace the body with a
    71 MHTTPDataSupplier supplied by the filter. The filter should then
    72 receive the data from HTTP via the saved data supplier and give it
    73 to the client via its own data supplier.
    74 @publishedAll
    75 @released
    76 */
    77 	{
    78  public:
    79 	/** Obtain a data part from the supplier.  The data is guaranteed
    80 		to survive until a call is made to ReleaseData().
    81 		@param aDataPart - the data part
    82 		@return ETrue if this is the last part. EFalse otherwise */
    83 	//##ModelId=3C4C187A0026
    84 	 virtual TBool GetNextDataPart(TPtrC8& aDataPart) = 0;
    85 
    86 	/** Release the current data part being held at the data
    87 		supplier.  This call indicates to the supplier that the part
    88 		is no longer needed, and another one can be supplied, if
    89 		appropriate.  */
    90 	//##ModelId=3C4C187A0025
    91 	virtual void ReleaseData() = 0;
    92 
    93 	/** Obtain the overall size of the data being supplied, if known
    94 		to the supplier.  Where a body of data is supplied in several
    95 		parts this size will be the sum of all the part sizes. If
    96 		the size is not known, KErrNotFound is returned; in this case
    97 		the client must use the return code of GetNextDataPart to find
    98 		out when the data is complete.
    99 
   100 		@return A size in bytes, or KErrNotFound if the size is not known.  */
   101 	//##ModelId=3C4C187A001D
   102 	virtual TInt OverallDataSize() = 0;
   103 
   104 	/** Reset the data supplier.  This indicates to the data supplier that it should
   105 		return to the first part of the data.  This could be used in a situation where
   106 		the data consumer has encountered an error and needs the data to be supplied
   107 		afresh.  Even if the last part has been supplied (i.e. GetNextDataPart has
   108 		returned ETrue), the data supplier should reset to the first part.
   109 	
   110 		If the supplier cannot reset it should return an error code; otherwise it should
   111 		return KErrNone, where the reset will be assumed to have succeeded*/
   112 	//##ModelId=3C4C187A001C
   113 	virtual TInt Reset() = 0;
   114 
   115 private:
   116 	// Some reserved methods for future expansion (e.g. better support
   117 	// for ZCD)
   118 	//##ModelId=3C4C187A001B
   119 	inline virtual void MHDS_Reserved1();
   120 	//##ModelId=3C4C187A0012
   121 	inline virtual void MHDS_Reserved2();
   122 	//##ModelId=3C4C187A0011
   123 	inline virtual void MHDS_Reserved3();
   124 	};
   125 
   126 inline void MHTTPDataSupplier::MHDS_Reserved1()
   127 	{}
   128 
   129 inline void MHTTPDataSupplier::MHDS_Reserved2()
   130 	{}
   131 
   132 inline void MHTTPDataSupplier::MHDS_Reserved3()
   133 	{}
   134 
   135 #endif // __MHTTPDATASUPPLIER_H__