From 97455f5144c945e5c8e42fba84f6bf61cddcfe18 Mon Sep 17 00:00:00 2001
From: Martin Kampas <martin.kampas@tieto.com>
Date: Mon, 8 Apr 2013 09:09:07 +0200
Subject: [PATCH] Sandbox: add deactivate(), complete API doc

---
 libssu/sandbox.cpp | 44 ++++++++++++++++++++++++++++++++++++--------
 libssu/sandbox_p.h |  1 +
 2 files changed, 37 insertions(+), 8 deletions(-)

diff --git a/libssu/sandbox.cpp b/libssu/sandbox.cpp
index f14c549..3210e4c 100644
--- a/libssu/sandbox.cpp
+++ b/libssu/sandbox.cpp
@@ -17,7 +17,6 @@
 #include <QtCore/QSet>
 
 #include "libssu/ssucoreconfig.h"
-// TODO: rename to ssuconstants.h?
 #include "constants.h"
 
 class Sandbox::FileEngineHandler : public QAbstractFileEngineHandler {
@@ -37,20 +36,35 @@ class Sandbox::FileEngineHandler : public QAbstractFileEngineHandler {
 
 /**
  * @class Sandbox
+ * @brief Simple sandboxing with Qt file system abstraction.
  *
- * Redirects all file operations on system configuration files to files under
- * sandbox directory. When constructed without arguments, the directory is get
- * from @c SSU_TESTS_SANDBOX environment variable.
+ * Redirects all file operations on selected files to files under sandbox
+ * directory. The term <em>world files</em> is used to reffer files outside
+ * sandbox.
+ *
+ * Its effect is controlled by activate() and deactivate() calls. Only one
+ * Sandbox instance can be active at any time. Active sandbox is automatically
+ * deactivated upon destruction.
+ *
+ * When constructed without arguments, path to sandbox directory is get from
+ * @c SSU_TESTS_SANDBOX environment variable.
+ *
+ * @attention When constructed without arguments, it is activated automatically
+ * and failure to do so is reported with @c qFatal(), i.e., application will be
+ * abort()ed.
  *
  * When constructed with @a usage UseAsSkeleton, it will first make temporary
  * copy of @a sandboxPath to work on and files in the original directory will
- * stay untouched.
+ * stay untouched.  Also see addWorldFiles().
  *
  * The argument @scopes allows to control if the sandbox will be used by this
  * process, its children processes (@c SSU_TESTS_SANDBOX environment variable
  * will be exported), or both.
  *
  * Internally it is based on QAbstractFileEngineHandler.
+ *
+ * @attention QDir lists entries presented in the world directory.  The behavior
+ * changed with Qt 4.8.0 (Qt commit b9b55234a777c3b206332bafbe227e1355ca9186)
  */
 
 Sandbox *Sandbox::s_activeInstance = 0;
@@ -71,15 +85,15 @@ Sandbox::Sandbox(const QString &sandboxPath, Usage usage, Scopes scopes)
 }
 
 Sandbox::~Sandbox(){
-  delete m_handler;
+  if (isActive()){
+    deactivate();
+  }
 
   if (!m_tempDir.isEmpty() && QFileInfo(m_tempDir).exists()){
     if (QProcess::execute("rm", QStringList() << "-rf" << m_tempDir) != 0){
       qWarning("%s: Failed to remove temporary directory", Q_FUNC_INFO);
     }
   }
-
-  s_activeInstance = 0;
 }
 
 bool Sandbox::isActive() const{
@@ -105,6 +119,20 @@ bool Sandbox::activate(){
   return true;
 }
 
+void Sandbox::deactivate(){
+  Q_ASSERT(isActive());
+
+  if (m_scopes & ThisProcess){
+    delete m_handler;
+  }
+
+  if (m_scopes & ChildProcesses){
+    unsetenv("SSU_TESTS_SANDBOX");
+  }
+
+  s_activeInstance = 0;
+}
+
 /**
  * Copies selected files into sandbox. Existing files in sandbox are not overwriten.
  *
diff --git a/libssu/sandbox_p.h b/libssu/sandbox_p.h
index 9963812..a4eba52 100644
--- a/libssu/sandbox_p.h
+++ b/libssu/sandbox_p.h
@@ -33,6 +33,7 @@ class Sandbox {
     ~Sandbox();
 
     bool activate();
+    void deactivate();
     bool isActive() const;
 
     bool addWorldFiles(const QString &directory, QDir::Filters filters = QDir::NoFilter,