inc/FWebCtrlIWebDownloadListener.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 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                FWebCtrlIWebDownloadListener.h
  20  * @brief               This is the header file for the %IWebDownloadListener interface.
  21  *
  22  * This header file contains the declarations of the %IWebDownloadListener interface.
  23  */
  24 #ifndef _FWEB_CTRL_IWEB_DOWNLOAD_LISTENER_H_
  25 #define _FWEB_CTRL_IWEB_DOWNLOAD_LISTENER_H_
  26
  27 #include <FBaseByteBuffer.h>
  28 #include <FBaseRtIEventListener.h>
  29 #include <FWebCtrlILoadingListener.h>
  30
  31 namespace Tizen { namespace Web { namespace Controls
  32 {
  33
  34 /**
  35  * @interface   IWebDownloadListener
  36  * @brief               This interface downloads data from the internet.
  37  *
  38  * @since               2.0
  39  *
  40  * The %IWebDownloadListener interface downloads data from the internet.
  41  * An application receives content from a network incrementally
  42  * when it decides to download the content after checking the Multipurpose Internet Mail Extensions (MIME).
  43  * This is useful when the content is not supported by the framework itself and the application wants to handle it.
  44  * @n
  45  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/web/controls_namespace.htm">Web Controls Guide</a>.
  46  *
  47  * The following examples demonstrate how to use the %IWebDownloadListener interface.
  48  *      @code
  49  *      #include <FWeb.h>
  50  *      #include <FUiControls.h>
  51  *
  52  *      using namespace Tizen::Web;
  53  *      using namespace Tizen::Ui::Controls;
  54  *
  55  *      // Adds a Web control to the parent container
  56  *      result
  57  *      WebSample::CreateControl(Form* pParentForm)
  58  *      {
  59  *              result r = E_SUCCESS;
  60  *
  61  *              pWeb = new Web();
  62  *              r = pWeb->Construct( pParentForm->GetClientAreaBounds());
  63  *              r = pParentForm->AddControl(pWeb);
  64  *
  65  *              // Sets a loading listener and a Web downloading listener
  66  *              pWeb->SetDownloadListener(pMyDownloadListener);
  67  *              pWeb->SetLoadingListener(pMyLoadingListener);
  68  *
  69  *              return r;
  70  *      }
  71  *      @endcode
  72  *
  73  *      As soon as the first chunk of data is received, OnWebDataReceived() is fired with the MIME type.
  74  *      If you want to download the data, return @c WEB_DECISION_DOWNLOAD.
  75  *
  76  *      @code
  77  *      DecisionPolicy
  78  *      MyLoadingListener::OnWebDataReceived(const Tizen::Base::String& mime, const Tizen::Net::Http::HttpHeader& header)
  79  *      {
  80  *              return WEB_DECISION_DOWNLOAD;
  81  *      }
  82  *      @endcode
  83  *
  84  * Then, the data is routed to OnWebChunkedDataReceived().
  85  *
  86  *      @code
  87  *      void
  88  *      MyDownloadListener::OnWebChunkedDataReceived(Tizen::Base::ByteBuffer& chunk)
  89  *      {
  90  *              // ....
  91  *      }
  92  *      @endcode
  93  */
  94 class _OSP_EXPORT_ IWebDownloadListener
  95         : public virtual Tizen::Base::Runtime::IEventListener
  96 {
  97 public:
  98         /**
  99          * This polymorphic destructor should be overridden if required. @n
 100          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
 101          *
 102          * @since               2.0
 103          */
 104         virtual ~IWebDownloadListener(void) {}
 105
 106         /**
 107         * Called when the HyperText Transfer Protocol (HTTP) protocol receives the next chunked data.
 108          *
 109          * @since               2.0
 110          *
 111          * @param[in]   chunk                   The chunked data
 112          * @remarks             The received data size is less than the capacity of the specified Tizen::Base::ByteBuffer by @c 1.
 113          */
 114         virtual void OnWebChunkedDataReceived(const Tizen::Base::ByteBuffer& chunk) = 0;
 115
 116         /**
 117           * Called when the downloading of the content is completed.
 118           *
 119           * @since              2.0
 120           */
 121         virtual void OnWebDataDownloadCompleted(void) = 0;
 122
 123         /**
 124         * Called when an error occurs while downloading content.
 125         *
 126         * @since                2.0
 127         *
 128         * @param[in]    error                   The type of error that occurs while downloading data
 129         */
 130         virtual void OnWebDownloadFailed(LoadingErrorType error) = 0;
 131
 132 protected:
 133         //
 134         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 135         //
 136         // Gets the Impl instance.
 137         //
 138         // @since               2.0
 139         //
 140         virtual void IWebDownloadListener_Reserved1(void) {}
 141
 142         //
 143         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 144         //
 145         // Gets the Impl instance.
 146         //
 147         // @since               2.0
 148         //
 149         virtual void IWebDownloadListener_Reserved2(void) {}
 150
 151 }; // IWebDownloadListener
 152
 153 }}} // Tizen::Web::Controls
 154 #endif // _FWEB_CTRL_IWEB_DOWNLOAD_LISTENER_H_