Merge pull request #96 in ZP/z-push from feature/ZP-767-open-shared-folders-api to develop

* commit 'd6126a00':
  ZP-767 Added missing parameter doc.
  ZP-767 Fixed typos and suggestions.
  ZP-770 Fix typos.
  ZP-768 Check first on folder type, as it fails fast.
  ZP-770 Expose additional user folder API to ZPushAdmin class. Implement API in device webservice. Fixed typos.
  ZP-770 Expose additional user folder API to ZPushAdmin class. Implement API in device webservice. Fixed typos.
  ZP-769 Expose additional folders via DeviceManager, get user/device based additional folders from the ZPush class, make sure the NoBackendFlag is un/serialized correctly, write a FOLDERDATA (fd) state also for hierarchy states to retrieve the lastest sync counters.
  ZP-768 Get & Set additional folders into the ASDevice.

src/lib/core/asdevice.php

@@ -7,7 +7,7 @@
 *
 * Created   :   11.04.2011
 *
-* Copyright 2007 - 2013 Zarafa Deutschland GmbH
+* Copyright 2007 - 2015 Zarafa Deutschland GmbH
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License, version 3,
@@ -68,6 +68,7 @@ class ASDevice extends StateObject {
                                     'ignoredmessages' => array(),
                                     'announcedASversion' => false,
                                     'foldersynccomplete' => true,
+                                    'additionalfolders' => array(),
                                 );
 
     static private $loadedData;
@@ -686,4 +687,155 @@ class ASDevice extends StateObject {
         return true;
     }
 
