Add download event callback API and its example

5 files changed, 158 insertions, 4 deletions

diff --git a/src/ApiCallbackDownloadEventListener.cc b/src/ApiCallbackDownloadEventListener.cc
new file mode 100644
index 00000000..3a5e3742
--- /dev/null
+++ b/src/ApiCallbackDownloadEventListener.cc
@@ -0,0 +1,57 @@
+/* <!-- copyright */
+/*
+ * aria2 - The high speed download utility
+ *
+ * Copyright (C) 2013 Tatsuhiro Tsujikawa
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ *
+ * In addition, as a special exception, the copyright holders give
+ * permission to link the code of portions of this program with the
+ * OpenSSL library under certain conditions as described in each
+ * individual source file, and distribute linked combinations
+ * including the two.
+ * You must obey the GNU General Public License in all respects
+ * for all of the code used other than OpenSSL.  If you modify
+ * file(s) with this exception, you may extend this exception to your
+ * version of the file(s), but you are not obligated to do so.  If you
+ * do not wish to do so, delete this exception statement from your
+ * version.  If you delete this exception statement from all source
+ * files in the program, then also delete it here.
+ */
+/* copyright --> */
+#include "ApiCallbackDownloadEventListener.h"
+#include "RequestGroup.h"
+
+namespace aria2 {
+
+ApiCallbackDownloadEventListener::ApiCallbackDownloadEventListener
+(Session* session,
+ DownloadEventCallback callback,
+ void* userData)
+  : session_(session),
+    callback_(callback),
+    userData_(userData)
+{}
+
+ApiCallbackDownloadEventListener::~ApiCallbackDownloadEventListener() {}
+
+void ApiCallbackDownloadEventListener::onEvent
+(DownloadEvent event, const RequestGroup* group)
+{
+  callback_(session_, event, group->getGID(), userData_);
+}
+
+} // namespace aria2
diff --git a/src/ApiCallbackDownloadEventListener.h b/src/ApiCallbackDownloadEventListener.h
new file mode 100644
index 00000000..a681fe98
--- /dev/null
+++ b/src/ApiCallbackDownloadEventListener.h
@@ -0,0 +1,57 @@
+/* <!-- copyright */
+/*
+ * aria2 - The high speed download utility
+ *
+ * Copyright (C) 2013 Tatsuhiro Tsujikawa
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ *
+ * In addition, as a special exception, the copyright holders give
+ * permission to link the code of portions of this program with the
+ * OpenSSL library under certain conditions as described in each
+ * individual source file, and distribute linked combinations
+ * including the two.
+ * You must obey the GNU General Public License in all respects
+ * for all of the code used other than OpenSSL.  If you modify
+ * file(s) with this exception, you may extend this exception to your
+ * version of the file(s), but you are not obligated to do so.  If you
+ * do not wish to do so, delete this exception statement from your
+ * version.  If you delete this exception statement from all source
+ * files in the program, then also delete it here.
+ */
+/* copyright --> */
+#ifndef DOWNLOAD_EVENT_LISTENER_H
+#define DOWNLOAD_EVENT_LISTENER_H
+
+#include "Notifier.h"
+
+namespace aria2 {
+
+class ApiCallbackDownloadEventListener : public DownloadEventListener {
+public:
+  ApiCallbackDownloadEventListener(Session* session,
+                                   DownloadEventCallback callback,
+                                   void* userData);
+  virtual ~ApiCallbackDownloadEventListener();
+  virtual void onEvent(DownloadEvent event, const RequestGroup* group);
+private:
+  Session* session_;
+  DownloadEventCallback callback_;
+  void* userData_;
+};
+
+} // namespace aria2
+
+#endif // DOWNLOAD_EVENT_LISTENER_H
diff --git a/src/Makefile.am b/src/Makefile.am
index 6aee0591..8920cd94 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -659,7 +659,8 @@ DISTCLEANFILES = $(pkgconfig_DATA)
 lib_LTLIBRARIES = libaria2.la
 libaria2_la_SOURCES = $(SRCS) \
 	aria2api.cc aria2api.h \
