inc/FNetHttpHttpResponse.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                FNetHttpHttpResponse.h
  20  * @brief               This is the header file for the %HttpResponse class.
  21  *
  22  * This header file contains the declarations of the %HttpResponse class.
  23  */
  24
  25 #ifndef _FNET_HTTP_HTTP_RESPONSE_H_
  26 #define _FNET_HTTP_HTTP_RESPONSE_H_
  27
  28 #include <FBaseColLinkedList.h>
  29 #include <FNetHttpHttpTypes.h>
  30 #include <FNetHttpHttpHeader.h>
  31 #include <FNetHttpHttpMessage.h>
  32 #include <FNetHttpHttpCookie.h>
  33
  34 namespace Tizen { namespace Net { namespace Http
  35 {
  36 class HttpTransaction;
  37 class _HttpResponseImpl;
  38 /**
  39  * @class       HttpResponse
  40  * @brief       This class represents a response message.
  41  *
  42  * @since   2.0
  43  *
  44  * The %HttpResponse class represents a response message that stores a status code, the status text, and the server version information, as well as
  45  * the message headers and body supplied by the HttpMessage base class.
  46  *
  47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/http_connectivity.htm">HTTP Guide</a>.
  48  *
  49  * The following example demonstrates how to use the %HttpResponse class.
  50  *
  51  * @code
  52
  53     #include <FBase.h>
  54     #include <FNet.h>
  55
  56     using namespace Tizen::Base;
  57     using namespace Tizen::Net::Http;
  58
  59     void
  60     MyTransactionEventListener::OnTransactionReadyToRead(const Tizen::Net::Http::HttpSession& httpSession,
  61                              const Tizen::Net::Http::HttpTransaction& httpTransaction, int availableBodyLen)
  62     {
  63         HttpResponse* pResponse = httpTransaction.GetResponse();
  64
  65         if (pResponse->GetHttpStatusCode() == HTTP_STATUS_OK)
  66         {
  67             ByteBuffer* pBody = null;
  68             String statusText = pResponse->GetStatusText();
  69             String version = pResponse->GetVersion();
  70             pBody = pResponse->ReadBodyN();
  71             delete pBody;
  72         }
  73     }
  74
  75  * @endcode
  76  */
  77 //////////////////////////////////////////////////////////////////////////
  78 class _OSP_EXPORT_ HttpResponse
  79         : public HttpMessage
  80 {
  81
  82 public:
  83         /**
  84          * @if OSPDEPREC
  85          * Gets the status code from the response header.
  86          *
  87          * @brief <i> [Deprecated] </i>
  88          * @deprecated  This method is deprecated. Instead of using this method, it is recommended to use the GetHttpStatusCode() method that returns the status code as an integer type.
  89          * @since       2.0
  90          *
  91          * @return              The status code, @n
  92          *                              else @c -1 if an error occurs
  93          * @exception   E_SUCCESS                               The method is successful.
  94          * @exception   E_INVALID_STATE                 Invoke this method before receiving a response header.
  95          * @exception   E_INVALID_DATA                  The status code is not defined.
  96          * @remarks     The specific error code can be accessed using the GetLastResult() method.
  97          * @remarks             The @c statusText gives a short textual description of the status code. It is placed after the status code on the first line of the
  98          *                              response. The specific error code can be accessed using the GetLastResult() method.
  99          * @see                 NetHttpStatusCode
 100          * @see                 SetStatusCode()
 101          * @endif
 102          */
 103         NetHttpStatusCode GetStatusCode(void) const;
 104
 105         /**
 106          * Gets the HTTP status code from the response header.
 107          *
 108          * @since       2.0
 109          *
 110          * @return              The status code, @n
 111          *                              else @c -1 if an error occurs
 112          * @exception   E_SUCCESS                                       The method is successful.
 113          * @exception   E_INVALID_STATE                         Invoke this method before receiving a response header.
 114          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 115          * @remarks             The @c statusText gives a short textual description of the status code. It is placed after the status code on the first line of the
 116          *                              response.
 117          * @see                 SetHttpStatusCode()
 118          */
 119         int GetHttpStatusCode(void) const;
 120
 121         /**
 122          * Gets a short textual description of the status code from the response header. @n
 123          * This description is placed after the status code on the first line of the response.
 124          *
 125          * @since       2.0
 126          *
 127          * @return              The status description, @n
 128          *                              else an empty string when the status text is not defined
 129          * @exception   E_SUCCESS                                       The method is successful.
 130          * @exception   E_INVALID_STATE                         Invoke this method before receiving a response header.
 131          * @exception   E_INVALID_DATA                          The status text is not defined.
 132          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 133          * @see                 SetStatusText()
 134          */
 135         Tizen::Base::String GetStatusText(void) const;
 136
 137         /**
 138          * Gets the version of the protocol used by the server from the response header.
 139          *
 140          * @since       2.0
 141          *
 142          * @return              The protocol version, @n
 143          *                              else an empty string when the version is not defined
 144          * @exception   E_SUCCESS                                       The method is successful.
 145          * @exception   E_INVALID_STATE                         Invoke this method before receiving a response header.
 146          * @exception   E_INVALID_DATA                          The version is not defined.
 147          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 148          * @see                 SetVersion()
 149          */
 150         Tizen::Base::String GetVersion(void) const;
 151
 152         /**
 153          * Gets the HttpHeader object of a response header.
 154          *
 155          * @since       2.0
 156          *
 157          * @return              The header object, @n
 158          *                              else @c null if the header is not received
 159          * @exception   E_SUCCESS                                       The method is successful.
 160          * @exception   E_INVALID_HEADER                        The header is @c null.
 161          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 162          */
 163         virtual HttpHeader* GetHeader(void) const;
 164
 165         /**
 166          * Gets the message body of the response.
 167          *
 168          * @since       2.0
 169          *
 170          * @return              The response body object
 171          * @exception   E_SUCCESS                               The method is successful.
 172          * @exception   E_INVALID_STATE                 Invoke this method before receiving a response body.
 173          * @exception   E_EMPTY_BODY                    The requested body is empty.
 174          * @exception   E_OUT_OF_RANGE                  The specified @c data size exceeds the maximum range.
 175          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 176          * @exception   E_IO                                    The method has failed to read the data.
 177          * @exception   E_UNKNOWN                               An unknown error has occurred.
 178          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 179          * @remarks             This method can be invoked several times until there is no more data.
 180          */
 181         virtual Tizen::Base::ByteBuffer* ReadBodyN(void);
 182
 183         /**
 184          * Gets the list of cookies received in the response.
 185          *
 186          * @since       2.0
 187          *
 188          * @return              A list containing HttpCookie instances, @n
 189          *                              else @c null if no cookie is received in the response
 190          * @exception   E_SUCCESS                               The method is successful.
 191          * @exception   E_INVALID_STATE                 The method invoked is invalid in this state.
 192          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 193          */
 194         Tizen::Base::Collection::IList* GetCookies(void) const;
 195
 196 protected:
 197         /**
 198          * 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.
 199          *
 200          * @since       2.0
 201          *
 202          * @remarks             After creating an instance of this class, the Construct() method must be called explicitly to initialize the instance.
 203          */
 204         HttpResponse(void);
 205
 206         /**
 207          * This destructor overrides Tizen::Base::Object::~Object().
 208          *
 209          * @since       2.0
 210          */
 211         virtual ~HttpResponse(void);
 212
 213         /**
 214          * Initializes this instance of %HttpResponse with the specified parameter.
 215          *
 216          * @since       2.0
 217          *
 218          * @return              An error code
 219          * @param[in]   httpTransaction                 The HTTP transaction
 220          * @exception   E_SUCCESS                               The method is successful.
 221          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 222          * @exception   E_INVALID_ARG                   The specified input parameter is @c null.
 223          * @exception   E_SYSTEM                                A system error has occurred.
 224          */
 225         result Construct(const HttpTransaction& httpTransaction);
 226
 227 protected:
 228         /**
 229          * @if OSPDEPREC
 230          * Sets the status code from the response header.
 231          *
 232          * @brief <i> [Deprecated] </i>
 233          * @deprecated This method is deprecated. Instead of using this method, it is recommended to use the SetHttpStatusCode() method that sets
 234          * the status code as integer type.
 235          * @since               2.0
 236          *
 237          * @return              An error code
 238          * @param[in]   statusCode                              The status code
 239          * @exception   E_SUCCESS                               The method is successful.
 240          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 241          * @remarks             The @c statusCode element is a 3-digit integer result code of the attempt to understand and satisfy the request. The first digit of the
 242          *                              @c statusCode defines the class of response. The last two digits do not have any categorization role.
 243          * @see                 GetStatusCode()
 244          * @endif
 245          */
 246         result SetStatusCode(NetHttpStatusCode statusCode);
 247
 248         /**
 249          * Sets the status code from the response header.
 250          *
 251          * @since       2.0
 252          *
 253          * @return              An error code
 254          * @param[in]   statusCode                              The status code
 255          * @exception   E_SUCCESS                               The method is successful.
 256          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 257          * @remarks             The @c statusCode element is a 3-digit integer result code of the attempt to understand and satisfy the request. The first digit of the
 258          *                              @c statusCode defines the class of response. The last two digits do not have any categorization role.
 259          * @see                 GetHttpStatusCode()
 260          */
 261         result SetHttpStatusCode(int statusCode);
 262
 263         /**
 264          * Sets the status text from the response header.
 265          *
 266          * @since       2.0
 267          *
 268          * @return              An error code
 269          * @param[in]   statusText                              The status description
 270          * @exception   E_SUCCESS                               The method is successful.
 271          * @exception   E_INVALID_ARG                   The specified input parameter is @c null.
 272          * @remarks             The @c statusText gives a short textual description of the status code. This description is placed after the status code on the first
 273          *                              line of the response.
 274          * @see                 GetStatusText()
 275          */
 276         result SetStatusText(const Tizen::Base::String& statusText);
 277
 278         /**
 279          * Sets the version of the protocol used by the server from the response header.
 280          *
 281          * @since       2.0
 282          *
 283          * @return              An error code
 284          * @param[in]   httpVersion                             The protocol version
 285          * @exception   E_SUCCESS                               The method is successful.
 286          * @exception   E_INVALID_ARG                   The specified input parameter is @c null.
 287          * @see                 GetVersion()
 288          */
 289         result SetVersion(const Tizen::Base::String& httpVersion);
 290
 291         /**
 292          * Sets the response body.
 293          *
 294          * @since       2.0
 295          *
 296          * @return              An error code
 297          * @param[in]   body                                    The message body data
 298          * @exception   E_SUCCESS                               The method is successful.
 299          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 300          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 301          * @exception   E_INVALID_STATE                 The method invoked is invalid in this state.
 302          * @remarks             This method can be invoked several times until there is no more data to write.
 303          */
 304         virtual result WriteBody(const Tizen::Base::ByteBuffer& body);
 305
 306         /**
 307          * Reads the data from the data communicated.
 308          *
 309          * @since       2.0
 310          *
 311          * @return              An error code
 312          * @param[in]   headerLen                               The header length to read
 313          * @param[in]   bodyLen                                 The body length to read
 314          * @param[out]  rcvHeaderLen                    The received header length
 315          * @param[out]  rcvBodyLen                              The received body length
 316          * @exception   E_SUCCESS                               The method is successful.
 317          * @exception   E_IO                                    The method has failed to read the data.
 318          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 319          * @exception   E_INVALID_SESSION               The session handle is invalid.
 320          * @exception   E_INVALID_TRANSACTION   The transaction handle is invalid.
 321          * @exception   E_SYSTEM                                An internal error has occurred.
 322          * @exception   E_OUT_OF_RANGE                  The read data exceeds the maximum range.
 323          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation. @n
 324          *                                                                              The comparer has failed to compare keys.
 325          * @exception   E_INVALID_HEADER        An invalid header is received in response.
 326          */
 327         result Read(int headerLen, int bodyLen, int& rcvHeaderLen, int& rcvBodyLen);
 328
 329         /**
 330          * Saves the cookie received in the response to %HttpResponse.
 331          *
 332          * @since           2.0
 333          *
 334          * @return                      An error code
 335          * @param[in]           pHeader                                 A response header
 336          * @exception           E_SUCCESS                               The method is successful.
 337          * @exception           E_INVALID_STATE                 The method invoked is invalid in this state.
 338          * @exception           E_OUT_OF_MEMORY                 The memory is insufficient.
 339          * @remarks                     Transaction events use this method to set the cookie received in the response.
 340          * @see                         GetCookies()
 341          */
 342         result SetCookie(Tizen::Net::Http::HttpHeader* pHeader);
 343
 344 private:
 345         /**
 346          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 347          *
 348          * @param[in]   rhs   An instance of %HttpResponse
 349          */
 350         HttpResponse(const HttpResponse& rhs);
 351
 352         /**
 353          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 354          *
 355          * @param[in]   rhs                             An instance of %HttpResponse
 356          */
 357         HttpResponse& operator =(const HttpResponse& rhs);
 358
 359 private:
 360         friend class _HttpResponseImpl;
 361         _HttpResponseImpl* __pHttpResponseImpl;
 362
 363 }; // HttpResponse
 364
 365 } } } // Tizen::Net::Http
 366 #endif // _FNET_HTTP_HTTP_RESPONSE_H_