+    /**----------------------------------------------------------------------------------------------------------
+     * Additional Folders operations
+     */
+
+    /**
+     * Returns a list of all additional folders of this device.
+     *
+     * @access public
+     * @return array
+     */
+    public function GetAdditionalFolders() {
+        return array_values($this->additionalfolders);
+    }
+
+    /**
+     * Returns an additional folder by folder ID.
+     *
+     * @param string    $folderid
+     *
+     * @access public
+     * @return array|false Returns a list of properties. Else false if folder id is unknown.
+     */
+    public function GetAdditionalFolder($folderid) {
+        // check if the $folderid is one of our own - this will in mostly NOT be the case, so we do not log here
+        if (!isset($this->additionalfolders[$folderid])) {
+            return false;
+        }
+
+        return $this->additionalfolders[$folderid];
+    }
+
+    /**
+     * Adds an additional folder to this device & user.
+     *
+     * @param string    $store      the store where this folder is located, e.g. "SYSTEM" (for public folder) or a username.
+     * @param string    $folderid   the folder id of the additional folder.
+     * @param string    $name       the name of the additional folder (has to be unique for all folders on the device).
+     * @param string    $type       AS foldertype of SYNC_FOLDER_TYPE_USER_*
+     *
+     * @access public
+     * @return boolean
+     */
+    public function AddAdditionalFolder($store, $folderid, $name, $type) {
+        // check if type is of a additional user type
+        if (!in_array($type, array(SYNC_FOLDER_TYPE_USER_CONTACT, SYNC_FOLDER_TYPE_USER_APPOINTMENT, SYNC_FOLDER_TYPE_USER_TASK, SYNC_FOLDER_TYPE_USER_MAIL, SYNC_FOLDER_TYPE_USER_NOTE, SYNC_FOLDER_TYPE_USER_JOURNAL))) {
+            ZLog::Write(LOGLEVEL_ERROR, sprintf("ASDevice->AddAdditionalFolder(): folder can not be added because the specified type '%s' is not a permitted user type.", $type));
+            return false;
+        }
+
+        // check if a folder with this ID is already in the list
+        if (isset($this->additionalfolders[$folderid])) {
+            ZLog::Write(LOGLEVEL_ERROR, sprintf("ASDevice->AddAdditionalFolder(): folder can not be added because there is already an additional folder with the same folder id: '%s'", $folderid));
+            return false;
+        }
+
+        // check if a folder with that Name is already in the list
+        foreach ($this->additionalfolders as $k => $folder) {
+            if ($folder['name'] == $name) {
+                ZLog::Write(LOGLEVEL_ERROR, sprintf("ASDevice->AddAdditionalFolder(): folder can not be added because there is already an additional folder with the same name: '%s'", $name));
+                return false;
+            }
+        }
+
+        // check if a folder with this ID or Name is already known on the device (regular folder)
+        foreach($this->GetHierarchyCache()->ExportFolders() as $syncedFolderid => $folder) {
+            if ($syncedFolderid == $folderid) {
+                ZLog::Write(LOGLEVEL_ERROR, sprintf("ASDevice->AddAdditionalFolder(): folder can not be added because there is already a folder with the same folder id synchronized: '%s'", $folderid));
+                return false;
+            }
+
+            // $folder is a SyncFolder object here
+            if ($folder->displayname == $name) {
+                ZLog::Write(LOGLEVEL_ERROR, sprintf("ASDevice->AddAdditionalFolder(): folder can not be added because there is already a folder with the same name synchronized: '%s'", $name));
+                return false;
+            }
+        }
+
+        // add the folder
+        $af = $this->additionalfolders;
+        $af[$folderid] = array(
+                            'store'     => $store,
+                            'folderid'  => $folderid,
+                            'name'      => $name,
+                            'type'      => $type,
+                         );
+        $this->additionalfolders = $af;
+
+        return true;
+    }
+
+    /**
+     * Edits (sets a new name) for an additional folder. Store, folderid and type can not be edited. Remove and add instead.
+     *
+     * @param string    $folderid   the folder id of the additional folder.
+     * @param string    $name       the name of the additional folder (has to be unique for all folders on the device).
+     *
+     * @access public
+     * @return boolean
+     */
+    public function EditAdditionalFolder($folderid, $name) {
+        // check if a folder with this ID is known
+        if (!isset($this->additionalfolders[$folderid])) {
+            ZLog::Write(LOGLEVEL_ERROR, sprintf("ASDevice->EditAdditionalFolder(): folder can not be edited because there is no folder known with this folder id: '%s'. Add the folder first.", $folderid));
+            return false;
+        }
+
+        // check if a folder with the new name is already in the list
+        foreach ($this->additionalfolders as $k => $folder) {
+            if ($folder['name'] == $name) {
+                ZLog::Write(LOGLEVEL_ERROR, sprintf("ASDevice->EditAdditionalFolder(): folder can not be added because there is already an additional folder with the same name: '%s'", $name));
+                return false;
+            }
+        }
+
+        // check if a folder with the new name is already known on the device (regular folder)
+        foreach($this->GetHierarchyCache()->ExportFolders() as $syncedFolderid => $folder) {
+            // $folder is a SyncFolder object here
+            if ($folder->displayname == $name) {
+                ZLog::Write(LOGLEVEL_ERROR, sprintf("ASDevice->EditAdditionalFolder(): folder can not be added because there is already a folder with the same name synchronized: '%s'", $folderid));
+                return false;
+            }
+        }
+
+        // update the name
+        $af = $this->additionalfolders;
+        $af[$folderid]['name'] = $name;
+        $this->additionalfolders = $af;
+
+        return true;
+    }
+
+    /**
+     * Removes an additional folder from this device & user.
+     *
+     * @access public
+     * @return boolean
+     */
+    public function RemoveAdditionalFolder($folderid) {
+        // check if a folder with this ID is known
+        if (!isset($this->additionalfolders[$folderid])) {
+            ZLog::Write(LOGLEVEL_ERROR, sprintf("ASDevice->RemoveAdditionalFolder(): folder can not be removed because there is no folder known with this folder id: '%s'", $folderid));
+            return false;
+        }
+
+        // remove the folder
+        $af = $this->additionalfolders;
+        unset($af[$folderid]);
+        $this->additionalfolders = $af;
+        return true;
+    }
+
 }

src/lib/core/devicemanager.php

@@ -10,7 +10,7 @@
 *
 * Created   :   11.04.2011
 *
-* Copyright 2007 - 2013 Zarafa Deutschland GmbH
+* Copyright 2007 - 2015 Zarafa Deutschland GmbH
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License, version 3,
@@ -403,6 +403,46 @@ class DeviceManager {
         return $class;
     }
 