-	KeepRunningCommand.cc KeepRunningCommand.h
+	KeepRunningCommand.cc KeepRunningCommand.h \
+	ApiCallbackDownloadEventListener.cc ApiCallbackDownloadEventListener.h
 else # !ENABLE_LIBARIA2
 noinst_LTLIBRARIES = libaria2.la
 libaria2_la_SOURCES = $(SRCS)
diff --git a/src/aria2api.cc b/src/aria2api.cc
index 42cabbb0..356b7515 100644
--- a/src/aria2api.cc
+++ b/src/aria2api.cc
@@ -59,6 +59,9 @@
 #include "console.h"
 #include "KeepRunningCommand.h"
 #include "A2STR.h"
+#include "SingletonHolder.h"
+#include "Notifier.h"
+#include "ApiCallbackDownloadEventListener.h"
 #ifdef ENABLE_BITTORRENT
 # include "bittorrent_helper.h"
 #endif // ENABLE_BITTORRENT
@@ -74,7 +77,9 @@ Session::~Session()
 
 SessionConfig::SessionConfig()
   : keepRunning(false),
-    useSignalHandler(true)
+    useSignalHandler(true),
+    downloadEventCallback(0),
+    userData(0)
 {}
 
 namespace {
@@ -116,7 +121,7 @@ Session* sessionNew(const KeyVals& options, const SessionConfig& config)
     rv = session->context->reqinfo->prepare();
     if(rv != 0) {
       delete session;
-      session = 0;
+      return 0;
     }
     const SharedHandle<DownloadEngine>& e =
       session->context->reqinfo->getDownloadEngine();
@@ -125,9 +130,17 @@ Session* sessionNew(const KeyVals& options, const SessionConfig& config)
       // Add command to make aria2 keep event polling
       e->addCommand(new KeepRunningCommand(e->newCUID(), e.get()));
     }
+    if(config.downloadEventCallback) {
+      SharedHandle<DownloadEventListener> listener
+        (new ApiCallbackDownloadEventListener(session,
+                                              config.downloadEventCallback,
+                                              config.userData));
+      SingletonHolder<Notifier>::instance()
+        ->addDownloadEventListener(listener);
+    }
   } else {
     delete session;
-    session = 0;
+    return 0;
   }
   return session;
 }
diff --git a/src/includes/aria2/aria2.h b/src/includes/aria2/aria2.h
index 5671c4ee..86ef420d 100644
--- a/src/includes/aria2/aria2.h
+++ b/src/includes/aria2/aria2.h
@@ -131,6 +131,21 @@ enum DownloadEvent {
 };
 
 /**
+ * @functypedef
+ *
+ * Callback function invoked when download event occurred. The |event|
+ * indicates the event. See :type:`DownloadEvent` for events. The
+ * |gid| refers to the download which this event was fired on. The
+ * |userData| is a pointer specified in
+ * :member:`SessionConfig::userData`.
+ *
+ * At the moment, the return value is ignored, but the implementation
+ * of this callback should return 0 for compatibility.
+ */
+typedef int (*DownloadEventCallback)(Session* session, DownloadEvent event,
+                                     const A2Gid& gid, void* userData);
+
+/**
  * @struct
  *
  * The configuration for the session.
@@ -166,6 +181,17 @@ struct SessionConfig {
    *   handled like shutdown(session, false) is called.
    */
   bool useSignalHandler;
+  /**
+   * Specify the callback function which will be invoked when download
+   * event occurred. See :type:`DownloadEvent` about the download
+   * event. The default value is ``NULL``.
+   */
+  DownloadEventCallback downloadEventCallback;
+  /**
+   * Pointer to user defined data. libaria2 treats this as opaque
+   * pointer and will not free it. The default value is ``NULL``.
+   */
+  void* userData;
 };
 
 /**