Imported Upstream version 16.3.2

[platform/upstream/libzypp.git] / zypp / Callback.h

diff --git a/zypp/Callback.h b/zypp/Callback.h
index 3956a0b..3baf8c0 100644 (file)
--- a/zypp/Callback.h
+++ b/zypp/Callback.h
@@ -32,7 +32,7 @@ namespace zypp
    * \par The task report structure (SENDER SIDE).
    *
    * A default constructible struct derived from callback::ReportBase.
-   * It \b must \b not conatin any data, just virtual methods.
+   * It \b must \b not contain any data, just virtual methods.
    *
    * These are the functions the sender invokes, and which will be forwarded
    * to some receiver. If no receiver is present, the defined default
@@ -58,7 +58,7 @@ namespace zypp
    *
    * \par Sending a Task report (SENDER SIDE).
    *
-   * Simply create a callback::SendReport<_Report>, where _Report
+   * Simply create a callback::SendReport<TReport>, where TReport
    * is your task report structure. Invoke the callback functions
    * as needed. That's it.
    *
@@ -130,6 +130,17 @@ namespace zypp
    *
    * For typesafe passing of user data via callbacks \see \ref UserData.
    *
+   * ReportBase provides a generic \ref callback::ReportBase:report method
+   * which can be used to communicate by encoding everything in its \a UserData
+   * argument.
+   *
+   * Convenient sending can be achieved by installing non-virtual methods
+   * in the TReport class, which encode the arguments in UserData and send
+   * them via ReportBase::report().
+   *
+   * Convenient receiving can be achieved by installing virtual methods in
+   * the TReport class, which can be simply overloaded by the receiver. Downside
+   * of this is that adding virtual methods breaks binary compatibility.
    */
   namespace callback
   { /////////////////////////////////////////////////////////////////
@@ -138,22 +149,27 @@ namespace zypp
     struct ReportBase
     {
       typedef callback::UserData UserData;
+      typedef UserData::ContentType ContentType;
+
+      /** The most generic way of sending/receiving data. */
+      virtual void report( const UserData & userData_r = UserData() )
+      {}
+
       virtual ~ReportBase()
       {}
     };
 
     /**  */
-    template<class _Report>
+    template<class TReport>
       class DistributeReport;
 
     /**  */
-    template<class _Report>
-      struct ReceiveReport : public _Report
+    template<class TReport>
+      struct ReceiveReport : public TReport
       {
-       typedef _Report                   ReportType;
-       typedef typename ReportType::UserData UserData;
-       typedef ReceiveReport<_Report>    Receiver;
-        typedef DistributeReport<_Report> Distributor;
+       typedef TReport                   ReportType;
+       typedef ReceiveReport<TReport>    Receiver;
+        typedef DistributeReport<TReport> Distributor;
 
         virtual ~ReceiveReport()
         { disconnect(); }
@@ -177,14 +193,13 @@ namespace zypp
       };
 
     /**  */
-    template<class _Report>
+    template<class TReport>
       struct DistributeReport
       {
        public:
-       typedef _Report                   ReportType;
-       typedef typename ReportType::UserData UserData;
-       typedef ReceiveReport<_Report>    Receiver;
-       typedef DistributeReport<_Report> Distributor;
+       typedef TReport                   ReportType;
+       typedef ReceiveReport<TReport>    Receiver;
+       typedef DistributeReport<TReport> Distributor;
 
          static DistributeReport & instance()
          {
@@ -217,13 +232,12 @@ namespace zypp
       };
 
     /**  */
-    template<class _Report>
+    template<class TReport>
       struct SendReport : private zypp::base::NonCopyable
       {
-       typedef _Report                   ReportType;
-       typedef typename ReportType::UserData UserData;
-        typedef ReceiveReport<_Report>    Receiver;
-        typedef DistributeReport<_Report> Distributor;
+       typedef TReport                   ReportType;
+        typedef ReceiveReport<TReport>    Receiver;
+        typedef DistributeReport<TReport> Distributor;
 
         SendReport()
         { Distributor::instance()->reportbegin(); }
@@ -266,13 +280,12 @@ namespace zypp
      *  ...// r receiving the report
      * \endcode
     */
-    template<class _Report>
+    template<class TReport>
       struct TempConnect
       {
-       typedef _Report                   ReportType;
-       typedef typename ReportType::UserData UserData;
-        typedef ReceiveReport<_Report>    Receiver;
-        typedef DistributeReport<_Report> Distributor;
+       typedef TReport                   ReportType;
+        typedef ReceiveReport<TReport>    Receiver;
+        typedef DistributeReport<TReport> Distributor;
 
         TempConnect()
         : _oldRec( Distributor::instance().getReceiver() )