storage client methods for restoring backups (see #1641)

livesupport/src/modules/storageClient/include/LiveSupport/StorageClient/StorageClientInterface.h

@@ -79,6 +79,18 @@ class StorageClientInterface
         {
         }
 
+        /**
+         *  The possible states of an asynchronous process.
+         *  This is used by the asynchronous (groups of) methods:
+         *  remoteSearch, createBackup, restoreBackup,
+         *  uploadToHub, downloadFromHub.
+         */
+        typedef enum {  initState,
+                        pendingState,
+                        finishedState,
+                        closedState,
+                        failedState }       AsyncState;
+
         /**
          *  Return the version string from the storage.
          *
@@ -520,23 +532,24 @@ class StorageClientInterface
                                                                         = 0;
         
         /**
-         *  Check the status of a storage backup.
+         *  Check the state of a storage backup.
          *
          *  @param  token   the identifier of this backup task.
          *  @param  url     return parameter;
-         *                      if the status is "success", it contains the 
+         *                      if a finishedState is returned, it contains the
          *                      URL of the created backup file.
          *  @param  path    return parameter;
-         *                      if the status is "success", it contains the
+         *                      if a finishedState is returned, it contains the
          *                      local access path of the created backup file.
          *  @param  errorMessage    return parameter;
-         *                      if the status is "fault", it contains the
+         *                      if a failedState is returned, it contains the
          *                      fault string.
-         *  @return the status string: one of "working", "success", or "fault".
+         *  @return the state of the backup process: one of pendingState,
+         *                      finishedState, or failedState.
          *  @exception XmlRpcException if there is a problem with the XML-RPC
          *                             call.
          */
-        virtual Ptr<Glib::ustring>::Ref
+        virtual AsyncState
         createBackupCheck(const Glib::ustring &             token,
                           Ptr<const Glib::ustring>::Ref &   url,
                           Ptr<const Glib::ustring>::Ref &   path,
@@ -566,7 +579,7 @@ class StorageClientInterface
          *                             call.
          */
         virtual Ptr<Glib::ustring>::Ref
-        restoreBackup(Ptr<SessionId>::Ref               sessionId,
+        restoreBackupOpen(Ptr<SessionId>::Ref               sessionId,
                           Ptr<const Glib::ustring>::Ref     path) const
                                                 throw (XmlRpcException)
                                                                         = 0;
@@ -576,18 +589,31 @@ class StorageClientInterface
          *
          *  @param  token       the identifier of this backup task.
          *  @param  errorMessage    return parameter;
-         *                      if the status is "fault", it contains the
+         *                      if a failedState is returned, it contains the
          *                      fault string.
-         *  @return the status string: one of "working", "success", or "fault".
+         *  @return the state of the restore process: one of pendingState,
+         *                      finishedState, or failedState.
          *  @exception XmlRpcException if there is a problem with the XML-RPC
          *                             call.
          */
-        virtual Ptr<Glib::ustring>::Ref
+        virtual AsyncState
-        restoreBackupCheck(Ptr<const Glib::ustring>::Ref    token,
+        restoreBackupCheck(const Glib::ustring &            token,
                            Ptr<const Glib::ustring>::Ref &  errorMessage) const
                                                 throw (XmlRpcException)
                                                                         = 0;
         
+        /**
+         *  Close the backup restore process.
+         *
+         *  @param  token       the identifier of this backup task.
+         *  @exception XmlRpcException if there is a problem with the XML-RPC
+         *                             call.
+         */
+        virtual void
+        restoreBackupClose(const Glib::ustring &            token) const
+                                                throw (XmlRpcException)
+                                                                        = 0;
+        
         /**
          *  The possible formats of exported playlists.
          */
@@ -648,15 +674,6 @@ class StorageClientInterface
                                                 throw (XmlRpcException)
                                                                         = 0;
 
-        /**
-         *  The possible states of an asynchronous transport process.
-         */
-        typedef enum {  initState,
-                        pendingState,
-                        finishedState,
-                        closedState,
-                        failedState }       TransportState;
-
         /**
          *  Check the status of the asynchronous network transport operation.
          *
@@ -680,7 +697,7 @@ class StorageClientInterface
          *  @exception XmlRpcException if there is a problem with the XML-RPC
          *                             call.
          */
-        virtual TransportState
+        virtual AsyncState
         checkTransport(Ptr<const Glib::ustring>::Ref    token,
                        Ptr<Glib::ustring>::Ref      errorMessage
                                                     = Ptr<Glib::ustring>::Ref())

livesupport/src/modules/storageClient/src/TestStorageClient.cxx

@@ -1034,7 +1034,7 @@ TestStorageClient :: createBackupOpen(Ptr<SessionId>::Ref       sessionId,
 /*------------------------------------------------------------------------------
  *  Check the status of a storage backup.
  *----------------------------------------------------------------------------*/
-Ptr<Glib::ustring>::Ref
+TestStorageClient :: AsyncState
 TestStorageClient :: createBackupCheck(
                           const Glib::ustring &             token,
                           Ptr<const Glib::ustring>::Ref &   url,
@@ -1042,8 +1042,7 @@ TestStorageClient :: createBackupCheck(
                           Ptr<const Glib::ustring>::Ref &   errorMessage) const
                                                 throw (XmlRpcException)
 {
-    Ptr<Glib::ustring>::Ref     status(new Glib::ustring("working"));
+    return pendingState;
-    return status;
 }
 
         
@@ -1061,7 +1060,7 @@ TestStorageClient :: createBackupClose(const Glib::ustring &    token) const
  *  Initiate the uploading of a storage backup to the local storage.
  *----------------------------------------------------------------------------*/
 Ptr<Glib::ustring>::Ref
-TestStorageClient :: restoreBackup(
+TestStorageClient :: restoreBackupOpen(
                         Ptr<SessionId>::Ref             sessionId,
                         Ptr<const Glib::ustring>::Ref   path)           const
                                                 throw (XmlRpcException)
@@ -1074,14 +1073,23 @@ TestStorageClient :: restoreBackup(
 /*------------------------------------------------------------------------------
  *  Check the status of a backup restore.
  *----------------------------------------------------------------------------*/
-Ptr<Glib::ustring>::Ref
+TestStorageClient :: AsyncState
 TestStorageClient :: restoreBackupCheck(
-                        Ptr<const Glib::ustring>::Ref   token,
+                        const Glib::ustring &           token,
                         Ptr<const Glib::ustring>::Ref & errorMessage)   const
                                                 throw (XmlRpcException)
 {
-    Ptr<Glib::ustring>::Ref     status(new Glib::ustring("working"));
+    return pendingState;
-    return status;
+}
+
+
+/*------------------------------------------------------------------------------
+ *  Close the backup restore process.
+ *----------------------------------------------------------------------------*/
+void
+TestStorageClient :: restoreBackupClose(const Glib::ustring &   token) const
+                                                throw (XmlRpcException)
+{
 }
 
 
@@ -1128,7 +1136,7 @@ TestStorageClient :: importPlaylist(
 /*------------------------------------------------------------------------------
  *  Check the status of the asynchronous network transport operation.
  *----------------------------------------------------------------------------*/
-StorageClientInterface::TransportState
+TestStorageClient :: AsyncState
 TestStorageClient :: checkTransport(Ptr<const Glib::ustring>::Ref  token,
                                     Ptr<Glib::ustring>::Ref        errorMessage)
                                                 throw (XmlRpcException)

livesupport/src/modules/storageClient/src/TestStorageClient.h

@@ -653,23 +653,23 @@ class TestStorageClient :
         
         /**
          *  Check the status of a storage backup.
-         *  This is a dummy method; it always returns the status "working".
+         *  This is a dummy method; it always returns a pendingState.
          *
-         *  @param  token   the identifier of this backup task.
          *  @param  url     return parameter;
-         *                      if the status is "success", it contains the 
+         *                      if a finishedState is returned, it contains the
          *                      URL of the created backup file.
          *  @param  path    return parameter;
-         *                      if the status is "success", it contains the
+         *                      if a finishedState is returned, it contains the
          *                      local access path of the created backup file.
          *  @param  errorMessage    return parameter;
-         *                      if the status is "fault", it contains the
+         *                      if a failedState is returned, it contains the
          *                      fault string.
-         *  @return the status string: one of "working", "success", or "fault".
+         *  @return the state of the backup process: one of pendingState,
+         *                      finishedState, or failedState.
          *  @exception XmlRpcException if there is a problem with the XML-RPC
          *                             call.
          */
-        virtual Ptr<Glib::ustring>::Ref
+        virtual AsyncState
         createBackupCheck(const Glib::ustring &             token,
                           Ptr<const Glib::ustring>::Ref &   url,
                           Ptr<const Glib::ustring>::Ref &   path,
@@ -690,6 +690,7 @@ class TestStorageClient :
 
         /**
          *  Initiate the uploading of a storage backup to the local storage.
+         *  This is a dummy method; it just returns a fake token.
          *
          *  @param  sessionId   the session ID from the authentication client.
          *  @param  path        the location of the archive file to upload.
@@ -698,26 +699,39 @@ class TestStorageClient :
          *                             call.
          */
         virtual Ptr<Glib::ustring>::Ref
-        restoreBackup(Ptr<SessionId>::Ref               sessionId,
+        restoreBackupOpen(Ptr<SessionId>::Ref               sessionId,
                           Ptr<const Glib::ustring>::Ref     path) const
                                                 throw (XmlRpcException);
         
         /**
          *  Check the status of a backup restore.
+         *  This is a dummy method; it always returns a pendingState.
          *
          *  @param  token       the identifier of this backup task.
          *  @param  errorMessage    return parameter;
-         *                      if the status is "fault", it contains the
+         *                      if a failedState is returned, it contains the
          *                      fault string.
-         *  @return the status string: one of "working", "success", or "fault".
+         *  @return the state of the restore process: one of pendingState,
+         *                      finishedState, or failedState.
          *  @exception XmlRpcException if there is a problem with the XML-RPC
          *                             call.
          */
-        virtual Ptr<Glib::ustring>::Ref
+        virtual AsyncState
-        restoreBackupCheck(Ptr<const Glib::ustring>::Ref    token,
+        restoreBackupCheck(const Glib::ustring &            token,
                            Ptr<const Glib::ustring>::Ref &  errorMessage) const
                                                 throw (XmlRpcException);
         
+        /**
+         *  Close the backup restore process.
+         *
+         *  @param  token       the identifier of this backup task.
+         *  @exception XmlRpcException if there is a problem with the XML-RPC
+         *                             call.
+         */
+        virtual void
+        restoreBackupClose(const Glib::ustring &            token) const
+                                                throw (XmlRpcException);
+        
         /**
          *  Initiate the exporting of a playlist.
          *
@@ -792,7 +806,7 @@ class TestStorageClient :
          *  @exception XmlRpcException if there is a problem with the XML-RPC
          *                             call.
          */
-        virtual TransportState
+        virtual AsyncState
         checkTransport(Ptr<const Glib::ustring>::Ref    token,
                        Ptr<Glib::ustring>::Ref      errorMessage
                                                     = Ptr<Glib::ustring>::Ref())

livesupport/src/modules/storageClient/src/TestStorageClientTest.cxx

@@ -487,12 +487,11 @@ TestStorageClientTest :: createBackupTest(void)
     Ptr<const Glib::ustring>::Ref       url;
     Ptr<const Glib::ustring>::Ref       path;
     Ptr<const Glib::ustring>::Ref       errorMessage;
-    Ptr<Glib::ustring>::Ref         status;
+    StorageClientInterface::AsyncState  state;
     CPPUNIT_ASSERT_NO_THROW(
-        status = tsc->createBackupCheck(*token, url, path, errorMessage);
+        state = tsc->createBackupCheck(*token, url, path, errorMessage);
     );
-    CPPUNIT_ASSERT(status);
+    CPPUNIT_ASSERT_EQUAL(StorageClientInterface::pendingState, state);
-    CPPUNIT_ASSERT_EQUAL(std::string(*status), std::string("working"));
     
     CPPUNIT_ASSERT_NO_THROW(
         tsc->createBackupClose(*token);
@@ -500,6 +499,34 @@ TestStorageClientTest :: createBackupTest(void)
 }
 
 
+/*------------------------------------------------------------------------------
+ *  Testing the restoreBackupXxxx() functions.
+ *----------------------------------------------------------------------------*/
+void
+TestStorageClientTest :: restoreBackupTest(void)
+                                                throw (CPPUNIT_NS::Exception)
+{
+    Ptr<Glib::ustring>::Ref     path(new Glib::ustring(
+                                                "var/cowbell_backup.tar"));
+    Ptr<Glib::ustring>::Ref     token;
+    CPPUNIT_ASSERT_NO_THROW(
+        token = tsc->restoreBackupOpen(dummySessionId, path);
+    );
+    CPPUNIT_ASSERT(token);
+    
+    Ptr<const Glib::ustring>::Ref       errorMessage;
+    StorageClientInterface::AsyncState  state;
+    CPPUNIT_ASSERT_NO_THROW(
+        state = tsc->restoreBackupCheck(*token, errorMessage);
+    );
+    CPPUNIT_ASSERT_EQUAL(StorageClientInterface::pendingState, state);
+    
+    CPPUNIT_ASSERT_NO_THROW(
+        tsc->restoreBackupClose(*token);
+    );
+}
+
+
 /*------------------------------------------------------------------------------
  *  Testing the exportPlaylistXxxx() functions.
  *----------------------------------------------------------------------------*/
@@ -553,7 +580,7 @@ TestStorageClientTest :: remoteSearchTest(void)
     CPPUNIT_ASSERT(token);
     
     Ptr<Glib::ustring>::Ref                 errorMessage(new Glib::ustring);
-    StorageClientInterface::TransportState  state;
+    StorageClientInterface::AsyncState      state;
     CPPUNIT_ASSERT_NO_THROW(
         state = tsc->checkTransport(token, errorMessage);
     );

livesupport/src/modules/storageClient/src/TestStorageClientTest.h

@@ -74,6 +74,7 @@ class TestStorageClientTest : public CPPUNIT_NS::TestFixture
     CPPUNIT_TEST(searchTest);
     CPPUNIT_TEST(getAllTest);
     CPPUNIT_TEST(createBackupTest);
+    CPPUNIT_TEST(restoreBackupTest);
     CPPUNIT_TEST(exportPlaylistTest);
     CPPUNIT_TEST(remoteSearchTest);
     CPPUNIT_TEST_SUITE_END();
@@ -179,6 +180,14 @@ class TestStorageClientTest : public CPPUNIT_NS::TestFixture
         void
         createBackupTest(void)                  throw (CPPUNIT_NS::Exception);
 
+        /**
+         *  Testing the restoreBackupXxxx() functions.
+         *
+         *  @exception CPPUNIT_NS::Exception on test failures.
+         */
+        void
+        restoreBackupTest(void)                 throw (CPPUNIT_NS::Exception);
+
         /**
          *  Testing the exportPlaylistXxxx() functions.
          *

livesupport/src/modules/storageClient/src/WebStorageClient.cxx

@@ -713,6 +713,52 @@ const std::string    createBackupTmpFileParamName = "tmpfile";
 const std::string    createBackupFaultStringParamName = "faultString";
 
 
+/* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~  storage server constants: restoreBackupXxxx */
+
+/*------------------------------------------------------------------------------
+ *  The name of the 'open' restore backup method on the storage server
+ *----------------------------------------------------------------------------*/
+const std::string    restoreBackupOpenMethodName 
+                            = "locstor.restoreBackupOpen";
+
+/*------------------------------------------------------------------------------
+ *  The name of the 'check' restore backup method on the storage server
+ *----------------------------------------------------------------------------*/
+const std::string    restoreBackupCheckMethodName 
+                            = "locstor.restoreBackupCheck";
+
+/*------------------------------------------------------------------------------
+ *  The name of the 'close' restore backup method on the storage server
+ *----------------------------------------------------------------------------*/
+const std::string    restoreBackupCloseMethodName 
+                            = "locstor.restoreBackupClose";
+
+/*------------------------------------------------------------------------------
+ *  The name of the session ID parameter in the input structure
+ *----------------------------------------------------------------------------*/
+const std::string    restoreBackupSessionIdParamName    = "sessid";
+
+/*------------------------------------------------------------------------------
+ *  The name of the search criteria parameter in the input structure
+ *----------------------------------------------------------------------------*/
+const std::string    restoreBackupFileNameParamName     = "filename";
+
+/*------------------------------------------------------------------------------
+ *  The name of the token parameter in the input or output structure
+ *----------------------------------------------------------------------------*/
+const std::string    restoreBackupTokenParamName        = "token";
+
+/*------------------------------------------------------------------------------
+ *  The name of the status parameter in the output structure
+ *----------------------------------------------------------------------------*/
+const std::string    restoreBackupStatusParamName       = "status";
+
+/*------------------------------------------------------------------------------
+ *  The name of the faultString parameter in the output structure
+ *----------------------------------------------------------------------------*/
+const std::string    restoreBackupFaultStringParamName  = "faultString";
+
+
 /* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~  storage server constants: exportPlaylistXxxx */
 
 /*------------------------------------------------------------------------------
@@ -2370,7 +2416,7 @@ WebStorageClient :: createBackupOpen(Ptr<SessionId>::Ref        sessionId,
 /*------------------------------------------------------------------------------
  *  Check the status of a storage backup.
  *----------------------------------------------------------------------------*/
-Ptr<Glib::ustring>::Ref
+WebStorageClient :: AsyncState
 WebStorageClient :: createBackupCheck(
                           const Glib::ustring &             token,
                           Ptr<const Glib::ustring>::Ref &   url,
@@ -2387,16 +2433,18 @@ WebStorageClient :: createBackupCheck(
 
     execute(createBackupCheckMethodName, parameters, result);
     
-    Ptr<Glib::ustring>::Ref     status;
-    
     checkStruct(createBackupCheckMethodName,
                 result,
                 createBackupStatusParamName,
                 XmlRpcValue::TypeString);
     
-    status.reset(new Glib::ustring(result[createBackupStatusParamName]));
+    Ptr<Glib::ustring>::Ref     status(new Glib::ustring(
+                                    result[createBackupStatusParamName] ));
     
-    if (*status == "success") {
+    if (*status == "working") {
+        return pendingState;
+    
+    } else if (*status == "success") {
         checkStruct(createBackupCheckMethodName,
                     result,
                     createBackupUrlParamName,
@@ -2412,9 +2460,10 @@ WebStorageClient :: createBackupCheck(
         
         path.reset(new const Glib::ustring(
                         std::string(result[createBackupTmpFileParamName]) ));
-    }
         
-    if (*status == "fault") {
+        return finishedState;
+    
+    } else if (*status == "fault") {
         checkStruct(createBackupCheckMethodName,
                     result,
                     createBackupFaultStringParamName,
@@ -2422,9 +2471,18 @@ WebStorageClient :: createBackupCheck(
         
         errorMessage.reset(new Glib::ustring(
                         std::string(result[createBackupFaultStringParamName])));
-    }
         
-    return status;
+        return failedState;
+    
+    } else {
+        std::stringstream eMsg;
+        eMsg << "Incorrect value '"
+             << *status
+             << "' returned by the XML-RPC method '" 
+             << createBackupCheckMethodName
+             << "; expected one of 'working', 'success' or 'fault'.";
+        throw XmlRpcMethodResponseException(eMsg.str());
+    }
 }
 
         
@@ -2450,12 +2508,30 @@ WebStorageClient :: createBackupClose(const Glib::ustring &     token) const
  *  Initiate the uploading of a storage backup to the local storage.
  *----------------------------------------------------------------------------*/
 Ptr<Glib::ustring>::Ref
-WebStorageClient :: restoreBackup(
+WebStorageClient :: restoreBackupOpen(
                         Ptr<SessionId>::Ref             sessionId,
                         Ptr<const Glib::ustring>::Ref   path)           const
                                                 throw (XmlRpcException)
 {
-    Ptr<Glib::ustring>::Ref     token(new Glib::ustring("fake token"));
+    XmlRpcValue     parameters;
+    XmlRpcValue     result;
+
+    parameters.clear();
+    parameters[restoreBackupSessionIdParamName] 
+            = sessionId->getId();
+    parameters[restoreBackupFileNameParamName] 
+            = std::string(*path);
+
+    execute(restoreBackupOpenMethodName, parameters, result);
+    
+    checkStruct(restoreBackupOpenMethodName,
+                result,
+                restoreBackupTokenParamName,
+                XmlRpcValue::TypeString);
+    
+    Ptr<Glib::ustring>::Ref     token(new Glib::ustring( 
+                                    result[createBackupTokenParamName] ));
+    
     return token;
 }
 
@@ -2463,14 +2539,73 @@ WebStorageClient :: restoreBackup(
 /*------------------------------------------------------------------------------
  *  Check the status of a backup restore.
  *----------------------------------------------------------------------------*/
-Ptr<Glib::ustring>::Ref
+WebStorageClient :: AsyncState
 WebStorageClient :: restoreBackupCheck(
-                        Ptr<const Glib::ustring>::Ref   token,
+                        const Glib::ustring &           token,
                         Ptr<const Glib::ustring>::Ref & errorMessage)   const
                                                 throw (XmlRpcException)
 {
-    Ptr<Glib::ustring>::Ref     status(new Glib::ustring("working"));
+    XmlRpcValue     parameters;
-    return status;
+    XmlRpcValue     result;
+
+    parameters.clear();
+    parameters[restoreBackupTokenParamName] 
+            = std::string(token);
+
+    execute(restoreBackupCheckMethodName, parameters, result);
+    
+    checkStruct(restoreBackupCheckMethodName,
+                result,
+                restoreBackupStatusParamName,
+                XmlRpcValue::TypeString);
+    
+    Ptr<Glib::ustring>::Ref     status(new Glib::ustring(
+                                    result[restoreBackupStatusParamName] ));
+    
+    if (*status == "working") {
+        return pendingState;
+    
+    } else if (*status == "success") {
+        return finishedState;
+    
+    } else if (*status == "fault") {
+        checkStruct(restoreBackupCheckMethodName,
+                    result,
+                    restoreBackupFaultStringParamName,
+                    XmlRpcValue::TypeString);
+        
+        errorMessage.reset(new Glib::ustring(
+                    std::string(result[restoreBackupFaultStringParamName])));
+        
+        return failedState;
+    
+    } else {
+        std::stringstream eMsg;
+        eMsg << "Incorrect value '"
+             << *status
+             << "' returned by the XML-RPC method '" 
+             << restoreBackupCheckMethodName
+             << "; expected one of 'working', 'success' or 'fault'.";
+        throw XmlRpcMethodResponseException(eMsg.str());
+    }
+}
+
+
+/*------------------------------------------------------------------------------
+ *  Close the backup restore process.
+ *----------------------------------------------------------------------------*/
+void
+WebStorageClient :: restoreBackupClose(const Glib::ustring &    token) const
+                                                throw (XmlRpcException)
+{
+    XmlRpcValue     parameters;
+    XmlRpcValue     result;
+
+    parameters.clear();
+    parameters[restoreBackupTokenParamName] 
+            = std::string(token);
+
+    execute(restoreBackupCloseMethodName, parameters, result);
 }
 
 
@@ -2616,7 +2751,7 @@ WebStorageClient :: importPlaylist(
 /*------------------------------------------------------------------------------
  *  Check the status of the asynchronous network transport operation.
  *----------------------------------------------------------------------------*/
-StorageClientInterface::TransportState
+WebStorageClient :: AsyncState
 WebStorageClient :: checkTransport(Ptr<const Glib::ustring>::Ref  token,
                                    Ptr<Glib::ustring>::Ref        errorMessage)
                                                 throw (XmlRpcException)

livesupport/src/modules/storageClient/src/WebStorageClient.h

@@ -750,19 +750,20 @@ class WebStorageClient :
          *
          *  @param  token   the identifier of this backup task.
          *  @param  url     return parameter;
-         *                      if the status is "success", it contains the 
+         *                      if a finishedState is returned, it contains the
          *                      URL of the created backup file.
          *  @param  path    return parameter;
-         *                      if the status is "success", it contains the
+         *                      if a finishedState is returned, it contains the
          *                      local access path of the created backup file.
          *  @param  errorMessage    return parameter;
-         *                      if the status is "fault", it contains the
+         *                      if a failedState is returned, it contains the
          *                      fault string.
-         *  @return the status string: one of "working", "success", or "fault".
+         *  @return the state of the backup process: one of pendingState,
+         *                      finishedState, or failedState.
          *  @exception XmlRpcException if there is a problem with the XML-RPC
          *                             call.
          */
-        virtual Ptr<Glib::ustring>::Ref
+        virtual AsyncState
         createBackupCheck(const Glib::ustring &             token,
                           Ptr<const Glib::ustring>::Ref &   url,
                           Ptr<const Glib::ustring>::Ref &   path,
@@ -790,7 +791,7 @@ class WebStorageClient :
          *                             call.
          */
         virtual Ptr<Glib::ustring>::Ref
-        restoreBackup(Ptr<SessionId>::Ref               sessionId,
+        restoreBackupOpen(Ptr<SessionId>::Ref               sessionId,
                           Ptr<const Glib::ustring>::Ref     path) const
                                                 throw (XmlRpcException);
         
@@ -799,17 +800,29 @@ class WebStorageClient :
          *
          *  @param  token       the identifier of this backup task.
          *  @param  errorMessage    return parameter;
-         *                      if the status is "fault", it contains the
+         *                      if a failedState is returned, it contains the
          *                      fault string.
-         *  @return the status string: one of "working", "success", or "fault".
+         *  @return the state of the restore process: one of pendingState,
+         *                      finishedState, or failedState.
          *  @exception XmlRpcException if there is a problem with the XML-RPC
          *                             call.
          */
-        virtual Ptr<Glib::ustring>::Ref
+        virtual AsyncState
-        restoreBackupCheck(Ptr<const Glib::ustring>::Ref    token,
+        restoreBackupCheck(const Glib::ustring &            token,
                            Ptr<const Glib::ustring>::Ref &  errorMessage) const
                                                 throw (XmlRpcException);
         
+        /**
+         *  Close the backup restore process.
+         *
+         *  @param  token       the identifier of this backup task.
+         *  @exception XmlRpcException if there is a problem with the XML-RPC
+         *                             call.
+         */
+        virtual void
+        restoreBackupClose(const Glib::ustring &            token) const
+                                                throw (XmlRpcException);
+        
         /**
          *  Initiate the exporting of a playlist.
          *
@@ -884,7 +897,7 @@ class WebStorageClient :
          *  @exception XmlRpcException if there is a problem with the XML-RPC
          *                             call.
          */
-        virtual TransportState
+        virtual AsyncState
         checkTransport(Ptr<const Glib::ustring>::Ref    token,
                        Ptr<Glib::ustring>::Ref      errorMessage
                                                     = Ptr<Glib::ustring>::Ref())

livesupport/src/modules/storageClient/src/WebStorageClientTest.cxx

@@ -841,20 +841,21 @@ WebStorageClientTest :: createBackupTest(void)
     Ptr<const Glib::ustring>::Ref           url;
     Ptr<const Glib::ustring>::Ref           path;
     Ptr<const Glib::ustring>::Ref           errorMessage;
-    Ptr<Glib::ustring>::Ref         status;
+    StorageClientInterface::AsyncState      state;
+    
     int     iterations = 20;
     do {
         std::cerr << "-/|\\"[iterations%4] << '\b';
         sleep(1);
         CPPUNIT_ASSERT_NO_THROW(
-            status = wsc->createBackupCheck(*token, url, path, errorMessage);
+            state = wsc->createBackupCheck(*token, url, path, errorMessage);
         );
-        CPPUNIT_ASSERT(status);
+        CPPUNIT_ASSERT(state == StorageClientInterface::pendingState
-        CPPUNIT_ASSERT(*status == "working"
+                         || state == StorageClientInterface::finishedState
-                         || *status == "success"
+                         || state == StorageClientInterface::failedState);
-                         || *status == "fault");
+    } while (--iterations && state == StorageClientInterface::pendingState);
-    } while (--iterations && *status == "working");
+    
-    CPPUNIT_ASSERT_EQUAL(std::string("success"), std::string(*status));
+    CPPUNIT_ASSERT_EQUAL(StorageClientInterface::finishedState, state);
     // TODO: test accessibility of the URL?
     
     CPPUNIT_ASSERT_NO_THROW(
@@ -868,6 +869,68 @@ WebStorageClientTest :: createBackupTest(void)
 }
 
 
+/*------------------------------------------------------------------------------
+ *  Testing the restoreBackupXxxx() functions.
+ *----------------------------------------------------------------------------*/
+void
+WebStorageClientTest :: restoreBackupTest(void)
+                                                throw (CPPUNIT_NS::Exception)
+{
+    Ptr<SessionId>::Ref         sessionId;
+    CPPUNIT_ASSERT_NO_THROW(
+        sessionId = authentication->login("root", "q");
+    );
+    CPPUNIT_ASSERT(sessionId);
+    
+    Ptr<UniqueId>::Ref      oldAudioClipId(new UniqueId("0000000000010001"));
+    CPPUNIT_ASSERT(
+        wsc->existsAudioClip(sessionId, oldAudioClipId)
+    );
+    
+    Ptr<Glib::ustring>::Ref     path(new Glib::ustring(
+                                                "var/cowbell_backup.tar"));
+    Ptr<Glib::ustring>::Ref     token;
+    CPPUNIT_ASSERT_NO_THROW(
+        token = wsc->restoreBackupOpen(sessionId, path);
+    );
+    CPPUNIT_ASSERT(token);
+    
+    Ptr<const Glib::ustring>::Ref           errorMessage;
+    StorageClientInterface::AsyncState      state;
+    
+    int     iterations = 20;
+    do {
+        std::cerr << "-/|\\"[iterations%4] << '\b';
+        sleep(1);
+        CPPUNIT_ASSERT_NO_THROW(
+            state = wsc->restoreBackupCheck(*token, errorMessage);
+        );
+        CPPUNIT_ASSERT(state == StorageClientInterface::pendingState
+                         || state == StorageClientInterface::finishedState
+                         || state == StorageClientInterface::failedState);
+    } while (--iterations && state == StorageClientInterface::pendingState);
+    
+    CPPUNIT_ASSERT_EQUAL(StorageClientInterface::finishedState, state);
+    
+    CPPUNIT_ASSERT_NO_THROW(
+        wsc->createBackupClose(*token);
+    );
+    
+    CPPUNIT_ASSERT(
+        !wsc->existsAudioClip(sessionId, oldAudioClipId)
+    );
+    
+    Ptr<UniqueId>::Ref      newAudioClipId(new UniqueId("7c215b48a9c827e6"));
+    CPPUNIT_ASSERT(
+        wsc->existsAudioClip(sessionId, newAudioClipId)
+    );
+    
+    CPPUNIT_ASSERT_NO_THROW(
+        authentication->logout(sessionId);
+    );
+}
+
+
 /*------------------------------------------------------------------------------
  *  Testing the exportPlaylistXxxx() functions.
  *----------------------------------------------------------------------------*/
@@ -1014,7 +1077,7 @@ WebStorageClientTest :: remoteSearchTest(void)
     );
     
     Ptr<Glib::ustring>::Ref                 errorMessage(new Glib::ustring);
-    StorageClientInterface::TransportState  state;
+    StorageClientInterface::AsyncState      state;
     
     int     iterations = 20;
     do {

livesupport/src/modules/storageClient/src/WebStorageClientTest.h

@@ -80,6 +80,7 @@ class WebStorageClientTest : public BaseTestMethod
     CPPUNIT_TEST(getAllTest);
     CPPUNIT_TEST(browseTest);
     CPPUNIT_TEST(createBackupTest);
+    CPPUNIT_TEST(restoreBackupTest);
     CPPUNIT_TEST(exportPlaylistTest);
     CPPUNIT_TEST(importPlaylistTest);
     CPPUNIT_TEST(remoteSearchTest);
@@ -187,6 +188,14 @@ class WebStorageClientTest : public BaseTestMethod
         void
         createBackupTest(void)                  throw (CPPUNIT_NS::Exception);
 
+        /**
+         *  Testing the restoreBackupXxxx() functions.
+         *
+         *  @exception CPPUNIT_NS::Exception on test failures.
+         */
+        void
+        restoreBackupTest(void)                 throw (CPPUNIT_NS::Exception);
+
         /**
          *  Testing the exportPlaylistXxxx() functions.
          *

livesupport/src/products/gLiveSupport/src/SearchWindow.cxx

@@ -558,7 +558,7 @@ SearchWindow :: remoteSearchClose(void)
                                 storage   = gLiveSupport->getStorageClient();
         Ptr<SessionId>::Ref     sessionId = gLiveSupport->getSessionId();
         
-        StorageClientInterface::TransportState      state;
+        StorageClientInterface::AsyncState          state;
         Ptr<Glib::ustring>::Ref                     errorMessage;
         try {
             state = storage->checkTransport(remoteSearchToken, errorMessage);

livesupport/src/products/gLiveSupport/src/TransportList.cxx

@@ -218,7 +218,7 @@ TransportList :: add(const Glib::ustring &          title,
     
     Ptr<Glib::ustring>::Ref     tokenPtr(new Glib::ustring(token));
     Ptr<Glib::ustring>::Ref     errorMsg(new Glib::ustring);
-    StorageClientInterface::TransportState
+    StorageClientInterface::AsyncState
                                 state = storage->checkTransport(tokenPtr,
                                                                 errorMsg);
     
@@ -321,7 +321,7 @@ TransportList :: update(Gtk::TreeIter   iter)           throw (XmlRpcException)
     Ptr<StorageClientInterface>::Ref 
                                 storage = gLiveSupport->getStorageClient();
     Ptr<Glib::ustring>::Ref     errorMsg(new Glib::ustring);
-    StorageClientInterface::TransportState
+    StorageClientInterface::AsyncState
                                 status = storage->checkTransport(
                                     iter->get_value(modelColumns.tokenColumn),
                                     errorMsg);
@@ -335,7 +335,7 @@ TransportList :: update(Gtk::TreeIter   iter)           throw (XmlRpcException)
  *----------------------------------------------------------------------------*/
 bool
 TransportList :: setStatus(Gtk::TreeIter                        iter,
-                           StorageClientInterface::TransportState   status,
+                           StorageClientInterface::AsyncState   status,
                            Ptr<const Glib::ustring>::Ref        errorMsg)
                                                                     throw ()
 {

livesupport/src/products/gLiveSupport/src/TransportList.h

@@ -112,7 +112,7 @@ class TransportList : public Gtk::VBox,
          */
         bool
         setStatus(Gtk::TreeIter                         iter,
-                  StorageClientInterface::TransportState    status,
+                  StorageClientInterface::AsyncState    status,
                   Ptr<const Glib::ustring>::Ref         errorMsg
                                             = Ptr<const Glib::ustring>::Ref())
                                                                 throw ();