inc/FNetHttpHttpUrlEncodedEntity.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                FNetHttpHttpUrlEncodedEntity.h
  20  * @brief               This is the header file for the %HttpUrlEncodedEntity class.
  21  *
  22  * This header file contains the declarations of the %HttpUrlEncodedEntity class.
  23  */
  24
  25 #ifndef _FNET_HTTP_HTTP_URL_ENCODED_ENTITY_H_
  26 #define _FNET_HTTP_HTTP_URL_ENCODED_ENTITY_H_
  27
  28 #include <FNetHttpHttpTypes.h>
  29 #include <FNetHttpIHttpEntity.h>
  30
  31 namespace Tizen { namespace Base
  32 {
  33 class String;
  34 class ByteBuffer;
  35 } }
  36
  37 namespace Tizen { namespace Text
  38 {
  39 class Encoding;
  40 } }
  41
  42 namespace Tizen { namespace Net { namespace Http
  43 {
  44 class _HttpUrlEncodedEntityImpl;
  45
  46 /**
  47  * @class       HttpUrlEncodedEntity
  48  * @brief       This class represents an http body for urlencoded pairs (name and value).
  49  *
  50  * @since 2.0
  51  *
  52  * The %HttpUrlEncodedEntity class represents an http body for urlencoded pairs (name and value).
  53  *
  54  * The following example demonstrates how to use the %HttpUrlEncodedEntity class to send content for urlencoded pairs to the server.
  55  *
  56  * @code
  57
  58     #include <FBase.h>
  59     #include <FNet.h>
  60
  61     using namespace Tizen::Base;
  62     using namespace Tizen::Net::Http;
  63
  64     void
  65     TestHttpUrlEncodedEntity(void)
  66     {
  67         result r = E_SUCCESS;
  68
  69         HttpSession* pSession = null;
  70         HttpTransaction* pTransaction = null;
  71         HttpRequest* pRequest = null;
  72         String hostAddr(L"http://www.tizen.org");
  73
  74         pSession = new HttpSession();
  75         r = pSession->Construct(NET_HTTP_SESSION_MODE_NORMAL, null, hostAddr, null);
  76
  77         pTransaction = pSession->OpenTransactionN();
  78         r = pTransaction->AddHttpTransactionListener(*this);
  79
  80         pRequest = const_cast<HttpRequest*>(pTransaction->GetRequest());
  81         r = pRequest->SetUri(L"http://www.tizen.org/test");
  82         r = pRequest->SetMethod(NET_HTTP_METHOD_POST);
  83
  84         HttpUrlEncodedEntity* pHttpUrlEncodedEntity = new HttpUrlEncodedEntity();
  85         r = pHttpUrlEncodedEntity->Construct();
  86
  87         r = pHttpUrlEncodedEntity->AddParameter(L"name1", L"value1");
  88         r = pHttpUrlEncodedEntity->AddParameter(L"name2", L"value2");
  89
  90         r = pRequest->SetEntity(*pHttpUrlEncodedEntity);
  91
  92         // Sends the HttpTransaction.
  93         r = pTransaction->Submit();
  94     }
  95
  96  * @endcode
  97  */
  98
  99 class _OSP_EXPORT_ HttpUrlEncodedEntity
 100         : public Tizen::Base::Object
 101         , public IHttpEntity
 102 {
 103
 104 public:
 105    /**
 106         * The object is not fully constructed after this constructor is called. @n
 107         * For full construction, the Construct() method must be called right after calling this constructor.
 108         *
 109         * @since       2.0
 110         *
 111         * @remarks              After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
 112         */
 113         HttpUrlEncodedEntity(void);
 114
 115    /**
 116         * This destructor overrides Tizen::Base::Object::~Object().
 117         *
 118         * @since 2.0
 119         */
 120         virtual ~HttpUrlEncodedEntity(void);
 121
 122    /**
 123         * Initializes this instance of %HttpUrlEncodedEntity.
 124         *
 125         * @since       2.0
 126         *
 127         * @return               An error code
 128         * @exception    E_SUCCESS                       The method is successful.
 129         * @exception    E_SYSTEM                        A system error has occurred.
 130         * @remarks              The default content type is "application/x-www-form-urlencoded" and default character set is "ISO-8859-1".
 131         */
 132         result Construct(void);
 133
 134    /**
 135         * Initializes this instance of %HttpUrlEncodedEntity with the specified parameters.
 136         *
 137         * @since       2.0
 138         *
 139         * @return               An error code
 140         * @param[in]    charset                                         The character set of the entity
 141         * @param[in]    encoding                                        The encoding scheme for the parameters
 142         * @exception    E_SUCCESS                                       The method is successful.
 143         * @exception    E_SYSTEM                                        A system error has occurred.
 144         * @remarks              The default content type is "application/x-www-form-urlencoded".
 145         */
 146         result Construct(const Tizen::Base::String& charset, const Tizen::Text::Encoding& encoding);
 147
 148 private:
 149    /**
 150         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 151         *
 152         * @param[in]    rhs                     An instance of %HttpUrlEncodedEntity
 153         */
 154         HttpUrlEncodedEntity(const HttpUrlEncodedEntity& rhs);
 155
 156    /**
 157         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 158         *
 159         * @param[in]    rhs                             An instance of %HttpUrlEncodedEntity
 160         */
 161         HttpUrlEncodedEntity& operator =(const HttpUrlEncodedEntity& rhs);
 162
 163 public:
 164    /**
 165         * Gets the length of the request content.
 166         *
 167         * @since       2.0
 168         *
 169         * @return               The length of the content, @n
 170         *                               else @c -1 if the content length is unknown
 171         */
 172         virtual long long GetContentLength(void) const;
 173
 174    /**
 175         * Gets the type of the request content.
 176         *
 177         * @since       2.0
 178         *
 179         * @return               The type of the content
 180         */
 181         virtual Tizen::Base::String GetContentType(void) const;
 182
 183    /**
 184         * Adds the form data (name and value pairs) to %HttpUrlEncodedEntity.
 185         *
 186         * @since       2.0
 187         *
 188         * @return               An error code
 189         * @param[in]    name                                            The name of the urlencoded entity
 190         * @param[in]    value                                           The value of the urlencoded entity
 191         * @exception    E_SUCCESS                                       The method is successful.
 192         * @exception    E_INVALID_ARG                           A specified input parameter is invalid.
 193         * @exception    E_INVALID_ENCODING_RANGE    The specified @c name or @c value contains code points that are outside the bounds of the specified @c encoding.
 194         * @exception    E_SYSTEM                                        A system error has occurred.
 195         */
 196         result AddParameter(const Tizen::Base::String& name, const Tizen::Base::String& value);
 197
 198 protected:
 199    /**
 200         * Checks whether the next data exists.
 201         *
 202         * @since       2.0
 203         *
 204         * @return               @c true if the next data exists, @n
 205         *                               else @c false
 206         * @exception    E_SUCCESS                               The method is successful.
 207         * @exception   E_INVALID_STATE                  The method invoked is invalid.
 208         * @exception    E_SYSTEM                                A system error has occurred.
 209         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 210         */
 211         virtual bool HasNextData(void);
 212
 213    /**
 214         * Gets the next data.
 215         *
 216         * @since       2.0
 217         *
 218         * @return               The buffer to read
 219         * @param[in]    recommendedSize                 The recommended size of the data to send
 220         * @exception    E_SUCCESS                               The method is successful.
 221         * @exception    E_INVALID_STATE                 The method invoked is invalid.
 222         * @exception    E_SYSTEM                                A system error has occurred.
 223         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 224         */
 225         virtual Tizen::Base::ByteBuffer* GetNextDataN(int recommendedSize);
 226
 227 private:
 228         friend class _HttpUrlEncodedEntityImpl;
 229         _HttpUrlEncodedEntityImpl* __pHttpUrlEncodedEntityImpl;
 230
 231 }; // HttpUrlEncodedEntity
 232
 233 } } } // Tizen::Net::Http
 234 #endif // _FNET_HTTP_HTTP_URL_ENCODED_ENTITY_H_