inc/FNetHttpHttpMultipartEntity.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                FNetHttpHttpMultipartEntity.h
  20  * @brief               This is the header file for the %HttpMultipartEntity class.
  21  *
  22  * This header file contains the declarations of the %HttpMultipartEntity class.
  23  */
  24
  25 #ifndef _FNET_HTTP_HTTP_MULTIPART_ENTITY_H_
  26 #define _FNET_HTTP_HTTP_MULTIPART_ENTITY_H_
  27
  28 #include <FBase.h>
  29 #include <FText.h>
  30 #include <FNetHttpHttpTypes.h>
  31 #include <FNetHttpIHttpEntity.h>
  32
  33 namespace Tizen { namespace Net { namespace Http
  34 {
  35 class _HttpMultipartEntityImpl;
  36
  37 /**
  38  * @if OSPDEPREC
  39  * The constant for the default MIME type of the string part.
  40  *
  41  * @brief <i> [Deprecated] </i>
  42  * @deprecated  This object is provided only for backward compatibility and will be deleted in the near future.
  43  *                              Use HTTP_STRING_PART_DEFAULT_MIME_TYPE instead of this object.
  44  * @since       2.0
  45  * @endif
  46  */
  47 _OSP_EXPORT_ extern const Tizen::Base::String STRING_PART_DEFAULT_MIME_TYPE;
  48
  49 /**
  50  * @if OSPDEPREC
  51  * The constant for the default MIME type of the file part.
  52  *
  53  * @brief <i> [Deprecated] </i>
  54  * @deprecated  This object is provided only for backward compatibility and will be deleted in the near future.
  55   *                             Use HTTP_FILE_PART_DEFAULT_MIME_TYPE instead of this object.
  56  * @since       2.0
  57  * @endif
  58  */
  59 _OSP_EXPORT_ extern const Tizen::Base::String FILE_PART_DEFAULT_MIME_TYPE;
  60
  61 /**
  62  * The constant for the default MIME type of the string part ("text/plain").
  63  *
  64  * @since       2.0
  65  */
  66 _OSP_EXPORT_ extern const wchar_t HTTP_STRING_PART_DEFAULT_MIME_TYPE[];
  67
  68 /**
  69  * The constant for the default MIME type of the file part ("application/octet-stream").
  70  *
  71  * @since       2.0
  72  */
  73 _OSP_EXPORT_ extern const wchar_t HTTP_FILE_PART_DEFAULT_MIME_TYPE[];
  74
  75 /**
  76  * @class       HttpMultipartEntity
  77  * @brief       This class represents a multipart/form-data entity as defined in RFC 2388.
  78  *
  79  * @since 2.0
  80  *
  81  *  The %HttpMultipartEntity class represents a multipart/form-data entity as defined in RFC 2388.
  82  *  The multipart/form-data entity contains a series of parts.
  83  *
  84  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/http_connectivity.htm">HTTP Guide</a>.
  85  *
  86  * The following example demonstrates how to use the %HttpMultipartEntity class to upload the content to the server.
  87  *
  88  * @code
  89
  90     #include <FBase.h>
  91     #include <FNet.h>
  92
  93     using namespace Tizen::Base;
  94     using namespace Tizen::Net::Http;
  95
  96     void
  97     TestHttpMultipartEntity(void)
  98     {
  99         result r = E_SUCCESS;
 100         HttpSession* pSession = null;
 101         HttpTransaction* pTransaction = null;
 102         HttpRequest* pRequest = null;
 103         HttpMultipartEntity* pMultipartEntity = null;
 104         String hostAddr(L"http://www.tizen.org");
 105
 106         // Creates an HTTP session.
 107         pSession = new HttpSession();
 108         r = pSession->Construct(NET_HTTP_SESSION_MODE_NORMAL, null, hostAddr, null);
 109
 110         pTransaction = pSession->OpenTransactionN();
 111         r = pTransaction->AddHttpTransactionListener(*this);
 112         r = pTransaction->SetHttpProgressListener(*this);
 113
 114         pRequest = pTransaction->GetRequest();
 115         pRequest->SetMethod(NET_HTTP_METHOD_POST);
 116         r = pRequest->SetUri(L"http://www.tizen.org/test");
 117
 118         pMultipartEntity = new HttpMultipartEntity();
 119         r = pMultipartEntity->Construct();
 120
 121         r = pMultipartEntity->AddStringPart(L"title", L"Tizen logo");
 122         r = pMultipartEntity->AddStringPart(L"date", L"2010-12-25");
 123         r = pMultipartEntity->AddFilePart(L"upload", L"/Home/Tizen.jpg", L"Tizen.jpg", L"image/jpeg", L"ISO-8859-1");
 124
 125         r = pRequest->SetEntity(*pMultipartEntity);
 126         r = pTransaction->Submit();
 127     }
 128
 129  * @endcode
 130  */
 131
 132 class _OSP_EXPORT_ HttpMultipartEntity
 133         : public Tizen::Base::Object
 134         , public IHttpEntity
 135 {
 136
 137 public:
 138         /**
 139          * 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.
 140          *
 141          * @since       2.0
 142          *
 143          * @remarks             After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
 144          */
 145         HttpMultipartEntity(void);
 146
 147         /**
 148          * This destructor overrides Tizen::Base::Object::~Object().
 149          *
 150          * @since 2.0
 151          */
 152         virtual ~HttpMultipartEntity(void);
 153
 154         /**
 155          * Initializes this instance of %HttpMultipartEntity.
 156          *
 157          * @since       2.0
 158          *
 159          * @return              An error code
 160          * @exception   E_SUCCESS                       The method is successful.
 161          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 162          * @exception   E_SYSTEM                        A system error has occurred.
 163          */
 164         result Construct(void);
 165
 166         /**
 167          * Initializes this instance of %HttpMultipartEntity with the specified parameters.
 168          *
 169          * @since       2.0
 170          *
 171          * @return              An error code
 172          * @param[in]   boundary                        The boundary of multipart/form-data
 173          * @exception   E_SUCCESS                       The method is successful.
 174          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 175          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 176          * @exception   E_SYSTEM                        A system error has occurred.
 177          */
 178         result Construct(const Tizen::Base::String& boundary);
 179
 180 private:
 181         /**
 182          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 183          *
 184          * @param[in]   rhs             An instance of %HttpMultipartEntity
 185          */
 186         HttpMultipartEntity(const HttpMultipartEntity& rhs);
 187
 188         /**
 189          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 190          *
 191          * @param[in]   rhs                     An instance of %HttpMultipartEntity
 192          */
 193         HttpMultipartEntity& operator =(const HttpMultipartEntity& rhs);
 194
 195 public:
 196         /**
 197          * Gets the length of the request content.
 198          *
 199          * @since       2.0
 200          *
 201          * @return              The length of the content, @n
 202          *                              else @c -1 if the content length is unknown
 203          */
 204         virtual long long GetContentLength(void) const;
 205
 206         /**
 207          * Gets the type of the request content.
 208          *
 209          * @since       2.0
 210          *
 211          * @return              The type of the content
 212          */
 213         virtual Tizen::Base::String GetContentType(void) const;
 214
 215         /**
 216          * Adds the string part to %HttpMultipartEntity with the default MIME type and character set.
 217          *
 218          * @since       2.0
 219          *
 220          * @return              An error code
 221          * @param[in]   name                                            The name of the part
 222          * @param[in]   text                                            The text of the part @n
 223          *                                                                                      The value of @c text is encoded using the default character encoding standard ("ISO-8859-1").
 224          * @exception   E_SUCCESS                                       The method is successful.
 225          * @exception   E_INVALID_ARG                           A specified input parameter is invalid.
 226          * @exception   E_OUT_OF_MEMORY                         The memory is insufficient.
 227          * @exception   E_INVALID_ENCODING_RANGE    The @c text contains code points that are outside the bounds specified by @c encoding.
 228          * @exception   E_SYSTEM                                        A system error has occurred.
 229          * @remarks             The default MIME type is "text/plain".
 230          */
 231         result AddStringPart(const Tizen::Base::String& name, const Tizen::Base::String& text);
 232
 233         /**
 234          * Adds the string part to %HttpMultipartEntity.
 235          *
 236          * @since       2.0
 237          *
 238          * @return              An error code
 239          * @param[in]   name                                            The name of the part
 240          * @param[in]   text                                            The text of the part
 241          * @param[in]   mimeType                                        The MIME type of @c text
 242          * @param[in]   charset                                         The character set of @c text
 243          * @param[in]   encoding                                        An encoding scheme for the specified @c text
 244          * @exception   E_SUCCESS                                       The method is successful.
 245          * @exception   E_INVALID_ARG                           A specified input parameter is invalid.
 246          * @exception   E_OUT_OF_MEMORY                         The memory is insufficient.
 247          * @exception   E_INVALID_ENCODING_RANGE    The @c text contains code points that are outside the bounds specified by @c encoding.
 248          * @exception   E_SYSTEM                                        A system error has occurred.
 249          */
 250         result AddStringPart(const Tizen::Base::String& name, const Tizen::Base::String& text, const Tizen::Base::String& mimeType, const Tizen::Base::String& charset, const Tizen::Text::Encoding& encoding);
 251
 252         /**
 253          * Adds the file part to %HttpMultipartEntity with the default MIME type.
 254          *
 255          * @if OSPCOMPAT
 256          * @brief <i> [Compatibility] </i>
 257          * @endif
 258          * @since       2.0
 259          * @if OSPCOMPAT
 260          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 261          *                                      For more information, see @ref CompIoPathPage "here".
 262          * @endif
 263          *
 264          * @return              An error code
 265          * @param[in]   name                            The name of the part
 266          * @param[in]   filePath                        The path of the file to upload
 267          * @exception   E_SUCCESS                       The method is successful.
 268          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 269          * @exception   E_FILE_NOT_FOUND        The specified file cannot be found or accessed.
 270          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 271          * @exception   E_SYSTEM                        A system error has occurred.
 272          * @remarks             The default MIME type is "application/octet-stream".
 273          */
 274         result AddFilePart(const Tizen::Base::String& name, const Tizen::Base::String& filePath);
 275
 276         /**
 277          * Adds the file part to %HttpMultipartEntity.
 278          *
 279          * @if OSPCOMPAT
 280          * @brief <i> [Compatibility] </i>
 281          * @endif
 282          * @since       2.0
 283          * @if OSPCOMPAT
 284          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 285          *                                      For more information, see @ref CompIoPathPage "here".
 286          * @endif
 287          *
 288          * @return              An error code
 289          * @param[in]   name                            The name of the part
 290          * @param[in]   filePath                        The path of the file to upload
 291          * @param[in]   fileName                        The file name of the part
 292          * @param[in]   mimeType                        The MIME type of the content
 293          * @param[in]   charset                         The character set of the content
 294          * @exception   E_SUCCESS                       The method is successful.
 295          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 296          * @exception   E_FILE_NOT_FOUND        The specified file cannot be found or accessed.
 297          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 298          * @exception   E_SYSTEM                        A system error has occurred.
 299          */
 300         result AddFilePart(const Tizen::Base::String& name, const Tizen::Base::String& filePath, const Tizen::Base::String& fileName, const Tizen::Base::String& mimeType, const Tizen::Base::String& charset);
 301
 302         /**
 303          * Adds the binary part to %HttpMultipartEntity with the default MIME type.
 304          *
 305          * @since       2.0
 306          *
 307          * @return              An error code
 308          * @param[in]   name                            The name of the part
 309          * @param[in]   fileName                        The file name of the part
 310          * @param[in]   buffer                          The buffer of file to upload
 311          * @exception   E_SUCCESS                       The method is successful.
 312          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 313          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 314          * @exception   E_SYSTEM                        A system error has occurred.
 315          * @remarks             The default MIME-type is "application/octet-stream".
 316          */
 317         result AddFilePartByBuffer(const Tizen::Base::String& name, const Tizen::Base::String& fileName, const Tizen::Base::ByteBuffer& buffer);
 318
 319         /**
 320          * Adds the binary part to %HttpMultipartEntity.
 321          *
 322          * @since       2.0
 323          *
 324          * @return              An error code
 325          * @param[in]   name                            The name of the part
 326          * @param[in]   fileName                        The file name of the part
 327          * @param[in]   buffer                          The buffer of the file to upload
 328          * @param[in]   mimeType                        The MIME type of the content
 329          * @param[in]   charset                         The character set of the content
 330          * @exception   E_SUCCESS                       The method is successful.
 331          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 332          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 333          * @exception   E_SYSTEM                        A system error has occurred.
 334          */
 335         result AddFilePartByBuffer(const Tizen::Base::String& name, const Tizen::Base::String& fileName, const Tizen::Base::ByteBuffer& buffer, const Tizen::Base::String& mimeType, const Tizen::Base::String& charset);
 336
 337 protected:
 338         /**
 339          * Checks whether the next data exists.
 340          *
 341          * @since       2.0
 342          *
 343          * @return              @c true if the next data exists, @n
 344          *                              else @c false
 345          * @exception   E_SUCCESS                               The method is successful.
 346          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 347          * @exception   E_INVALID_STATE                 The method invoked is invalid.
 348          * @exception   E_SYSTEM                                A system error has occurred.
 349          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 350          */
 351         virtual bool HasNextData(void);
 352
 353         /**
 354          * Gets the next data.
 355          *
 356          * @since       2.0
 357          *
 358          * @return              The buffer to be read
 359          * @param[in]   recommendedSize                 The recommended size of the data to send
 360          * @exception   E_SUCCESS                               The method is successful.
 361          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 362          * @exception   E_INVALID_STATE                 The method invoked is invalid.
 363          * @exception   E_SYSTEM                                A system error has occurred.
 364          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 365          */
 366         virtual Tizen::Base::ByteBuffer* GetNextDataN(int recommendedSize);
 367
 368 private:
 369         friend class _HttpMultipartEntityImpl;
 370         _HttpMultipartEntityImpl* __pHttpMultipartEntityImpl;
 371
 372 }; // HttpMultipartEntity
 373
 374 } } } // Tizen::Net::Http
 375 #endif // _FNET_HTTP_HTTP_MULTIPART_ENTITY_H_