inc/FNetHttpHttpHeader.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FNetHttpHttpHeader.h
  20  * @brief               This is the header file for the %HttpHeader class.
  21  *
  22  * This header file contains the declarations of the %HttpHeader class.
  23  */
  24
  25 #ifndef _FNET_HTTP_HTTP_HEADER_H_
  26 #define _FNET_HTTP_HTTP_HEADER_H_
  27
  28 #include <FBaseResult.h>
  29 #include <FBaseString.h>
  30 #include <FBaseColMultiHashMap.h>
  31 #include <FBaseColIEnumerator.h>
  32 #include <FNetHttpHttpTypes.h>
  33
  34 namespace Tizen { namespace Net { namespace Http
  35 {
  36 class _HttpHeaderImpl;
  37 /**
  38  * @class       HttpHeader
  39  * @brief       This class encapsulates the header fields associated with a message.
  40  *
  41  * @since       2.0
  42  *
  43  * The %HttpHeader class is a collection of header fields associated with an HTTP message. The header fields can be added, read, modified, and
  44  *      removed. Also, each field can have multiple values. This class provides easy access to the header.
  45  *
  46  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/http_connectivity.htm">HTTP Guide</a>.
  47  */
  48
  49 class _OSP_EXPORT_ HttpHeader
  50         : public Tizen::Base::Object
  51 {
  52
  53 public:
  54         /**
  55          * This is the default constructor for this class.
  56          *
  57          * @since           2.0
  58          *
  59          * @exception           E_SUCCESS                               The method is successful.
  60          * @exception           E_OUT_OF_MEMORY                 The memory is insufficient.
  61          * @remarks             The specific error code can be accessed using the GetLastResult() method.
  62          */
  63         HttpHeader(void);
  64
  65         /**
  66          * Initializes an instance of %HttpHeader with the values of the specified instance.
  67          *
  68          * @since       2.0
  69          *
  70          * @param[in]   pHeader                                 An instance of %HttpHeader
  71          * @exception   E_SUCCESS                               The method is successful.
  72          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.
  73          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
  74          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
  75          * @remarks             The parameter @c pHeader can be @c null.
  76          *                              The specific error code can be accessed using the GetLastResult() method.
  77          */
  78         HttpHeader(const HttpHeader* pHeader);
  79
  80         /**
  81          * This destructor overrides Tizen::Base::Object::~Object().
  82          *
  83          * @since       2.0
  84          */
  85         virtual ~HttpHeader(void);
  86
  87 public:
  88         /**
  89          * Adds a named field, which is a <@c fieldName, @c fieldValue> pair, to the current instance of %HttpHeader.
  90          *
  91          * @since       2.0
  92          *
  93          * @return              An error code
  94          * @param[in]   fieldName                               A field name
  95          * @param[in]   fieldValue                              A field value
  96          * @exception   E_SUCCESS                               The method is successful.
  97          * @exception   E_INVALID_ARG                   The specified @c fieldName is an empty string.
  98          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
  99          * @exception   E_OBJ_ALREADY_EXIST             The specified @c fieldName already exists. @n
 100          *                                                                              The <@c fieldName, @c fieldValue> pair already exists.
 101          * @remarks             The field is created on the first instance when this method is used for a particular field name.
 102          *                              On subsequent calls, the same field is extended to have several parts, with a new part created to hold the supplied value.
 103          *                              If you need to submit a request in the chunked mode, you need to explicitly add the header field named
 104          *                              "Transfer-Encoding" with the value @c chunked. Otherwise, the non-chunked mode is used as the default value.
 105          * @see                 RemoveField()
 106          */
 107         result AddField(const Tizen::Base::String& fieldName, const Tizen::Base::String& fieldValue);
 108
 109         /**
 110          * Removes all the fields with the specified field name.
 111          *
 112          * @since       2.0
 113          *
 114          * @return              An error code
 115          * @param[in]   fieldName                               The field name to remove
 116          * @exception   E_SUCCESS                               The method is successful.
 117          * @exception   E_INVALID_ARG                   The specified @c fieldName is an empty string.
 118          * @exception   E_OBJ_NOT_FOUND                 The specified @c fieldName is not found in the current instance of %HttpHeader. @n
 119          *                                                                              The header field with the specified @c fieldName is not found.
 120          * @see                         AddField()
 121          */
 122         result RemoveField(const Tizen::Base::String& fieldName);
 123
 124         /**
 125          * Removes only the specified <@c fieldName, @c fieldValue> pair from the current instance of %HttpHeader.
 126          *
 127          * @since       2.0
 128          *
 129          * @return              An error code
 130          * @param[in]   fieldName                               The field name to remove
 131          * @param[in]   fieldValue                              The field value to remove with the specified @c fieldName
 132          * @exception   E_SUCCESS                               The method is successful.
 133          * @exception   E_INVALID_ARG                   The specified @c fieldName is an empty string.
 134          * @exception   E_OBJ_NOT_FOUND                 The specified @c fieldName is not found in the current instance of %HttpHeader. @n
 135          *                                              The header field with the specified field name and field value is not found.
 136          * @see                         AddField()
 137          */
 138         result RemoveField(const Tizen::Base::String& fieldName, const Tizen::Base::String& fieldValue);
 139
 140         /**
 141          * Removes all the fields of the current instance of %HttpHeader.
 142          *
 143          * @since       2.0
 144          */
 145         void RemoveAll(void);
 146
 147         /**
 148          * Gets a raw header string.
 149          *
 150          * @since           2.0
 151          *
 152          * @return                      A raw header string
 153          * @exception           E_SUCCESS                               The method is successful.
 154          * @exception           E_OUT_OF_MEMORY                 The memory is insufficient.
 155          * @exception           E_INVALID_HEADER                This header object does not contain any header field.
 156          * @exception           E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.
 157          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 158          */
 159         Tizen::Base::String* GetRawHeaderN(void) const;
 160
 161         /**
 162          * Gets a list of all the field names in the current instance of %HttpHeader.
 163          *
 164          * @since           2.0
 165          *
 166          * @return                      A list that contains all the field names as string values
 167          * @exception           E_SUCCESS                               The method is successful.
 168          * @exception           E_OUT_OF_MEMORY                 The memory is insufficient.
 169          * @exception           E_INVALID_HEADER                This header object does not contain any header field.
 170          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 171          */
 172         Tizen::Base::Collection::IList* GetFieldNamesN(void) const;
 173
 174         /**
 175          * Gets the field values corresponding to the specified field name.
 176          *
 177          * @since       2.0
 178          *
 179          * @return              An enumerator containing all the string values of the specified field name
 180          * @param[in]   fieldName                               A field name
 181          * @exception   E_SUCCESS                               The method is successful.
 182          * @exception   E_INVALID_ARG                   The specified @c fieldName is an empty string.
 183          * @exception   E_OBJ_NOT_FOUND                 The specified @c fieldName is not found in the current instance of %HttpHeader. @n
 184          *                                                                              The header field with the specified @c fieldName is not found.
 185          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 186          */
 187         Tizen::Base::Collection::IEnumerator* GetFieldValuesN(const Tizen::Base::String& fieldName) const;
 188
 189 private:
 190         /**
 191          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 192          *
 193          * @param[in]   rhs   An instance of %HttpHeader
 194          */
 195         HttpHeader(const HttpHeader& rhs);
 196
 197         /**
 198          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 199          *
 200          * @since       2.0
 201          *
 202          * @param[in]   rhs                     An instance of %HttpHeader
 203          */
 204         HttpHeader& operator =(const HttpHeader& rhs);
 205
 206 private:
 207         friend class _HttpHeaderImpl;
 208         _HttpHeaderImpl* __pHttpHeaderImpl;
 209
 210 }; // HttpHeader
 211
 212 } } } //Tizen::Net::Http
 213 #endif // _FNET_HTTP_HTTP_HEADER_H_