inc/FNetHttpIHttpTransactionEventListener.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                FNetHttpIHttpTransactionEventListener.h
  20  * @brief               This is the header file for the %IHttpTransactionEventListener interface.
  21  *
  22  * This header file contains the declarations of the %IHttpTransactionEventListener interface.
  23  */
  24
  25 #ifndef _FNET_HTTP_IHTTP_TRANSACTION_EVENT_LISTENER_H_
  26 #define _FNET_HTTP_IHTTP_TRANSACTION_EVENT_LISTENER_H_
  27
  28 #include <unique_ptr.h>
  29 #include <FBaseTypes.h>
  30 #include <FBaseString.h>
  31 #include <FBaseColIList.h>
  32 #include <FBaseRtIEventListener.h>
  33
  34 namespace Tizen { namespace Net { namespace Http
  35 {
  36 class HttpSession;
  37 class HttpTransaction;
  38 /**
  39  * @interface   IHttpTransactionEventListener
  40  * @brief               This interface provides listeners for the HTTP transaction events.
  41  *
  42  * @since       2.0
  43  *
  44  * @remarks     If a user-defined class is derived from multiple classes including this interface, a compile error for using an ambiguous base class can occur. @n
  45  *          In this case, type casting is required to declare an explicit base class for the user-defined class.
  46  *
  47  * The %IHttpTransactionEventListener interface provides listeners for the HTTP transaction events. To use this listener, you must add it to the HttpTransaction instance
  48  * through the AddListener() method. If an HTTP transaction event is generated, a method of this class is called.
  49  *
  50  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/http_transaction.htm">HTTP Transaction</a>.
  51  */
  52
  53 class _OSP_EXPORT_ IHttpTransactionEventListener
  54         : virtual public Tizen::Base::Runtime::IEventListener
  55 {
  56
  57 public:
  58         /**
  59          * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes are called when the destructor of this interface is called.
  60          *
  61          * @since   2.0
  62          */
  63         virtual ~IHttpTransactionEventListener(void) {}
  64
  65 public:
  66         /**
  67          * Called to notify when the content body of the response has been received.
  68          *
  69          * @since       2.0
  70          *
  71          * @param[in]   httpSession                                     The session information of the %Http transaction event
  72          * @param[in]   httpTransaction                         The transaction information of the %Http transaction event
  73          * @param[in]   availableBodyLen                        The length of the available body of the %Http transaction
  74          * @see                 HttpResponse::ReadBodyN()
  75          */
  76         virtual void OnTransactionReadyToRead(HttpSession& httpSession, HttpTransaction& httpTransaction, int availableBodyLen) = 0;
  77
  78         /**
  79          * Called to notify when the process of transaction has been aborted.
  80          *
  81          * @since       2.0
  82          *
  83          * @param[in]   httpSession                                     The session information of the %Http transaction event
  84          * @param[in]   httpTransaction                         The transaction information of the %Http transaction event
  85          * @param[in]   r                                                       The cause of the error
  86          * @exception   E_INVALID_ARG                           A specified input parameter is invalid.
  87          * @exception   E_OUT_OF_MEMORY                         The memory is insufficient.
  88          * @exception   E_IO                                            The method has failed to read the data.
  89          * @exception   E_TIMEOUT                                       An attempt to connect to the server has timed out.
  90          * @exception   E_NETWORK_UNAVAILABLE           The network is unavailable.
  91          * @exception   E_HOST_UNREACHABLE                      The network cannot be reached from this host at this time.
  92          * @exception   E_SYSTEM                                        An internal error has occurred.
  93          * @exception   E_UNKNOWN                                       An unknown error has occurred.
  94          * @exception   E_NOT_RESPONDING                        There is no response.
  95          * @exception   E_INVALID_CONTENT                       The content is invalid.
  96          * @exception   E_CONNECTION_RESET                      The network connection has been reset.
  97          * @exception   E_HTTP_USER                                     The HTTP user is canceled.
  98          * @exception   E_NO_CERTIFICATE                        The client certificate is required to connect to the server.
  99          * @exception   E_UNSUPPORTED_SERVICE           The service is not allowed.
 100          * @exception   E_USER_AGENT_NOT_ALLOWED        The user agent is not allowed.
 101          * @exception   E_RESOURCE_UNAVAILABLE          The network resource is unavailable.
 102          * @remarks     If the E_NO_CERTIFICATE exception is thrown, start the AppControl(L"tizen.certificatemanager") for getting the selected client certificate. @n
 103          *              For more information, see <a href="../org.tizen.native.appprogramming/html/guide/app/appcontrol_certmgr.htm">here</a>.
 104          */
 105         virtual void OnTransactionAborted(HttpSession& httpSession, HttpTransaction& httpTransaction, result r) = 0;
 106
 107         /**
 108          * Called to add chunks to the request.
 109          *
 110          * @since       2.0
 111          *
 112          * @param[in]   httpSession                                     The session information of the %Http transaction event
 113          * @param[in]   httpTransaction                         The transaction information of the %Http transaction event
 114          * @param[in]   recommendedChunkSize            The length of the chunked %Http transaction
 115          * @remarks     To enable this listener, HttpTransaction::EnableTransactionReadyToWrite() must be called.
 116          * @see                 HttpRequest::WriteBody()
 117          */
 118         virtual void OnTransactionReadyToWrite(HttpSession& httpSession, HttpTransaction& httpTransaction, int recommendedChunkSize) = 0;
 119
 120         /**
 121          * Called to notify when the header of response has been received.
 122          *
 123          * @since       2.0
 124          *
 125          * @param[in]   httpSession                                     The session information of the %Http transaction event
 126          * @param[in]   httpTransaction                         The transaction information of the %Http transaction event
 127          * @param[in]   headerLen                                       The length of the %Http transaction's header
 128          * @param[in]   bAuthRequired                           Set to @c true if the transaction requires authentication, @n
 129          *                                                                                      else @c false
 130          * @see                 HttpResponse::GetHeader()
 131          */
 132         virtual void OnTransactionHeaderCompleted(HttpSession& httpSession, HttpTransaction& httpTransaction, int headerLen, bool bAuthRequired) = 0;
 133
 134         /**
 135          * Called to notify when the process of transaction has been completed.
 136          *
 137          * @since       2.0
 138          *
 139          * @param[in]   httpSession                                     The session information of the %Http transaction event
 140          * @param[in]   httpTransaction                         The transaction information of the %Http transaction event
 141          * @see                 HttpResponse::GetHeader()
 142      * @see             HttpResponse::ReadBodyN()
 143          */
 144         virtual void OnTransactionCompleted(HttpSession& httpSession, HttpTransaction& httpTransaction) = 0;
 145
 146         /**
 147          * Called to accept input from the user on whether to resume or pause the transaction in case the certificate is not verified.
 148          *
 149          * @since           2.0
 150          *
 151          * @param[in]           httpSession                             The session information of the %Http transaction event
 152          * @param[in]           httpTransaction                 The transaction information of the %Http transaction event
 153          * @param[in]           pCert                                   The certificate information
 154          * @see                         HttpTransaction::Resume()
 155      * @see             HttpTransaction::Pause()
 156          */
 157         virtual void OnTransactionCertVerificationRequiredN(HttpSession& httpSession, HttpTransaction& httpTransaction, Tizen::Base::String* pCert) = 0;
 158
 159         /**
 160          * Called to notify when the server certificate verification has been requested.
 161          *
 162          * @since           2.1
 163          * @return                      The result for certificate verification.
 164          *
 165          * @param[in]           httpSession                             The session information of the %Http transaction event
 166          * @param[in]           httpTransaction                 The transaction information of the %Http transaction event
 167          * @param[in]           pCertList                               The server certificate chain. An IList whose element is of the type Tizen::Security::Cert::X509Certificate *.
 168          *
 169          * @remarks                     Do not delete instance of @c httpSession or @c httpTransaction in this listener before the IHttpTransactionEventListener::OnTransactionCompleted() or IHttpTransactionEventListener::OnTransactionAborted() method is called.
 170          * @see                         HttpTransaction::SetServerCertificateVerification()
 171          */
 172         virtual bool OnTransactionCertVerificationRequestedN(HttpSession& httpSession, HttpTransaction& httpTransaction, Tizen::Base::Collection::IList* pCertList)
 173         {
 174                 std::unique_ptr<Tizen::Base::Collection::IList> upCertList(pCertList);
 175                 return false;
 176         }
 177
 178 protected:
 179         //
 180         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 181         //
 182         // This method is reserved and may change its name at any time without prior notice.
 183         //
 184         // @since       2.0
 185         //
 186         virtual void IHttpTransactionEventListener_Reserved1(void) {}
 187
 188 };
 189
 190 } } } // Tizen::Net::Http
 191 #endif // _FNET_HTTP_IHTTP_TRANSACTION_EVENT_LISTENER_H_