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 "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
18 @warning : This file contains Rose Model ID comments - please do not delete
21 #ifndef __RHTTPHEADERS_H__
22 #define __RHTTPHEADERS_H__
25 #include <http/thttphdrfielditer.h>
26 #include <http/thttphdrval.h>
29 //##ModelId=3C4C1880001A
32 The collection of headers (or more correctly, header fields)
33 associated with a message. Header (fields) can be created, read and
34 modified. They may be composed of several parts (by repeated
35 invocations of API methods, see below) and may be assigned one or
36 more parameters. Individual field parts and parameters take
37 values described using THTTPHdrVal.
45 /** Default constructor
47 //##ModelId=3C4C18800088
48 inline RHTTPHeaders();
51 Methods for reading data.
54 /** Obtain the number of parts in the named header field's value,
55 Simple headers are created with a single part following one
56 call to SetFieldL. Subsequent calls to SetFieldL create
57 additional parts if the field exists already.
59 @param aFieldName The header name
60 @return The number of parts, or zero if the field does not exist. */
61 //##ModelId=3C4C18800081
62 IMPORT_C TInt FieldPartsL(RStringF aFieldName) const;
64 /** Obtain the named header field's value. The index
65 of a part within the field must be specified. Parts are indexed
66 from 0 and fields with only one part return the entire field for index 0
67 @param aFieldName The header name
68 @param aPartIdx The index of the part
69 @param aHeaderValue The header field value
70 @return An error condition. Returns KErrNotFound if there is not a field with the
73 //##ModelId=3C4C18800079
74 IMPORT_C TInt GetField(RStringF aFieldName,
75 TInt aPartIdx, THTTPHdrVal& aHeaderValue) const;
77 /** Obtain an Raw representation of the named header
78 field's value. Note that general client use of this method is
79 strongly discouraged since it exposes the Raw representation of particular headers.
80 However it may be needed for some cases where received headers could not be
81 decoded by HTTP. It will normally be used internally when
82 preparing header data to be transmitted with a request.
83 Note that this API may not return the field values for all the headers.
84 @param aFieldName The field name, e.g, 'Content-Type'
85 @param aRawFieldData The field's data content, in an appropriate Raw form
86 @return An error condition. Returns KErrNotFound if there is not a field with the
89 //##ModelId=3C4C18800076
90 IMPORT_C TInt GetRawField(RStringF aFieldName,
91 TPtrC8& aRawFieldData) const;
93 IMPORT_C void GetRawFieldL(RStringF aFieldName, TPtrC8& aRawFieldData) const;
95 /** Obtain the value of a named parameter, associated with the
96 named header field. An optional index to a part within the
97 header field may be supplied, if not it is assumed that it is
99 @param aFieldName The header name
100 @param aParamName The parameter name
101 @param aReturn The returned value. Note that this
102 must be Copy()d by the caller, if it wants to keep the value.
103 @param aPartIdx The optional index of the part
104 @return An error condition. Returns KErrNotFound if there is not a field with the
105 specifed field name */
106 //##ModelId=3C4C1880006C
107 IMPORT_C TInt GetParam(RStringF aFieldName,
109 THTTPHdrVal& aReturn,
110 TInt aPartIdx = 0) const;
112 /** Access the fields within this header collection, via an
113 iterator. Each application of the iterator returns the name
114 of the next field type. This may then be accessed via
115 RHTTPHeaders methods.
116 @return The iterator. */
117 //##ModelId=3C4C1880006B
118 IMPORT_C THTTPHdrFieldIter Fields() const;
122 Methods for writing data.
125 /** Set a named field in the header. On the first instance that
126 this API method is used for a given field name, the first will
127 be created. On subsequent calls, the same field will be
128 extended to have several parts, with a new part created to
129 hold the supplied value.
130 @param aFieldName The field name, e.g, 'Content-Type'
131 @param aFieldValue The field value, e.g. 'text/html' */
132 //##ModelId=3C4C18800060
133 IMPORT_C void SetFieldL(RStringF aFieldName, THTTPHdrVal aFieldValue);
134 IMPORT_C TInt SetField(RStringF aFieldName, THTTPHdrVal aFieldValue);
136 /** Set a named field in the header, and associate with it the
137 supplied parameter. If the field doesn't already exist it will
138 be created along with a parameter; if it does exist, then a
139 new part will be created along with the parameter.
140 @param aFieldName The field name, e.g. 'Accept'
141 @param aFieldValue The field value. e.g. 'text/plain'
142 @param aParamName The parameter name, e.g. 'q'
143 @param aParamValue The parameter value, e.g. '0.3' */
144 //##ModelId=3C4C18800063
145 IMPORT_C void SetFieldL(RStringF aFieldName, THTTPHdrVal aFieldValue,
146 RStringF aParamName, THTTPHdrVal aParamValue);
147 IMPORT_C TInt SetField(RStringF aFieldName, THTTPHdrVal aFieldValue,
148 RStringF aParamName, THTTPHdrVal aParamValue);
149 /** Set a parameter in an existing header.
150 @param aFieldName The field name, e.g. 'Accept'
151 @param aPartIdx The part of the header to add the parameter to
152 @param aParamName The parameter name, e.g. 'q'
153 @param aParamValue The parameter value, e.g. '0.3'
154 @leave KErrNotFoud if the field, or the part within the field doesn't exist
156 //##ModelId=3C4C18800058
157 IMPORT_C void SetParamL(RStringF aFieldName, RStringF aParamName, THTTPHdrVal aParamValue, TInt aPartIdx);
159 /** Set a named field in the header to contain the supplied Raw header
160 data. If the header already exists then a LF and the new data will be added to the existing data. This is used to
161 indicate that there are multiple instances of this header
164 Note that general client use of this method is strongly
165 discouraged since it exposes the raw representation of particular headers.
166 However it may be needed for some cases where headers to be transmitted have no encoding known
167 to HTTP. It will normally be used internally when receiving data from a service provider.
168 @param aFieldName The field name, e.g, 'Content-Type'
169 @param aRawFieldData The field's data content, in a raw form
170 @param aFieldSeparator The header field separator
172 //##ModelId=3C4C1880004F
173 IMPORT_C void SetRawFieldL(RStringF aFieldName,
174 const TDesC8& aRawFieldData,
175 const TDesC8& aFieldSeparator);
177 IMPORT_C TInt SetRawField(RStringF aFieldName, const TDesC8& aRawFieldData, const TDesC8& aFieldSeparator);
178 /** Remove, entirely, the named header field from the header
179 collection. All its parts and associated parameters (where
180 they exist) are also removed.
181 @param aFieldName The field name.
182 @return KErrNone if the removal is successful; KErrNotFound if
183 the field didn't exist within the headers. */
184 //##ModelId=3C4C1880004D
185 IMPORT_C TInt RemoveField(RStringF aFieldName);
187 /** Remove a single part of a header field. Just the part and any associated paramters are removed. If this
188 results in no parts being present in the header then it will also be removed
189 @param aFieldName The header name
190 @param aIndex The particular part of the field to be removed
191 @return KErrNone if the removal is sucessful; KErrNotFound if the header didn't exist. No exception is raised if
192 the particular value is not found as part of that header */
193 //##ModelId=3C4C18800043
194 IMPORT_C TInt RemoveFieldPart(RStringF aFieldName, TInt aIndex);
196 /** Remove all the fields of this header collection
198 //##ModelId=3C4C18800042
199 IMPORT_C void RemoveAllFields();
205 friend class CHeaders;
206 friend class CHttpClientTransaction;
207 friend class CHttpClientTransactionImpl;
208 //##ModelId=3C4C1880003A
209 CHeaders* iImplementation;
213 inline RHTTPHeaders::RHTTPHeaders()
214 : iImplementation(NULL)
219 #endif // __RHTTPHEADERS_H__