inc/FNetHttpHttpRequest.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                FNetHttpHttpRequest.h
  20  * @brief               This is the header file for the %HttpRequest class.
  21  *
  22  * This header file contains the declarations of the %HttpRequest class.
  23  */
  24
  25 #ifndef _FNET_HTTP_HTTP_REQUEST_H_
  26 #define _FNET_HTTP_HTTP_REQUEST_H_
  27
  28 #include <FNetHttpHttpMessage.h>
  29 #include <FNetHttpHttpTypes.h>
  30 #include <FNetHttpHttpHeader.h>
  31 #include <FNetHttpIHttpEntity.h>
  32
  33 namespace Tizen { namespace Net { namespace Http
  34 {
  35 class HttpTransaction;
  36 class _HttpRequestImpl;
  37
  38 /////////////////////////////////////////////////////////////////////////////
  39 /**
  40  * @class       HttpRequest
  41  * @brief       This class represents a request message.
  42  *
  43  * @since   2.0
  44  *
  45  * The %HttpRequest class represents an HTTP request message that stores a method (for example, HTTP GET), a URI, and the other message headers
  46  * and the body supplied by the HttpMessage base class.
  47  *
  48  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/http_connectivity.htm">HTTP Guide</a>.
  49  *
  50  * The following example demonstrates how to use the %HttpRequest class.
  51  *
  52  * @code
  53  *
  54     #include <FBase.h>
  55     #include <FNet.h>
  56
  57     using namespace Tizen::Base;
  58     using namespace Tizen::Net::Http;
  59
  60     void
  61     TestHttpRequest(void)
  62     {
  63         result r = E_SUCCESS;
  64         HttpSession* pSession = null;
  65         HttpTransaction* pTransaction = null;
  66         String hostAddr(L"http://www.tizen.org");
  67
  68         pSession = new HttpSession();
  69         r = pSession->Construct(NET_HTTP_SESSION_MODE_NORMAL, null, hostAddr, null);
  70
  71         pTransaction = pSession->OpenTransactionN();
  72         r = pTransaction->AddHttpTransactionListener(*this);
  73
  74         // Get the request instance.
  75         HttpRequest* pRequest = pTransaction->GetRequest();
  76
  77         // Set the method.
  78         NetHttpMethod method = NET_HTTP_METHOD_POST;
  79         r = pRequest->SetMethod(method);
  80
  81         // Set the uri.
  82         r = pRequest->SetUri(L"http://www.tizen.org/test");
  83
  84         HttpHeader* pHeader = null;
  85         pHeader = pRequest->GetHeader();
  86
  87         // Add the content-length to header.
  88         r = pHeader->AddField(L"Content-Length", L"1024");
  89     }
  90
  91  * @endcode
  92  */
  93 class _OSP_EXPORT_ HttpRequest
  94         : public HttpMessage
  95 {
  96
  97 public:
  98         /**
  99          * Sets an HTTP method of the request header. @n
 100          * The default method is @c NET_HTTP_METHOD_GET.
 101          *
 102          * @since       2.0
 103          *
 104          * @return              An error code
 105          * @param[in]   method                          An HTTP method
 106          * @exception   E_SUCCESS                       The method is successful.
 107          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 108          * @exception   E_INVALID_STATE         The corresponding transaction is already submitted.
 109          * @remarks             The detailed descriptions of the HTTP methods are as follows: @n
 110          *                              1) The OPTIONS method represents a request for information about the communication options available on the request/response chain
 111          *                              identified by the Request-URI. This method may include a message body to make more detailed queries. To do so, specify the Content-Length
 112          *                              (or Transfer-Encoding), and Content-Type header fields. However, if the server does not support this, the server may discard the body. @n
 113          *                              2) The GET method retrieves whatever information is identified by the Request-URI. @n
 114          *                              3) The HEAD method is identical to GET except that the server must not return a response message body. The GET and HEAD methods do
 115          *              not include a message body. @n
 116          *                              4) The POST method is used to request that the origin server accepts the entity enclosed in the request as a new subordinate of the
 117          *                              resource identified by the Request-URI. @n
 118          *                              5) The PUT method requests that the enclosed entity be stored under the supplied Request-URI. @n
 119          *                              When you are using the POST or PUT methods, be sure to specify the Content-Length header field, which is the message body length. @n
 120          *                              6) The DELETE method requests that the origin server deletes the resource identified by the Request-URI.
 121          * @see                 GetMethod()
 122          */
 123         result SetMethod(NetHttpMethod method);
 124
 125         /**
 126          * Sets a custom method of the request header.
 127          *
 128          * @since       2.0
 129          *
 130          * @return              An error code
 131          * @param[in]   method                          An HTTP method
 132          * @exception   E_SUCCESS                       The method is successful.
 133          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 134          * @exception   E_INVALID_STATE         The corresponding transaction is already submitted.
 135          * @remarks             This method can be used to user-defined methods as well as HTTP 1.1 methods like 'GET, PUT, POST, HEAD etc'.
 136          * @see                 GetCustomMethod()
 137          */
 138         result SetCustomMethod(const Tizen::Base::String& method);
 139
 140         /**
 141          * Sets an HTTP version of the request header.
 142          *
 143          * @since       2.0
 144          *
 145          * @return              An error code
 146          * @param[in]   version                         An HTTP version
 147          * @exception   E_SUCCESS                       The method is successful.
 148          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 149          * @exception   E_INVALID_STATE         The corresponding transaction is already submitted.
 150          * @see                 GetVersion()
 151          */
 152         result SetVersion(HttpVersion version);
 153
 154         /**
 155          * Sets a URI of the request header.
 156          *
 157          * @since       2.0
 158          *
 159          * @return              An error code
 160          * @param[in]   uri                                     The raw URI @n
 161          *                                                                      The URI must be a valid URI.
 162          * @exception   E_SUCCESS                       The method is successful.
 163          * @exception   E_INVALID_ARG           The specified @c uri is invalid.
 164          * @exception   E_INVALID_STATE         The corresponding transaction is already submitted.
 165          * @remarks             The URI must be encoded properly according to RFC 2396 before using this method.
 166          *                              The ending slash is a required part of a URL specifying a directory.
 167          * @see                 Tizen::Base::Utility::Uri
 168          * @see                 GetUri()
 169          */
 170         result SetUri(const Tizen::Base::String& uri);
 171
 172         /**
 173          * Sets the request message body.
 174          *
 175          * @since       2.0
 176          *
 177          * @return              An error code
 178          * @param[in]   body                                            The message body data
 179          * @exception   E_SUCCESS                                       The method is successful.
 180          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 181          * @exception   E_OUT_OF_MEMORY                         The memory is insufficient.
 182          * @exception   E_INVALID_SESSION                       The session handle is invalid.
 183          * @exception   E_INVALID_TRANSACTION           The transaction handle is invalid.
 184          * @exception   E_OUT_OF_RANGE                          The submitted body size is out of range.
 185          * @exception   E_INVALID_STATE                         Either of the following conditions has occurred: @n
 186          *                                                                                - The corresponding transaction is already submitted. @n
 187          *                                                                                - A chunked mode is not enabled.
 188          * @exception   E_UNKNOWN                                       An unknown error has occurred.
 189          * @remarks             This method can be used in two different situations. @n
 190          *                              @li Before submitting the request: @n
 191          *                              In this case, this method can be called several times consecutively, and all the bodies are appended together in the message queue until
 192          *                              the HttpTransaction::Submit() method is called. Set the message body, when the POST or PUT method is used. @n
 193          *                              @li After receiving an ADDCHUNK event: @n
 194          *                              In this case, this method must be invoked only once at a time. The recommended chunk size is given in IHttpTransactionEventListener::OnTransactionReadyToWrite().
 195          * @see                 SetMethod()
 196          * @see                 NetHttpMethod
 197          */
 198         virtual result WriteBody(const Tizen::Base::ByteBuffer& body);
 199
 200         /**
 201          * Sets the request entity.
 202          *
 203          * @since               2.0
 204          *
 205          * @return              An error code
 206          * @param[in]   entity                                          An instance of IHttpEntity to send
 207          * @exception   E_SUCCESS                                       The method is successful.
 208          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 209          * @exception   E_OUT_OF_MEMORY                         The memory is insufficient.
 210          * @exception   E_INVALID_SESSION                       The session handle is invalid.
 211          * @exception   E_INVALID_TRANSACTION           The transaction handle is invalid.
 212          * @exception   E_OUT_OF_RANGE                          The body size is out of range.
 213          * @exception   E_INVALID_STATE                         The WriteBody() method is already called.
 214          * @remarks             The instance of IHttpEntity is used by the internal platform.
 215          *              Do not delete or change the instance of %IHttpEntity before the IHttpTransactionEventListener::OnTransactionCompleted() or IHttpTransactionEventListener::OnTransactionAborted() method is called.
 216          */
 217         result SetEntity(IHttpEntity& entity);
 218
 219         /**
 220          * Gets the HttpHeader object of the HTTP request.
 221          *
 222          * @since       2.0
 223          *
 224          * @return              The header object of the HTTP request, @n
 225          *                              else @c null if the header is not set properly
 226          * @exception   E_SUCCESS                                       The method is successful.
 227          * @exception   E_INVALID_HEADER                        The header is @c null.
 228          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 229          * @remarks             This method is used to access the header associated with a transaction's request. The handle is obtained from the %HttpRequest object
 230          *                              associated with the transaction. Adding, modifying, or removing a header field is done using this header handle.
 231          */
 232         virtual HttpHeader* GetHeader(void) const;
 233
 234         /**
 235          * Sets the string to be sent in the cookie header field of %HttpRequest.
 236          *
 237          * @since       2.0
 238          *
 239          * @return              An error code
 240          * @param[in]   cookieString                    The cookie string @n
 241          *                                                                              For example, Cookie: cookie-name1=cookie-value1;cookie-name2=cookie-value2.
 242          * @exception   E_SUCCESS                               The method is successful.
 243          * @exception   E_INVALID_STATE                 The method invoked is invalid in this state.
 244          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 245          */
 246         result SetCookie(const Tizen::Base::String& cookieString);
 247
 248         /**
 249          * Gets the cookie header field of %HttpRequest.
 250          *
 251          * @since       2.0
 252          *
 253          * @return              The cookie string
 254          * @exception   E_SUCCESS                               The method is successful.
 255          * @exception   E_INVALID_STATE                 The cookie is empty.
 256          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 257          */
 258         Tizen::Base::String GetCookie(void) const;
 259
 260         /**
 261          * Sets the Accept-Encoding header field of %HttpRequest. @n
 262          * This header can be used to specify certain Content-Encoding which are acceptable for the response.
 263          *
 264          * @since               2.0
 265          *
 266          * @return              An error code
 267          * @param[in]   encoding                                        The accept encoding  @n
 268          *                                                                                      Three encodings ("identity", "gzip", "deflate") are supported. @n
 269          *                                                                                      If @c encoding is a empty string, an Accept-Encoding header containing all supported encodings will be set.
 270          * @exception   E_SUCCESS                                       The method is successful.
 271          * @exception   E_INVALID_ARG                           The specified @c encoding is invalid.
 272          * @exception   E_INVALID_STATE                         The corresponding transaction is already submitted.
 273          * @see                 GetAcceptEncoding()
 274          */
 275         result SetAcceptEncoding(const Tizen::Base::String& encoding);
 276
 277 protected:
 278         /**
 279          * 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.
 280          *
 281          * @since       2.0
 282          *
 283          * @remarks             After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
 284          * @see                 Construct()
 285          */
 286         HttpRequest(void);
 287
 288         /**
 289          * This destructor overrides Tizen::Base::Object::~Object().
 290          *
 291          * @since       2.0
 292          */
 293         virtual ~HttpRequest(void);
 294
 295         /**
 296          * Initializes this instance of %HttpRequest with the specified parameters.
 297          *
 298          * @since       2.0
 299          *
 300          * @return              An error code
 301          * @param[in]   httpTransaction                         The HTTP transaction
 302          * @param[in]   pCommonHeader                           A header object that stores the common header
 303          * @exception   E_SUCCESS                                       The method is successful.
 304          * @exception   E_INVALID_ARG                           A specified input parameter is @c null.
 305          * @exception   E_INVALID_OPERATION                     The current state of the instance prohibits the execution of the specified operation.
 306          * @exception   E_OUT_OF_MEMORY                         The memory is insufficient.
 307          * @exception   E_SYSTEM                                        A system error has occurred.
 308          */
 309         result Construct(const HttpTransaction& httpTransaction, const HttpHeader* pCommonHeader);
 310
 311         /**
 312          * Gets an HTTP method of the request header.
 313          *
 314          * @since               2.0
 315          *
 316          * @return              HTTP method
 317          * @see                 SetMethod()
 318          */
 319         NetHttpMethod GetMethod(void) const;
 320
 321         /**
 322          * Gets a custom method of the request header.
 323          *
 324          * @since       2.0
 325          *
 326          * @return              An error code
 327          * @param[out]  method                          The name of custom method
 328          * @exception   E_SUCCESS                       The method is successful.
 329          * @see                 SetCustomMethod()
 330          */
 331         result GetCustomMethod(Tizen::Base::String& method) const;
 332
 333         /**
 334          * Gets an HTTP version of the request header.
 335          *
 336          * @since       2.0
 337          *
 338          * @return              A version of HTTP
 339          * @see                 SetVersion()
 340          */
 341         HttpVersion GetVersion(void) const;
 342
 343         /**
 344          * Gets a URI of the request header.
 345          *
 346          * @since       2.0
 347          *
 348          * @return              An error code
 349          * @param[out]  uri                                             The raw URI
 350          * @exception   E_SUCCESS                               The method is successful.
 351          * @see                 SetUri()
 352          */
 353         result GetUri(Tizen::Base::String& uri) const;
 354
 355         /**
 356          * Gets the message body associated with an HTTP Request.
 357          *
 358          * @since       2.0
 359          *
 360          * @return              The response body object
 361          * @exception   E_SUCCESS                               The method is successful.
 362          * @exception   E_EMPTY_BODY                    The requested body is empty.
 363          * @exception   E_OUT_OF_MEMORY                 The ByteBuffer size is smaller than the request body size.
 364          * @exception   E_INVALID_STATE                 The method invoked is invalid in this state.
 365          * @exception   E_OUT_OF_RANGE                  The @c data size exceeds the maximum range.
 366          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 367          * @remarks             Be sure to @c Flip() the @c body, which is Tizen::Base::ByteBuffer, before reading any data in the %Tizen::Base::ByteBuffer instance.
 368          */
 369         virtual Tizen::Base::ByteBuffer* ReadBodyN(void);
 370
 371         /**
 372          * Gets the Accept-Encoding header field of %HttpRequest.
 373          *
 374          * @since               2.0
 375          *
 376          * @return              The accept encoding
 377          *
 378          * @see                 SetAcceptEncoding()
 379          */
 380         Tizen::Base::String GetAcceptEncoding(void) const;
 381
 382 private:
 383         /**
 384          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 385          *
 386          * @param[in]   rhs   An instance of %HttpRequest
 387          */
 388         HttpRequest(const HttpRequest& rhs);
 389
 390         /**
 391          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 392          *
 393          * @param[in]   rhs                             An instance of %HttpRequest
 394          */
 395         HttpRequest& operator =(const HttpRequest& rhs);
 396
 397 private:
 398         friend class _HttpRequestImpl;
 399         _HttpRequestImpl* __pHttpRequestImpl;
 400
 401 }; // HttpRequest
 402
 403 } } } // Tizen::Net::Http
 404 #endif // _FNET_HTTP_HTTP_REQUEST_H_