inc/FNetHttpHttpSession.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                FNetHttpHttpSession.h
  20  * @brief               This is the header file for the %HttpSession class.
  21  *
  22  * This header file contains the declarations of the %HttpSession class.
  23  */
  24
  25 #ifndef _FNET_HTTP_HTTP_SESSION_H_
  26 #define _FNET_HTTP_HTTP_SESSION_H_
  27
  28 #include <FBaseString.h>
  29 #include <FNetHttpHttpTypes.h>
  30 #include <FNetHttpHttpTransaction.h>
  31 #include <FNetHttpHttpHeader.h>
  32 #include <FNetHttpHttpCookieStorageManager.h>
  33 #include <FNetHttpHttpAuthentication.h>
  34 #include <FNetNetConnection.h>
  35
  36 namespace Tizen { namespace Net { namespace Http
  37 {
  38 class _HttpSessionImpl;
  39 /**
  40  * @class       HttpSession
  41  * @brief       This class represents an HTTP session.
  42  *
  43  * @since       2.0
  44  *
  45  * The %HttpSession class represents an HTTP session. The session encapsulates the client's HTTP activity over the duration of the client's execution. It is a set of transactions using the same
  46  * connection settings (such as proxy). The client may use several sessions concurrently if desired.
  47  *
  48  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/http_session.htm">HTTP Session</a>.
  49
  50  * The following example demonstrates how to use the %HttpSession 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     TestHttpSession(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
  72         // HttpSession construction.
  73         r = pSession->Construct(NET_HTTP_SESSION_MODE_NORMAL, pProxyAddr ,hostAddr, null);
  74
  75         // Open a new HttpTransaction.
  76         pTransaction = pSession->OpenTransactionN();
  77     }
  78
  79  * @endcode
  80  */
  81
  82 class _OSP_EXPORT_ HttpSession
  83         : public Tizen::Base::Object
  84 {
  85
  86 public:
  87         /**
  88          * 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.
  89          *
  90          * @since       2.0
  91          *
  92          * @remarks             After creating an instance of this class, one of the Construct() methods must be called explicitly to initialize the instance.
  93          */
  94         HttpSession(void);
  95
  96         /**
  97          * Initializes this instance of %HttpSession with the specified parameters. @n
  98          * Opens a session using the default @c netConnection.
  99          *
 100          * @since           2.0
 101          *
 102          * @return                      An error code
 103          * @param[in]           sessionMode                     The session mode to open the session
 104          * @param[in]           pProxyAddr                              A proxy address @n
 105          *                                                                                      The specified @c pProxyAddr must be a valid URL. If @c pProxyAddr is @c null, %HttpSession uses the system
 106          *                                                                                      default proxy address.
 107          * @param[in]           hostAddr                                A host address @n
 108          *                                                                                      The specified @c hostAddr must be a valid URL. If session mode is NET_HTTP_SESSION_MODE_MULTIPLE_HOST,
 109          *                                                                                      @c hostAddr is ignored (In case of multiple host mode, @c hostAddr is set to HttpRequest::SetUri()).
 110          * @param[in]           pCommonHeader                   An instance of HttpHeader @n
 111          *                                                                                      This is a common header used in all the transactions included in this session.
 112          * @param[in]           flag                                    Set to @c NET_HTTP_COOKIE_FLAG_ALWAYS_AUTOMATIC if the cookies must be handled automatically, @n
 113          *                                                                                      else @c NET_HTTP_COOKIE_FLAG_ALWAYS_MANUAL if the cookies must be handled manually
 114          * @exception           E_SUCCESS                               The method is successful.
 115          * @exception           E_INVALID_ARG                   A specified input parameter is invalid.
 116          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 117          * @exception           E_INVALID_CONNECTION    The net connection is invalid.
 118          * @exception           E_MAX_EXCEEDED          The number of currently opened sessions has exceeded the maximum limit.
 119          * @exception           E_INVALID_PROXY         The specified proxy address is invalid.
 120          * @exception           E_UNKNOWN                               An unknown error has occurred.
 121          * @exception           E_SYSTEM                                An internal error has occurred.
 122          * @exception           E_INVALID_ADDRESS               The host address is invalid.
 123          * @remarks                     In the NORMAL and PIPELINING session modes, all the transactions within this sessions are submitted through the same connection. While
 124          *                                      only one transaction is processed at a time in the Normal mode, multiple transactions can be pipelined in the Pipelining mode. In the
 125          *                                      normal mode, in order to submit the next transaction, the previous transaction must be complete.
 126          */
 127         result Construct(NetHttpSessionMode sessionMode, const Tizen::Base::String* pProxyAddr, const Tizen::Base::String& hostAddr, const HttpHeader* pCommonHeader, NetHttpCookieFlag flag = NET_HTTP_COOKIE_FLAG_ALWAYS_MANUAL);
 128
 129         /**
 130          * Initializes this instance of %HttpSession with the specified parameters. @n
 131          * Opens a session using the specified protocol.
 132          *
 133          * @since           2.0
 134          *
 135          * @return                      An error code
 136          * @param[in]           netConnection                   A NetConnection instance
 137          * @param[in]           sessionMode                             The session mode to open the session
 138          * @param[in]           pProxyAddr                              A proxy address @n
 139          *                                                                                      The specified @c pProxyAddr must be a valid URL. If @c pProxyAddr is @c null, %HttpSession uses the system
 140          *                                                                                      default proxy address.
 141          * @param[in]           hostAddr                                A host address @n
 142          *                                                                                      The specified @c hostAddr must be a valid URL.
 143          * @param[in]           pCommonHeader                   An instance of HttpHeader @n
 144          *                                                                                      This is a common header used in all the transactions included in this session.
 145          * @param[in]           flag                                    Set to @c NET_HTTP_COOKIE_FLAG_ALWAYS_AUTOMATIC if the cookies must be handled automatically, @n
 146          *                                                                                      else @c NET_HTTP_COOKIE_FLAG_ALWAYS_MANUAL if the cookies must be handled manually
 147          * @exception           E_SUCCESS                               The method is successful.
 148          * @exception           E_INVALID_ARG                   A specified input parameter is invalid.
 149          * @exception           E_OUT_OF_MEMORY                 The memory is insufficient.
 150          * @exception           E_INVALID_CONNECTION    The specified @c netConnection is invalid.
 151          * @exception           E_MAX_EXCEEDED                  Unable to setup new connection due to too many existing connections.
 152          * @exception           E_INVALID_PROXY                 The specified @c pProxyAddr is invalid.
 153          * @exception           E_UNKNOWN                               An unknown error has occurred.
 154          * @exception           E_SYSTEM                                An internal error has occurred.
 155          * @exception           E_INVALID_ADDRESS               The host address is invalid.
 156          * @remarks                     In the NORMAL and PIPELINING session mode, all the transactions within this session will be submitted through the same connection.
 157          *                                      While only one transaction is processed at a time in the Normal mode, multiple transactions can be pipelined in the Pipelining mode.
 158          *                                      In the normal mode, in order to submit the next transaction, the previous transaction must be complete.
 159          */
 160         result Construct(const NetConnection& netConnection, NetHttpSessionMode sessionMode, const Tizen::Base::String* pProxyAddr, const Tizen::Base::String& hostAddr, const HttpHeader* pCommonHeader, NetHttpCookieFlag flag = NET_HTTP_COOKIE_FLAG_ALWAYS_MANUAL);
 161
 162         /**
 163          * This destructor overrides Tizen::Base::Object::~Object().
 164          *
 165          * @since 2.0
 166          */
 167         virtual ~HttpSession(void);
 168
 169 public:
 170         /**
 171          * Opens a transaction.
 172          *
 173          * @since                       2.0
 174          * @privlevel           public
 175          * @privilege           http://tizen.org/privilege/http
 176          *
 177          * @return              A pointer to a new HttpTransaction, @n
 178          *                              else @c null if an error occurs
 179          * @exception   E_SUCCESS                               The method is successful.
 180          * @exception   E_MAX_EXCEEDED                  The maximum number of transactions has been reached.
 181          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 182          * @exception   E_SYSTEM                                A system error has occurred.
 183          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 184          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 185          * @remarks             The corresponding event listener must also be added in the same thread. A single transaction can be opened in a session at a time. After closing an open transaction, another
 186          *                              transaction can be opened.
 187          */
 188         HttpTransaction* OpenTransactionN(void);
 189
 190         /**
 191         * Opens a transaction with authentication information.
 192         *
 193         * @since                        2.0
 194         * @privlevel            public
 195         * @privilege            http://tizen.org/privilege/http
 196         *
 197         * @return               The pointer to a new HttpTransaction, @n
 198         *                               else @c null if an error occurs
 199         * @param[in]    auth                    The authentication information
 200         * @exception    E_SUCCESS                               The method is successful.
 201         * @exception    E_MAX_EXCEEDED                  The maximum number of transactions has been reached.
 202         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 203         * @exception    E_SYSTEM                                A system error has occurred.
 204         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 205         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 206         * @remarks              The corresponding event listener must also be added in the same thread. A single transaction at a time can be opened in a session. After closing an open transaction, another
 207         *                               transaction can be opened.
 208         */
 209         HttpTransaction* OpenTransactionN(const HttpAuthentication& auth);
 210
 211         /**
 212          * Cancels the specified transaction. @n
 213          * This method is followed by the CloseTransaction() method.
 214          *
 215          * @since                       2.0
 216          * @privlevel           public
 217          * @privilege           http://tizen.org/privilege/http
 218          *
 219          * @return              An error code
 220          * @param[in]   httpTransaction             The HttpTransaction to cancel
 221          * @exception   E_SUCCESS                                       The method is successful.
 222          * @exception   E_OPERATION_CANCELED            The specified transaction has already been canceled.
 223          * @exception   E_INVALID_STATE                         The method invoked is invalid.
 224          * @exception   E_INVALID_TRANSACTION           The specified @c httpTransaction is invalid.
 225          * @exception   E_UNKNOWN                                       An unknown error has occurred.
 226          * @exception   E_OUT_OF_MEMORY                         The memory is insufficient.
 227          * @exception   E_SYSTEM                                        A system error has occurred.
 228          * @exception   E_PRIVILEGE_DENIED                      The application does not have the privilege to call this method.
 229          * @remarks             The canceled transaction is no longer considered active. Also, re-opening the transaction is not allowed.
 230          */
 231         result CancelTransaction(HttpTransaction& httpTransaction);
 232
 233         /**
 234          * Closes the specified transaction.
 235          *
 236          * @since                       2.0
 237          * @privlevel           public
 238          * @privilege           http://tizen.org/privilege/http
 239          *
 240          * @return              An error code
 241          * @param[in]   httpTransaction                 The HttpTransaction to close
 242          * @exception   E_SUCCESS                               The method is successful.
 243          * @exception   E_OBJ_NOT_FOUND                 The specified transaction is not found within the indicated range, or @n
 244          *                                                                              The specified transaction is already deleted.
 245          * @exception   E_INVALID_STATE                 The method invoked is invalid.
 246          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 247          * @exception   E_INVALID_SESSION               The session is invalid.
 248          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 249          * @exception   E_SYSTEM                                A system error has occurred.
 250          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 251          */
 252         result CloseTransaction(HttpTransaction& httpTransaction);
 253
 254         /**
 255          * Closes all the transactions.
 256          *
 257          * @since                       2.0
 258          * @privlevel           public
 259          * @privilege           http://tizen.org/privilege/http
 260          *
 261          * @return              An error code
 262          * @exception   E_SUCCESS                               The method is successful.
 263          * @exception   E_OBJ_NOT_FOUND                 The specified transaction is not found within the indicated range, or @n
 264          *                                                                              the specified transaction is already deleted.
 265          * @exception   E_INVALID_SESSION               The session is invalid.
 266          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 267          * @exception   E_SYSTEM                                A system error has occurred.
 268          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 269          */
 270         result CloseAllTransactions(void);
 271
 272         /**
 273         * Sets the value to redirect the HTTP request automatically (the value is @c false by default).
 274         *
 275         * @since                2.0
 276         *
 277         * @return       An error code
 278         * @param[in]    enable                                  Set to @c true to redirect the HTTP request automatically, @n
 279         *                                       else @c false
 280         * @exception    E_SUCCESS               The method is successful.
 281         * @exception    E_INVALID_STATE                 The method invoked is invalid.
 282         * @exception    E_SYSTEM                A system error has occurred.
 283         */
 284         result SetAutoRedirectionEnabled(bool enable);
 285
 286         /**
 287         * Checks whether the HTTP redirection is automatic.
 288         *
 289         * @since                2.0
 290         *
 291         * @return       @c true if the HTTP redirection is automatic, @n
 292         *                               else @c false
 293         * @exception    E_SUCCESS           The method is successful.
 294         * @exception    E_SYSTEM            A system error has occurred.
 295         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 296         */
 297         bool IsAutoRedirectionEnabled(void) const;
 298
 299         /**
 300          * Gets the number of active transactions in the current instance of %HttpSession.
 301          *
 302          * @since                       2.0
 303          * @privlevel           public
 304          * @privilege           http://tizen.org/privilege/http
 305          *
 306          * @return      An integer value indicating the number of currently active transactions, @n
 307          *                              else @c -1 if an error occurs
 308          * @exception   E_SUCCESS                               The method is successful.
 309          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 310          * @exception   E_SYSTEM                                A system error has occurred.
 311          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 312          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 313          * @remarks             The transactions in the state between Submitted and Cancelled (or Closed) are considered to be active transactions.
 314          */
 315         int GetActiveTransactionCount(void) const;
 316
 317         /**
 318          * Gets the maximum number of transactions, the current instance of %HttpSession can have.
 319          *
 320          * @since                       2.0
 321          * @privlevel           public
 322          * @privilege           http://tizen.org/privilege/http
 323          *
 324          * @return      An integer value indicating the maximum number of transactions allowed @n
 325          *              In NET_HTTP_SESSION_MODE_MULTIPLE_HOST mode, the return value is zero.
 326          * @exception   E_SUCCESS                               The method is successful.
 327          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 328          * @exception   E_SYSTEM                                A system error has occurred.
 329          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 330          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 331          * @remarks             In NET_HTTP_SESSION_MODE_MULTIPLE_HOST mode, the platform does not limit the number of maximum HttpTransaction that %HttpSession can have. @n
 332          */
 333         int GetMaxTransactionCount(void) const;
 334
 335         /**
 336          * Gets the pointer to HttpCookieStorageManager.
 337          *
 338          * @since       2.0
 339          *
 340          * @return              The pointer to HttpCookieStorageManager, @n
 341          *              else @c null if an error occurs
 342          */
 343         HttpCookieStorageManager* GetCookieStorageManager(void) const;
 344
 345 private:
 346         /**
 347          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 348          *
 349          * @param[in]   rhs             An instance of %HttpSession
 350          */
 351         HttpSession(const HttpSession& rhs);
 352
 353         /**
 354          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 355          * Do @b not use directly.
 356          *
 357          * @param[in]   rhs                     An instance of %HttpSession
 358          */
 359         HttpSession& operator =(const HttpSession& rhs);
 360
 361 private:
 362         friend class _HttpSessionImpl;
 363         _HttpSessionImpl* __pHttpSessionImpl;
 364
 365 }; // HttpSession
 366
 367 } } } // Tizen::Net::Http
 368 #endif // _FNET_HTTP_HTTP_SESSION_H_