inc/FNetHttpHttpTransaction.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                FNetHttpHttpTransaction.h
  20  * @brief               This is the header file for the %HttpTransaction class.
  21  *
  22  * This header file contains the declarations of the %HttpTransaction class.
  23  */
  24
  25 #ifndef _FNET_HTTP_HTTP_TRANSACTION_H_
  26 #define _FNET_HTTP_HTTP_TRANSACTION_H_
  27
  28 #include <FNetHttpHttpTypes.h>
  29 #include <FNetHttpHttpRequest.h>
  30 #include <FNetHttpHttpResponse.h>
  31 #include <FNetHttpHttpAuthentication.h>
  32 #include <FNetHttpIHttpTransactionEventListener.h>
  33 #include <FNetHttpIHttpEntity.h>
  34 #include <FNetHttpIHttpProgressEventListener.h>
  35
  36 namespace Tizen { namespace Net { namespace Http
  37 {
  38 class _HttpTransactionImpl;
  39 /**
  40  * @class       HttpTransaction
  41  * @brief       This class manages the HTTP transaction that encapsulates a request and a response.
  42  *
  43  * @since       2.0
  44  *
  45  * The %HttpTransaction class manages the HTTP transaction that encapsulates a request and a response.
  46  * A transaction represents an interaction between the HTTP client and the HTTP origin server.
  47  *
  48  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/http_transaction.htm">HTTP Transaction</a>.
  49  *
  50  * The following example demonstrates how to use the %HttpTransaction 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     TestHttpTransaction(void)
  62     {
  63         result r = E_SUCCESS;
  64
  65         HttpSession* pSession = null;
  66         HttpTransaction* pTransaction = null;
  67         String* pProxyAddr = null;
  68         String hostAddr(L"http://www.tizen.org");
  69
  70         pSession = new HttpSession();
  71         r = pSession->Construct(NET_HTTP_SESSION_MODE_NORMAL, pProxyAddr ,hostAddr, null);
  72
  73         // Open a new HttpTransaction.
  74         pTransaction = pSession->OpenTransactionN();
  75
  76         r = pTransaction->AddHttpTransactionListener(*this);
  77
  78         HttpRequest* pRequest = pTransaction->GetRequest();
  79         r = pRequest->SetUri(L"http://www.tizen.org");
  80         r = pRequest->SetMethod(NET_HTTP_METHOD_GET);
  81
  82         // Submit the HttpTransaction.
  83         r = pTransaction->Submit();
  84     }
  85
  86  * @endcode
  87  */
  88
  89 class _OSP_EXPORT_ HttpTransaction
  90         : public Tizen::Base::Object
  91 {
  92
  93 public:
  94         /**
  95          * This destructor overrides Tizen::Base::Object::~Object().
  96          *
  97          * @since   2.0
  98          */
  99         virtual ~HttpTransaction(void);
 100
 101 public:
 102         /**
 103          * Submits the HTTP request.
 104          *
 105          * @since                       2.0
 106          * @privlevel           public
 107          * @privilege           http://tizen.org/privilege/http
 108          *
 109          * @return                      An error code
 110          * @exception           E_SUCCESS                               The method is successful.
 111          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 112          * @exception           E_INVALID_ARG                   A specified input parameter is invalid. @n
 113          *                                                                              At least one of Uri, Method, Header, and Body is invalid.
 114          * @exception           E_INVALID_HEADER                The header is @c null.
 115          * @exception       E_INVALID_STATE     The method invoked is invalid.
 116          * @exception           E_OUT_OF_RANGE          The submitted data is out of range.
 117          * @exception           E_MAX_EXCEEDED          The number of active transactions has exceeded the maximum limit.
 118          * @exception           E_INVALID_PROXY         The proxy server address is invalid.
 119          * @exception           E_DNS                                   The DNS query has failed.
 120          * @exception           E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
 121          * @exception           E_EMPTY_BODY                    The body is empty in a POST method case.
 122          * @exception           E_INVALID_SESSION               The session is invalid.
 123          * @exception           E_AUTHENTICATION                The authentication has failed.
 124          * @exception           E_UNKNOWN                               An unknown error has occurred.
 125          * @exception           E_SYSTEM                                A system error has occurred.
 126          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 127          * @remarks                     The appropriate request header and body must be set using HttpRequest before using this method.
 128          *                                      If the session is in a non-pipeline mode, be sure not to submit a transaction before the previous transaction is completed.
 129          * @see                         HttpHeader
 130          */
 131         result Submit(void);
 132
 133         /**
 134          * Gets the authentication information.
 135          *
 136          * @since                       2.0
 137          * @privlevel           public
 138          * @privilege           http://tizen.org/privilege/http
 139          *
 140          * @return              A pointer to HttpAuthentication
 141          * @exception   E_SUCCESS                               The method is successful.
 142          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 143          * @exception   E_INVALID_STATE                 The method invoked is invalid.
 144          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.
 145          * @exception   E_SYSTEM                                A system error has occurred.
 146          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 147          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 148          */
 149         HttpAuthentication* OpenAuthenticationInfoN(void);
 150
 151         /**
 152          * Gets a pointer to the HttpRequest related to the transaction. @n
 153          * Setting a request header, method, URI, and body can be done by using the @c pHttpRequest pointer.
 154          *
 155          * @since       2.0
 156          *
 157          * @return              The HttpRequest object pointer, @n
 158          *                              else @c null in case of an invalid condition
 159          * @exception   E_SUCCESS                       The method is successful.
 160          * @exception   E_INVALID_STATE     The method invoked is invalid.
 161          * @exception   E_INVALID_DATA      The request is not valid.
 162          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 163          * @see                 Tizen::Net::Http::HttpRequest
 164          */
 165         HttpRequest* GetRequest(void) const;
 166
 167         /**
 168          * Gets a pointer to the HttpResponse related to the transaction. @n
 169          * Getting a response header and body can be done by using the @c pHttpResponse pointer.
 170          *
 171          * @since       2.0
 172          *
 173          * @return              The HttpResponse object pointer, @n
 174          *                              else @c null if the response is not received
 175          * @exception   E_SUCCESS                       The method is successful.
 176          * @exception   E_INVALID_STATE         The method invoked is invalid.
 177          * @exception   E_INVALID_DATA      The response is not received.
 178          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 179          * @see                 HttpResponse
 180          */
 181         HttpResponse* GetResponse(void) const;
 182
 183         /**
 184          * Adds the IHttpTransactionEventListener instance. @n
 185          * The added listener can listen to events as they are fired.
 186          *
 187          * @since       2.0
 188          *
 189          * @return              An error code
 190          * @param[in]   listener                        The IHttpTransactionEventListener instance
 191          * @exception   E_SUCCESS                       The method is successful.
 192          * @exception   E_INVALID_STATE         The method invoked is invalid.
 193          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 194          * @exception   E_OBJ_ALREADY_EXIST     The listener is already added.
 195          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation, @n
 196          *                                                                      because the caller thread is a worker thread.
 197          */
 198         result AddHttpTransactionListener(IHttpTransactionEventListener& listener);
 199
 200         /**
 201          * Removes the IHttpTransactionEventListener instance.
 202          *
 203          * @since       2.0
 204          *
 205          * @return              An error code
 206          * @param[in]   listener                        The IHttpTransactionEventListener instance
 207          * @exception   E_SUCCESS                       The method is successful.
 208          * @exception   E_INVALID_STATE         The method invoked is invalid.
 209          * @exception   E_OBJ_NOT_FOUND         The specified instance is not found within the indicated range, or
 210          *                                                                      the listener is already removed.
 211          */
 212         result RemoveHttpTransactionListener(IHttpTransactionEventListener& listener);
 213
 214         /**
 215          * Sets the IHttpProgressEventListener instance.
 216          *
 217          * @since               2.0
 218          *
 219          * @return              An error code
 220          * @param[in]   listener                        The IHttpProgressEventListener instance
 221          * @exception   E_SUCCESS                       The method is successful.
 222          * @exception   E_INVALID_STATE         The method invoked is invalid.
 223          */
 224         result SetHttpProgressListener(IHttpProgressEventListener& listener);
 225
 226         /**
 227          * Sets a user object to the instance of %HttpTransaction.
 228          *
 229          * @since               2.0
 230          *
 231          * @return              An error code
 232          * @param[in]   pUserData                       The user data to set
 233          * @exception   E_SUCCESS                       The method is successful.
 234          * @exception   E_INVALID_STATE         The method invoked is invalid.
 235          */
 236         result SetUserObject(const Tizen::Base::Object* pUserData);
 237
 238         /**
 239          * Gets a user object that is set to the instance of %HttpTransaction.
 240          *
 241          * @since               2.0
 242          *
 243          * @return              An error code
 244          */
 245         Tizen::Base::Object* GetUserObject(void) const;
 246
 247         /**
 248          * Enables OnTransactionReadyToWrite.
 249          *
 250          * @since       2.0
 251          *
 252          * @return              @c true if the OnTransactionReadyToWrite listener is active, @n
 253          *                              else @c false
 254          */
 255         bool EnableTransactionReadyToWrite(void);
 256
 257         /**
 258          * Resumes the transaction after the IHttpTransactionEventListener::OnTransactionCertVerificationRequiredN() event is invoked. @n
 259          * As described in the IHttpTransactionEventListener section, the above event occurs in case of the uncertified server certificate.
 260          *
 261          * @since       2.0
 262          *
 263          * @return              An error code
 264          * @exception   E_SUCCESS                       The method is successful.
 265          * @exception   E_INVALID_STATE         The current state of the instance prohibits the execution of the specified operation.
 266          */
 267         result Resume(void);
 268
 269         /**
 270          * Pauses the transaction after the IHttpTransactionEventListener::OnTransactionCertVerificationRequiredN() event is invoked. @n
 271          * As described in the IHttpTransactionEventListener section, the above event occurs in case of the uncertified server certificate.
 272          *
 273          * @since       2.0
 274          *
 275          * @return              An error code
 276          * @exception   E_SUCCESS                       The method is successful.
 277          * @exception   E_INVALID_STATE         The current state of the instance prohibits the execution of the specified operation.
 278          */
 279         result Pause(void);
 280
 281         /**
 282          *      Sets a client certificate to connect the server.
 283          *
 284          * @since               2.0
 285          *
 286          * @return              An error code
 287          * @param[in]   certificateId           The selected client certificate to set
 288          * @exception   E_SUCCESS                       The method is successful.
 289          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 290          * @exception   E_INVALID_STATE         This instance is in an invalid state.
 291          * @remarks     Start the AppControl(L"tizen.certificatemanager") for getting the selected client certificate. @n
 292          *              For more information, see <a href="../org.tizen.native.appprogramming/html/guide/app/appcontrol_certmgr.htm">here</a>.
 293          */
 294         result SetClientCertificate(int certificateId);
 295
 296         /**
 297          *      Sets the timeout in seconds that is the timeout for waiting the transaction. @n
 298          *      A timeout value of zero means an infinite timeout.
 299          *
 300          *  @since              2.0
 301          *
 302          *      @return         An error code
 303          *  @param[in]  timeout                                 A timeout for transaction
 304          *      @exception      E_SUCCESS                               The method is successful.
 305          *  @exception  E_INVALID_ARG                   The specified input parameter is invalid.
 306          *  @exception  E_INVALID_STATE                 The transaction is already submitted, or
 307          *                                      the transaction is already closed.
 308          */
 309         result SetTimeout(int timeout);
 310
 311         /**
 312         * Sets the flag to verify server certificate. (the flag is @c HTTP_CV_FLAG_AUTOMATIC by default)
 313         *
 314         * @since                2.1
 315         *
 316         * @return       An error code
 317         * @param[in]    flag                                    Set the flag for certificate verification.
 318         * @exception    E_SUCCESS               The method is successful.
 319         * @exception    E_INVALID_STATE                 The method invoked is invalid.
 320         * @exception    E_SYSTEM                A system error has occurred.
 321         */
 322         result SetServerCertificateVerification(NetHttpCertificateVerificationFlag flag = HTTP_CV_FLAG_AUTOMATIC);
 323
 324 private:
 325         /**
 326          * This default constructor is intentionally declared as private so that only the platform can create an instance.
 327          */
 328         HttpTransaction(void);
 329
 330         /**
 331          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 332          *
 333          * @param[in]   rhs                     An instance of %HttpTransaction
 334          */
 335         HttpTransaction(const HttpTransaction& rhs);
 336
 337         /**
 338          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 339          *
 340          * @param[in]   rhs                             An instance of %HttpTransaction
 341          */
 342         HttpTransaction& operator =(const HttpTransaction& rhs);
 343
 344 private:
 345         friend class _HttpTransactionImpl;
 346         _HttpTransactionImpl* __pHttpTransactionImpl;
 347
 348 }; // HttpTransaction
 349
 350 } } } // Tizen::Net::Http
 351 #endif // _FNET_HTTP_HTTP_TRANSACTION_H_