1 mhttpdatasupplier.h |
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__ |