+    /**
+     * Returns the additional folders as SyncFolder objects.
+     *
+     * @access public
+     * @return array of SyncFolder
+     */
+    public function GetAdditionalUserSyncFolders() {
+        $folders = array();
+        foreach($this->device->GetAdditionalFolders() as $df) {
+            $folder = new SyncFolder();
+            $folder->serverid = $df['folderid'];
+            $folder->parentid = 0;                  // only top folders are supported
+            $folder->displayname = $df['name'];
+            $folder->type = $df['type'];
+            // save store as custom property which is not streamed directly to the device
+            $folder->NoBackendFolder = true;
+            $folder->Store = $df['store'];
+
+            $folders[$folder->serverid] = $folder;
+        }
+        return $folders;
+    }
+
+    /**
+     * Get the store of an additional folder.
+     *
+     * @param string    $folderid
+     *
+     * @access public
+     * @return boolean|string
+     */
+    public function GetAdditionalUserSyncFolderStore($folderid) {
+        $f = $this->device->GetAdditionalFolder($folderid);
+        if ($f) {
+            return $f['store'];
+        }
+
+        return false;
+    }
+
     /**
      * Checks if the message should be streamed to a mobile
      * Should always be called before a message is sent to the mobile

src/lib/core/zpush.php

@@ -528,8 +528,9 @@ class ZPush {
      * @return array
      */
     static public function GetAdditionalSyncFolders() {
-        // TODO if there are any user based folders which should be synchronized, they have to be returned here as well!!
-        return self::$addSyncFolders;
+        // get user based folders which should be synchronized
+        $userFolder = self::GetDeviceManager()->GetAdditionalUserSyncFolders();
+        return array_merge(self::$addSyncFolders, $userFolder);
     }
 
     /**
@@ -542,7 +543,13 @@ class ZPush {
      * @return string
      */
     static public function GetAdditionalSyncFolderStore($folderid, $noDebug = false) {
-        $val = (isset(self::$addSyncFolders[$folderid]->Store))? self::$addSyncFolders[$folderid]->Store : false;
+        if(isset(self::$addSyncFolders[$folderid]->Store)) {
+            $val = self::$addSyncFolders[$folderid]->Store;
+        }
+        else {
+            $val = self::GetDeviceManager()->GetAdditionalUserSyncFolderStore($folderid);
+        }
+
         if (!$noDebug)
             ZLog::Write(LOGLEVEL_DEBUG, sprintf("ZPush::GetAdditionalSyncFolderStore('%s'): '%s'", $folderid, Utils::PrintAsString($val)));
         return $val;

src/lib/core/zpushdefs.php

@@ -6,7 +6,7 @@
 *
 * Created   :   01.10.2007
 *
-* Copyright 2007 - 2013 Zarafa Deutschland GmbH
+* Copyright 2007 - 2015 Zarafa Deutschland GmbH
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License, version 3,
@@ -324,6 +324,7 @@ define("SYNC_FOLDERHIERARCHY_COUNT","FolderHierarchy:Count");
 define("SYNC_FOLDERHIERARCHY_VERSION","FolderHierarchy:Version");
 // only for internal use - never to be streamed to the mobile
 define("SYNC_FOLDERHIERARCHY_IGNORE_STORE","FolderHierarchy:IgnoreStore");
+define("SYNC_FOLDERHIERARCHY_IGNORE_NOBCKENDFLD","FolderHierarchy:IgnoreNoBackendFolder");
 
 // MeetingResponse
 define("SYNC_MEETINGRESPONSE_CALENDARID","MeetingResponse:CalendarId");

src/lib/request/folderchange.php

@@ -6,7 +6,7 @@
 *
 * Created   :   16.02.2012
 *
-* Copyright 2007 - 2013 Zarafa Deutschland GmbH
+* Copyright 2007 - 2015 Zarafa Deutschland GmbH
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License, version 3,
@@ -121,6 +121,9 @@ class FolderChange extends RequestProcessor {
             $syncstate = self::$deviceManager->GetStateManager()->GetSyncState($synckey);
             $newsynckey = self::$deviceManager->GetStateManager()->GetNewSyncKey($synckey);
 
+            // there are no SyncParameters for the hierarchy, but we use it to save the latest synckeys
+            $spa = self::$deviceManager->GetStateManager()->GetSynchedFolderState(false);
+
             // Over the ChangesWrapper the HierarchyCache is notified about all changes
             $changesMem = self::$deviceManager->GetHierarchyChangesWrapper();
 
@@ -238,9 +241,14 @@ class FolderChange extends RequestProcessor {
         self::$topCollector->AnnounceInformation(sprintf("Operation status %d", $status), true);
 
         // Save the sync state for the next time
-        if (isset($importer))
+        if (isset($importer)) {
             self::$deviceManager->GetStateManager()->SetSyncState($newsynckey, $importer->GetState());
 
+            // update SPA & save it
+            $spa->SetSyncKey($newsynckey);
+            self::$deviceManager->GetStateManager()->SetSynchedFolderState($spa);
+        }
+
         return true;
     }
 }

src/lib/request/foldersync.php

@@ -81,6 +81,9 @@ class FolderSync extends RequestProcessor {
 
             // We will be saving the sync state under 'newsynckey'
             $newsynckey = self::$deviceManager->GetStateManager()->GetNewSyncKey($synckey);
+
+            // there are no SyncParameters for the hierarchy, but we use it to save the latest synckeys
+            $spa = self::$deviceManager->GetStateManager()->GetSynchedFolderState(false);
         }
         catch (StateNotFoundException $snfex) {
                 $status = SYNC_FSSTATUS_SYNCKEYERROR;
@@ -257,8 +260,13 @@ class FolderSync extends RequestProcessor {
                 self::$topCollector->AnnounceInformation(sprintf("Outgoing %d folders",$changeCount), true);
 
                 // everything fine, save the sync state for the next time
-                if ($synckey == $newsynckey)
+                if ($synckey == $newsynckey) {
                     self::$deviceManager->GetStateManager()->SetSyncState($newsynckey, $newsyncstate);
+
+                    // update SPA & save it
+                    $spa->SetSyncKey($newsynckey);
+                    self::$deviceManager->GetStateManager()->SetSynchedFolderState($spa);
+                }
             }
         }
         self::$encoder->endTag();

src/lib/syncobjects/syncfolder.php

@@ -10,7 +10,7 @@
 *
 * Created   :   05.09.2011
 *
-* Copyright 2007 - 2013 Zarafa Deutschland GmbH
+* Copyright 2007 - 2015 Zarafa Deutschland GmbH
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License, version 3,
@@ -52,6 +52,7 @@ class SyncFolder extends SyncObject {
     public $displayname;
     public $type;
     public $Store;
+    public $NoBackendFolder;
 
     function SyncFolder() {
         $mapping = array (
@@ -71,6 +72,9 @@ class SyncFolder extends SyncObject {
 
                     SYNC_FOLDERHIERARCHY_IGNORE_STORE                   => array (  self::STREAMER_VAR      => "Store",
                                                                                     self::STREAMER_TYPE     => self::STREAMER_TYPE_IGNORE),
+
+                    SYNC_FOLDERHIERARCHY_IGNORE_NOBCKENDFLD             => array (  self::STREAMER_VAR      => "NoBackendFolder",
+                                                                                    self::STREAMER_TYPE     => self::STREAMER_TYPE_IGNORE),
                 );
 
         parent::SyncObject($mapping);

src/lib/webservice/webservicedevice.php

@@ -8,7 +8,7 @@
 *
 * Created   :   23.12.2011
 *
-* Copyright 2007 - 2013 Zarafa Deutschland GmbH
+* Copyright 2007 - 2015 Zarafa Deutschland GmbH
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License, version 3,
@@ -146,13 +146,111 @@ class WebserviceDevice {
         $deviceId = preg_replace("/[^A-Za-z0-9]/", "", $deviceId);
         $folderId = preg_replace("/[^A-Za-z0-9]/", "", $folderId);
         ZLog::Write(LOGLEVEL_INFO, sprintf("WebserviceDevice::ResyncFolder('%s','%s'): mark folder of a device of user '%s' for resynchronization", $deviceId, $folderId, Request::GetGETUser()));
-    
+
         if (! ZPushAdmin::ResyncFolder(Request::GetGETUser(), $deviceId, $folderId)) {
             ZPush::GetTopCollector()->AnnounceInformation(ZLog::GetLastMessage(LOGLEVEL_ERROR), true);
             throw new SoapFault("ERROR", ZLog::GetLastMessage(LOGLEVEL_ERROR));
         }
-    
+
         ZPush::GetTopCollector()->AnnounceInformation(sprintf("Folder resync requested - device id '%s', folder id '%s", $deviceId, $folderId), true);
         return true;
     }
+
+    /**
+     * Returns a list of all additional folders of the given device and the Request::GetGETUser().
+     *
+     * @param string    $deviceId       device id that should be listed.
+     *
+     * @access public
+     * @return array
+     */
+    public function AdditionalFolderList($deviceId) {
+        $user = Request::GetGETUser();
+        $deviceId = preg_replace("/[^A-Za-z0-9]/", "", $deviceId);
+        $folders = ZPushAdmin::AdditionalFolderList($user, $deviceId);
+        ZLog::Write(LOGLEVEL_INFO, sprintf("WebserviceDevice::AdditionalFolderList(): found %d folders for device '%s' of user '%s'", count($folders), $deviceId, $user));
+        ZPush::GetTopCollector()->AnnounceInformation(sprintf("Retrieved details of %d folders", count($folders)), true);
+
+        return $folders;
+    }
+
+    /**
+     * Adds an additional folder to the given device and the Request::GetGETUser().
+     *
+     * @param string    $deviceId       device id the folder should be added to.
+     * @param string    $add_store      the store where this folder is located, e.g. "SYSTEM" (for public folder) or an username/email address.
+     * @param string    $add_folderid   the folder id of the additional folder.
+     * @param string    $add_name       the name of the additional folder (has to be unique for all folders on the device).
+     * @param string    $add_type       AS foldertype of SYNC_FOLDER_TYPE_USER_*
+     *
+     * @access public
+     * @return boolean
+     */
+    public function AdditionalFolderAdd($deviceId, $add_store, $add_folderid, $add_name, $add_type) {
+        $user = Request::GetGETUser();
+        $deviceId = preg_replace("/[^A-Za-z0-9]/", "", $deviceId);
+        $add_folderid = preg_replace("/[^A-Za-z0-9]/", "", $add_folderid);
+        $add_type = preg_replace("/[^0-9]/", "", $add_type);
+
+        $status = ZPushAdmin::AdditionalFolderAdd($user, $deviceId, $add_store, $add_folderid, $add_name, $add_type);
+        if (!$status) {
+            ZPush::GetTopCollector()->AnnounceInformation(ZLog::GetLastMessage(LOGLEVEL_ERROR), true);
+            throw new SoapFault("ERROR", ZLog::GetLastMessage(LOGLEVEL_ERROR));
+        }
+        ZLog::Write(LOGLEVEL_INFO, sprintf("WebserviceDevice::AdditionalFolderAdd(): added folder for device '%s' of user '%s': %s", $deviceId, $user, Utils::PrintAsString($status)));
+        ZPush::GetTopCollector()->AnnounceInformation("Added additional folder", true);
+
+        return $status;
+    }
+
+    /**
+     * Updates the name of an additional folder to the given device and the Request::GetGETUser().
+     *
+     * @param string    $deviceId       device id of where the folder should be updated.
+     * @param string    $add_folderid   the folder id of the additional folder.
+     * @param string    $add_name       the name of the additional folder (has to be unique for all folders on the device).
+     *
+     * @access public
+     * @return boolean
+     */
+    public function AdditionalFolderEdit($deviceId, $add_folderid, $add_name) {
+        $user = Request::GetGETUser();
+        $deviceId = preg_replace("/[^A-Za-z0-9]/", "", $deviceId);
+        $add_folderid = preg_replace("/[^A-Za-z0-9]/", "", $add_folderid);
+
+        $status = ZPushAdmin::AdditionalFolderEdit($user, $deviceId, $add_folderid, $add_name);
+        if (!$status) {
+            ZPush::GetTopCollector()->AnnounceInformation(ZLog::GetLastMessage(LOGLEVEL_ERROR), true);
+            throw new SoapFault("ERROR", ZLog::GetLastMessage(LOGLEVEL_ERROR));
+        }
+        ZLog::Write(LOGLEVEL_INFO, sprintf("WebserviceDevice::AdditionalFolderEdit(): added folder for device '%s' of user '%s': %s", $deviceId, $user, Utils::PrintAsString($status)));
+        ZPush::GetTopCollector()->AnnounceInformation("Edited additional folder", true);
+
+        return $status;
+    }
+
+    /**
+     * Removes an additional folder from the given device and the Request::GetGETUser().
+     *
+     * @param string    $deviceId       device id of where the folder should be removed.
+     * @param string    $add_folderid   the folder id of the additional folder.
+     *
+     * @access public
+     * @return boolean
+     */
+    public function AdditionalFolderRemove($deviceId, $add_folderid) {
+        $user = Request::GetGETUser();
+        $deviceId = preg_replace("/[^A-Za-z0-9]/", "", $deviceId);
+        $add_folderid = preg_replace("/[^A-Za-z0-9]/", "", $add_folderid);
+
+        $status = ZPushAdmin::AdditionalFolderRemove($user, $deviceId, $add_folderid);
+        if (!$status) {
+            ZPush::GetTopCollector()->AnnounceInformation(ZLog::GetLastMessage(LOGLEVEL_ERROR), true);
+            throw new SoapFault("ERROR", ZLog::GetLastMessage(LOGLEVEL_ERROR));
+        }
+        ZLog::Write(LOGLEVEL_INFO, sprintf("WebserviceDevice::AdditionalFolderRemove(): removed folder for device '%s' of user '%s': %s", $deviceId, $user, Utils::PrintAsString($status)));
+        ZPush::GetTopCollector()->AnnounceInformation("Removed additional folder", true);
+
+        return $status;
+    }
 }