1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/http/rhttpheaders.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,214 @@
1.4 +// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// 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
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +
1.20 +
1.21 +/**
1.22 + @file RHTTPHeaders.h
1.23 + @warning : This file contains Rose Model ID comments - please do not delete
1.24 +*/
1.25 +
1.26 +#ifndef __RHTTPHEADERS_H__
1.27 +#define __RHTTPHEADERS_H__
1.28 +
1.29 +// System includes
1.30 +#include <http/thttphdrfielditer.h>
1.31 +#include <http/thttphdrval.h>
1.32 +
1.33 +
1.34 +//##ModelId=3C4C1880001A
1.35 +class RHTTPHeaders
1.36 +/**
1.37 +The collection of headers (or more correctly, header fields)
1.38 +associated with a message. Header (fields) can be created, read and
1.39 +modified. They may be composed of several parts (by repeated
1.40 +invocations of API methods, see below) and may be assigned one or
1.41 +more parameters. Individual field parts and parameters take
1.42 +values described using THTTPHdrVal.
1.43 +@publishedAll
1.44 +@released
1.45 +@see RHTTPMessage
1.46 +@see THTTPHdrVal
1.47 +*/
1.48 + {
1.49 + public:
1.50 + /** Default constructor
1.51 + */
1.52 + //##ModelId=3C4C18800088
1.53 + inline RHTTPHeaders();
1.54 +
1.55 + /**Getter methods
1.56 + Methods for reading data.
1.57 + */
1.58 + //@{
1.59 + /** Obtain the number of parts in the named header field's value,
1.60 + Simple headers are created with a single part following one
1.61 + call to SetFieldL. Subsequent calls to SetFieldL create
1.62 + additional parts if the field exists already.
1.63 + @leave KErrNoMemory
1.64 + @param aFieldName The header name
1.65 + @return The number of parts, or zero if the field does not exist. */
1.66 + //##ModelId=3C4C18800081
1.67 + IMPORT_C TInt FieldPartsL(RStringF aFieldName) const;
1.68 +
1.69 + /** Obtain the named header field's value. The index
1.70 + of a part within the field must be specified. Parts are indexed
1.71 + from 0 and fields with only one part return the entire field for index 0
1.72 + @param aFieldName The header name
1.73 + @param aPartIdx The index of the part
1.74 + @param aHeaderValue The header field value
1.75 + @return An error condition. Returns KErrNotFound if there is not a field with the
1.76 + specifed field name
1.77 + */
1.78 + //##ModelId=3C4C18800079
1.79 + IMPORT_C TInt GetField(RStringF aFieldName,
1.80 + TInt aPartIdx, THTTPHdrVal& aHeaderValue) const;
1.81 +
1.82 + /** Obtain an Raw representation of the named header
1.83 + field's value. Note that general client use of this method is
1.84 + strongly discouraged since it exposes the Raw representation of particular headers.
1.85 + However it may be needed for some cases where received headers could not be
1.86 + decoded by HTTP. It will normally be used internally when
1.87 + preparing header data to be transmitted with a request.
1.88 + Note that this API may not return the field values for all the headers.
1.89 + @param aFieldName The field name, e.g, 'Content-Type'
1.90 + @param aRawFieldData The field's data content, in an appropriate Raw form
1.91 + @return An error condition. Returns KErrNotFound if there is not a field with the
1.92 + specifed field name
1.93 + */
1.94 + //##ModelId=3C4C18800076
1.95 + IMPORT_C TInt GetRawField(RStringF aFieldName,
1.96 + TPtrC8& aRawFieldData) const;
1.97 +
1.98 + /** Obtain the value of a named parameter, associated with the
1.99 + named header field. An optional index to a part within the
1.100 + header field may be supplied, if not it is assumed that it is
1.101 + the first part.
1.102 + @param aFieldName The header name
1.103 + @param aParamName The parameter name
1.104 + @param aReturn The returned value. Note that this
1.105 + must be Copy()d by the caller, if it wants to keep the value.
1.106 + @param aPartIdx The optional index of the part
1.107 + @return An error condition. Returns KErrNotFound if there is not a field with the
1.108 + specifed field name */
1.109 + //##ModelId=3C4C1880006C
1.110 + IMPORT_C TInt GetParam(RStringF aFieldName,
1.111 + RStringF aParamName,
1.112 + THTTPHdrVal& aReturn,
1.113 + TInt aPartIdx = 0) const;
1.114 +
1.115 + /** Access the fields within this header collection, via an
1.116 + iterator. Each application of the iterator returns the name
1.117 + of the next field type. This may then be accessed via
1.118 + RHTTPHeaders methods.
1.119 + @return The iterator. */
1.120 + //##ModelId=3C4C1880006B
1.121 + IMPORT_C THTTPHdrFieldIter Fields() const;
1.122 + //@}
1.123 +
1.124 + /** Setter Methods
1.125 + Methods for writing data.
1.126 + */
1.127 + //@{
1.128 + /** Set a named field in the header. On the first instance that
1.129 + this API method is used for a given field name, the first will
1.130 + be created. On subsequent calls, the same field will be
1.131 + extended to have several parts, with a new part created to
1.132 + hold the supplied value.
1.133 + @param aFieldName The field name, e.g, 'Content-Type'
1.134 + @param aFieldValue The field value, e.g. 'text/html' */
1.135 + //##ModelId=3C4C18800060
1.136 + IMPORT_C void SetFieldL(RStringF aFieldName, THTTPHdrVal aFieldValue);
1.137 +
1.138 + /** Set a named field in the header, and associate with it the
1.139 + supplied parameter. If the field doesn't already exist it will
1.140 + be created along with a parameter; if it does exist, then a
1.141 + new part will be created along with the parameter.
1.142 + @param aFieldName The field name, e.g. 'Accept'
1.143 + @param aFieldValue The field value. e.g. 'text/plain'
1.144 + @param aParamName The parameter name, e.g. 'q'
1.145 + @param aParamValue The parameter value, e.g. '0.3' */
1.146 + //##ModelId=3C4C18800063
1.147 + IMPORT_C void SetFieldL(RStringF aFieldName, THTTPHdrVal aFieldValue,
1.148 + RStringF aParamName, THTTPHdrVal aParamValue);
1.149 +
1.150 + /** Set a parameter in an existing header.
1.151 + @param aFieldName The field name, e.g. 'Accept'
1.152 + @param aPartIdx The part of the header to add the parameter to
1.153 + @param aParamName The parameter name, e.g. 'q'
1.154 + @param aParamValue The parameter value, e.g. '0.3'
1.155 + @leave KErrNotFoud if the field, or the part within the field doesn't exist
1.156 + */
1.157 + //##ModelId=3C4C18800058
1.158 + IMPORT_C void SetParamL(RStringF aFieldName, RStringF aParamName, THTTPHdrVal aParamValue, TInt aPartIdx);
1.159 +
1.160 + /** Set a named field in the header to contain the supplied Raw header
1.161 + data. If the header already exists then a LF and the new data will be added to the existing data. This is used to
1.162 + indicate that there are multiple instances of this header
1.163 +
1.164 +
1.165 + Note that general client use of this method is strongly
1.166 + discouraged since it exposes the raw representation of particular headers.
1.167 + However it may be needed for some cases where headers to be transmitted have no encoding known
1.168 + to HTTP. It will normally be used internally when receiving data from a service provider.
1.169 + @param aFieldName The field name, e.g, 'Content-Type'
1.170 + @param aRawFieldData The field's data content, in a raw form
1.171 + @param aFieldSeparator The header field separator
1.172 + */
1.173 + //##ModelId=3C4C1880004F
1.174 + IMPORT_C void SetRawFieldL(RStringF aFieldName,
1.175 + const TDesC8& aRawFieldData,
1.176 + const TDesC8& aFieldSeparator);
1.177 +
1.178 + /** Remove, entirely, the named header field from the header
1.179 + collection. All its parts and associated parameters (where
1.180 + they exist) are also removed.
1.181 + @param aFieldName The field name.
1.182 + @return KErrNone if the removal is successful; KErrNotFound if
1.183 + the field didn't exist within the headers. */
1.184 + //##ModelId=3C4C1880004D
1.185 + IMPORT_C TInt RemoveField(RStringF aFieldName);
1.186 +
1.187 + /** Remove a single part of a header field. Just the part and any associated paramters are removed. If this
1.188 + results in no parts being present in the header then it will also be removed
1.189 + @param aFieldName The header name
1.190 + @param aIndex The particular part of the field to be removed
1.191 + @return KErrNone if the removal is sucessful; KErrNotFound if the header didn't exist. No exception is raised if
1.192 + the particular value is not found as part of that header */
1.193 + //##ModelId=3C4C18800043
1.194 + IMPORT_C TInt RemoveFieldPart(RStringF aFieldName, TInt aIndex);
1.195 +
1.196 + /** Remove all the fields of this header collection
1.197 + */
1.198 + //##ModelId=3C4C18800042
1.199 + IMPORT_C void RemoveAllFields();
1.200 +
1.201 + //@}
1.202 +
1.203 +
1.204 +private:
1.205 + friend class CHeaders;
1.206 + //##ModelId=3C4C1880003A
1.207 + CHeaders* iImplementation;
1.208 + };
1.209 +
1.210 +
1.211 +inline RHTTPHeaders::RHTTPHeaders()
1.212 + : iImplementation(NULL)
1.213 + {
1.214 + }
1.215 +
1.216 +
1.217 +#endif // __RHTTPHEADERS_H__