inc/FNetHttpHttpStringEntity.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                FNetHttpHttpStringEntity.h
  20  * @brief               This is the header file for the %HttpStringEntity class.
  21  *
  22  * This header file contains the declarations of the %HttpStringEntity class.
  23  */
  24
  25 #ifndef _FNET_HTTP_HTTP_STRING_ENTITY_H_
  26 #define _FNET_HTTP_HTTP_STRING_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 _HttpStringEntityImpl;
  45
  46 /**
  47  * @class       HttpStringEntity
  48  * @brief       This class represents a http body for the text content.
  49  *
  50  * @since 2.0
  51  *
  52  * The %HttpStringEntity class represents a http body for the text content.
  53  *
  54  * The following example demonstrates how to use the %HttpStringEntity class to send the content for text to the server using this class.
  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     TestHttpStringEntity(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         HttpStringEntity* pHttpStringEntity = new HttpStringEntity();
  85         pHttpStringEntity->Construct(L"test content body");
  86
  87         r = pRequest->SetEntity(*pHttpStringEntity);
  88
  89         // Sends the HttpTransaction.
  90         r = pTransaction->Submit();
  91     }
  92
  93  * @endcode
  94  */
  95
  96 class _OSP_EXPORT_ HttpStringEntity
  97         : public Tizen::Base::Object
  98         , public IHttpEntity
  99 {
 100
 101 public:
 102         /**
 103          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 104          *
 105          * @since       2.0
 106          *
 107          * @remarks             After creating an instance of this class, the Construct() method
 108          *              must be called explicitly to initialize this instance.
 109          */
 110         HttpStringEntity(void);
 111
 112         /**
 113          * This destructor overrides Tizen::Base::Object::~Object().
 114          *
 115          * @since 2.0
 116          */
 117         virtual ~HttpStringEntity(void);
 118
 119         /**
 120          * Initializes this instance of %HttpStringEntity with the default content type and character set.
 121          *
 122          * @since       2.0
 123          *
 124          * @return              An error code
 125          * @param[in]   text                                            The text of the body
 126          * @exception   E_SUCCESS                                       The method is successful.
 127          * @exception   E_INVALID_ENCODING_RANGE    The specified @c text contains code points that are outside the bounds of the default encoding standard ("ISO-8859-1").
 128          * @exception   E_SYSTEM                                        A system error has occurred.
 129          * @remarks             The default content type is "text/plain" and default charset is "ISO-8859-1".
 130          */
 131         result Construct(const Tizen::Base::String& text);
 132
 133         /**
 134          * Initializes this instance of %HttpStringEntity with the specified parameters.
 135          *
 136          * @since       2.0
 137          *
 138          * @return              An error code
 139          * @param[in]   text                                            The text of the body
 140          * @param[in]   contentType                                     The content type of @c text
 141          * @param[in]   charset                                         The character set of @c text
 142          * @param[in]   encoding                                        An encoding scheme for the specified @c text
 143          * @exception   E_SUCCESS                                       The method is successful.
 144          * @exception   E_INVALID_ARG                           A specified input parameter is invalid.
 145          * @exception   E_INVALID_ENCODING_RANGE    The specified @c text contains code points that are outside the bounds of @c encoding.
 146          * @exception   E_SYSTEM                                        A system error has occurred.
 147          */
 148         result Construct(const Tizen::Base::String& text, const Tizen::Base::String& contentType, const Tizen::Base::String& charset, const Tizen::Text::Encoding& encoding);
 149
 150
 151 private:
 152         /**
 153          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 154          *
 155          * @param[in]   rhs                     An instance of %HttpStringEntity
 156          */
 157         HttpStringEntity(const HttpStringEntity& rhs);
 158
 159         /**
 160          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 161          *
 162          * @param[in]   rhs                             An instance of %HttpStringEntity
 163          */
 164         HttpStringEntity& operator =(const HttpStringEntity& rhs);
 165
 166 public:
 167         /**
 168          * Gets the length of the request content.
 169          *
 170          * @since       2.0
 171          *
 172          * @return              The length of the content, @n
 173          *                              else @c -1 if the content length is unknown
 174          */
 175         virtual long long GetContentLength(void) const;
 176
 177         /**
 178          * Gets the type of the request content.
 179          *
 180          * @since       2.0
 181          *
 182          * @return              The type of the content
 183          */
 184         virtual Tizen::Base::String GetContentType(void) const;
 185
 186 protected:
 187         /**
 188          * Checks whether the next data exists.
 189          *
 190          * @since       2.0
 191          *
 192          * @return              @c true if the next data exists, @n
 193          *                              else @c false
 194          * @exception   E_SUCCESS                               The method is successful.
 195          * @exception   E_INVALID_STATE                 The method invoked is invalid.
 196          * @exception   E_SYSTEM                                A system error has occurred.
 197          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 198          */
 199         virtual bool HasNextData(void);
 200
 201         /**
 202          * Gets the next data.
 203          *
 204          * @since       2.0
 205          *
 206          * @return              The buffer to be read
 207          * @param[in]   recommendedSize                 The recommended size of the data to send
 208          * @exception   E_SUCCESS                               The method is successful.
 209          * @exception   E_INVALID_STATE                 The method invoked is invalid.
 210          * @exception   E_SYSTEM                                A system error has occurred.
 211          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 212          */
 213         virtual Tizen::Base::ByteBuffer* GetNextDataN(int recommendedSize);
 214
 215 private:
 216         friend class _HttpStringEntityImpl;
 217         _HttpStringEntityImpl* __pHttpStringEntityImpl;
 218
 219 }; // HttpStringEntity
 220
 221 } } } // Tizen::Net::Http
 222 #endif // _FNET_HTTP_HTTP_STRING_ENTITY_H_