[Phpgroupware-cvs] sync/inc/class.ipc_sync.inc.php, 1.13

[nomail]

Update of /sync/inc
Modified Files:
        Branch: 
          class.ipc_sync.inc.php

date: 2004/04/18 13:05:23;  author: mleonhardt;  state: Exp;  lines: +135 -100

Log Message:
- cleaning up code and extending docu
=====================================================================
No syntax errors detected in -
=====================================================================
Index: sync/inc/class.ipc_sync.inc.php
diff -u sync/inc/class.ipc_sync.inc.php:1.12 
sync/inc/class.ipc_sync.inc.php:1.13
--- sync/inc/class.ipc_sync.inc.php:1.12        Wed Apr 14 17:44:34 2004
+++ sync/inc/class.ipc_sync.inc.php     Sun Apr 18 13:05:23 2004
@@ -61,55 +61,69 @@
     $this->ipcManager =& CreateObject('phpgwapi.ipc_manager');
   }
 
- /**
-  * authenticate a user and device to phpGW to sync.
-  *
-  * @param string $username name of user to authenticate
-  * @param string $password clear text password of user to authenticate
-  * @param string $device_id is the device_id of the device which whant to 
-  *        do the sync
-  * @return int deviceid (db-entry-id) >= 0 if is successful 
-  */
+   /**
+    * authenticate a user and device to phpGW to sync.
+    *
+    * also writes a log entry to phpGroupware log
+    *
+    * @param string $username name of user to authenticate
+    * @param string $password clear text password of user to authenticate
+    * @param string $deviceid is the deviceid of the device which whant to 
+    *        do the sync
+    * @return array auth_info<br>
+    *  array(<br>
+    *   'result'    => integer deviceid (db-entry-id) >= 0 if is successful<br>
+    *   'sessionid' => string phpgw sessionid,<br>
+    *   'kp3'       => string phpgw session password (kp3)<br>
+    *  ) 
+    */
   
-    function authenticate($username, $password, $device_id) {
+    function authenticate($username, $password, $deviceid) {
     if ($this->debug)
-      error_log("authenticate device: [$username] [$device_id] [$password]");
+      error_log("authenticate device: [$username] [$deviceid] [$password]");
       
     if(is_object($GLOBALS['phpgw']->log))
     {
       $GLOBALS['phpgw']->log->message(array(
         'text' => 'I-authenticate, IPC.sync.authenticate: try authenticating 
device %1 for user ' . $username,
-        'p1'   => $device_id,
+        'p1'   => $deviceid,
         'line' => __LINE__,
         'file' => __FILE__
       ));
       $GLOBALS['phpgw']->log->commit();
     }
 
-    return $this->bo->AuthenticateSyncDevice($device_id, $username, $password);
+    return $this->bo->AuthenticateSyncDevice($deviceid, $username, $password);
   }
   
  /**
   * authorize a source for a given device add a channel if neccessary
   *
+  * we always allow access and request a new syncchannel<br>
+  * in a sync session first the device is authenticated with user and password,
+  * so we don't need to recheck the credentials for every source
+  *
   * @param string $username name of user to authenticate
-  * @param int $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
   * @param string $source Source-URI of the source to sync
-  * // !! todo: correct return parameter
-  * @return int channel_id (db-entry-id) >= 0 if is successful 
+  * @return integer channelid of newly added channel entry or existing one or 
-1 in case of error  
   */
   
-  function authorize($device_id, $source) {
+  function authorize($deviceid, $source) {
     if ($this->debug)
-      error_log("authorize source for device: [$device_id] [$source]");
+      error_log("authorize source for device: [$deviceid] [$source]");
       
-    return (int) $this->bo->AuthenticateSyncSource($device_id, $source);
+    return (integer) $this->bo->AuthenticateSyncSource($deviceid, $source);
   }
   
  /**
-  * TODO!! docu
-  * return array of source URI
+  * Get all sources actually supported by the phpgw syncmodule
+  *
+  * read from phpgw_syncsources
+  *
+  * @return array of string (source URIs, e.g. 'notes', './contact')
+  * 
   */
   
   function getSupportedSources() {
@@ -120,8 +134,14 @@
   }
 
  /**
-  * TODO!! docu
-  * get info about source
+  * Get source information about a given source (mimetype, version)
+  *
+  * @param string $source source name from device (e.g. 'contacts')
+  * @return array sourceinfo (array('contenttype' => $mimetype, 'version' => 
$mimeversion, 
+  * array[0..n] array of ('contenttype' => $mimetype, 'version' => 
$mimeversion))<br>
+  * First two entries of returnarray are the prefered type and version.<br> 
+  * The following array holds all supported types of the source 
+  * 
   */
   
   function getDataForSource($uri) {
@@ -134,22 +154,28 @@
  /**
   * get the principal-information by a given ID
   *
-  * @param string $device_URI is the device_id of the device which whant to 
+  * @param string $device_URI is the deviceid of the device which whant to 
   *        do the sync
-  * !! add return parameter and describe principal
+  * @return array deviceinfoarray 
+  *   array(<br>
+  *         'uri'=>unique identifier (e.g. EMSI) of the device,<br>
+  *         'username'=>phpgw username of the deviceowner,<br> 
+  *         'id'=>deviceid<br>
+  *          )<br> 
+  *   in case of error only id is set
   */
   
-  function readPrincipalByID($device_id) {
+  function readPrincipalByID($deviceid) {
     if ($this->debug)
-      error_log("readPricipalByID device: [$device_id]");
+      error_log("readPricipalByID device: [$deviceid]");
     
-    return $this->bo->readDeviceInfoByID($device_id);
+    return $this->bo->readDeviceInfoByID($deviceid);
   }
   
  /**
   * get one SyncItem from phpGW.
   *
-  * @param int $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
   * @param string $source source URI of the source to sync
   * @param string $LUID - the Items Unique Identifier ID (also called key)
@@ -160,11 +186,11 @@
   *  array[2] itemdata - returns the Item binary data
   */
   
-  function getSyncItemFromId($device_id, $source, $LUID, $mimetype) {
+  function getSyncItemFromId($deviceid, $source, $LUID, $mimetype) {
     if ($this->debug)
-      error_log("getSyncItemFromId: $device_id, $source, $LUID, $mimetype");
+      error_log("getSyncItemFromId: $deviceid, $source, $LUID, $mimetype");
 
-    return $this->bo->getSyncItemFromId($device_id, $source, $LUID, $mimetype);
+    return $this->bo->getSyncItemFromId($deviceid, $source, $LUID, $mimetype);
   }
   
  /**
@@ -173,7 +199,7 @@
   *        If the module
   *        changes the data or LUID (if it is new), then the new data
   *        and LUID is returned
-  * @param int $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
   * @param string $source Source-URI of the source to sync
   * @param string $LUID - the Items Unique Identifier ID (also called key)
@@ -182,17 +208,17 @@
   * @return boolean returns true if SyncItem is successful set
   */
   
-  function setSyncItem($device_id, $source, $LUID, $mimetype, $Itemdata) {
+  function setSyncItem($deviceid, $source, $LUID, $mimetype, $Itemdata) {
     if ($this->debug)
     {
       // distinguish between encoded data from XML-RPC and data from internal 
classes 
       if (is_array($Itemdata)) {
-        error_log("setSyncItem: $device_id, $source, $LUID, $mimetype |" . 
serialize($Itemdata));
-        return $this->bo->setSyncItem($device_id, $source, $LUID, $mimetype, 
$Itemdata);    
+        error_log("setSyncItem: $deviceid, $source, $LUID, $mimetype |" . 
serialize($Itemdata));
+        return $this->bo->setSyncItem($deviceid, $source, $LUID, $mimetype, 
$Itemdata);    
       } else
       {
-        error_log("setSyncItem: $device_id, $source, $LUID, $mimetype |" . 
base64_decode($Itemdata));
-        return $this->bo->setSyncItem($device_id, $source, $LUID, $mimetype, 
base64_decode($Itemdata));    
+        error_log("setSyncItem: $deviceid, $source, $LUID, $mimetype |" . 
base64_decode($Itemdata));
+        return $this->bo->setSyncItem($deviceid, $source, $LUID, $mimetype, 
base64_decode($Itemdata));    
       }
     }
   }
@@ -200,35 +226,37 @@
  /**
   * get all SyncItemIDs of this source (slow sync)
   *
-  * @param int $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
   * @param string $source Source-URI of the source to sync
-  * @return array returns an integer-array of all IDs 
+  * @return array returns an integer array of all IDs 
   */
   
-  function getAllSyncItemIds($device_id, $source) {
+  function getAllSyncItemIds($deviceid, $source) {
     if ($this->debug)
-      error_log("getAllSyncItemIds: $device_id, $source");
+      error_log("getAllSyncItemIds: $deviceid, $source");
 
-    return $this->bo->GetIDList($device_id, $source, 1);
+    return $this->bo->GetIDList($deviceid, $source, 1);
   }
   
  /**
-  * get all SyncItems of this source (slow sync)
+  * get all SyncItems of this source
+  *
+  * this function returns an array of syncitems requested by the $Ids 
parameter 
   *
-  * @param int $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
   * @param string $source Source-URI of the source to sync
-  * @return array returns an array of all (ID => Data) 
+  * @return array returns a linear array of all Items (ID => Data) 
   */
   
-  function getSyncItemsbyID($device_id, $source, $mimetype, $Ids) {
+  function getSyncItemsbyID($deviceid, $source, $mimetype, $Ids) {
     if ($this->debug)
-      error_log("getSyncItemsbyID: $device_id, $source, $mimetype, " . 
serialize($Ids));
+      error_log("getSyncItemsbyID: $deviceid, $source, $mimetype, " . 
serialize($Ids));
 
     $AllItems = array();
     foreach($Ids as $iID) {
-      $AllItems[] = $this->getSyncItemFromId($device_id, $source, $iID, 
$mimetype);
+      $AllItems[] = $this->getSyncItemFromId($deviceid, $source, $iID, 
$mimetype);
     }
     error_log("end of getSyncitemsByID: ". serialize($AllItems));
     return $AllItems;
@@ -237,87 +265,91 @@
  /**
   * get all deleted SyncItemIds since $since
   *
-  * @param int $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
   * @param string $source Source-URI of the source to sync
-  * @param int $since timestamp, since we want to delete Items
-  * @return array returns an integer-array of all deleted IDs 
+  * @param integer $since timestamp, since we want to delete Items
+  * @return array returns an integer array of all deleted IDs 
   */
   
-  function getDeletedSyncItemIds($device_id, $source, $since) {
+  function getDeletedSyncItemIds($deviceid, $source, $since) {
     if ($this->debug)
-      error_log("getDeletedSyncItems: $device_id, $source, $since");
+      error_log("getDeletedSyncItems: $deviceid, $source, $since");
              
-    return $this->bo->GetDeletedIDList($device_id, $source, $since);
+    return $this->bo->GetDeletedIDList($deviceid, $source, $since);
   }
   
  /**
   * get all new SyncItemIds since $since
   *
-  * @param $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
-  * @param $source Source-URI of the source to sync
-  * @param $since timestamp, since we want to get Items
+  * @param string $source Source-URI of the source to sync
+  * @param integer $since timestamp, since we want to get Items
   * @return array returns an integer-array of all new IDs 
   */
   
-  function getNewSyncItemIds($device_id, $source, $since) {
+  function getNewSyncItemIds($deviceid, $source, $since) {
     if ($this->debug)
-      error_log("getNewSyncItemIds: $device_id, $source, $since");
+      error_log("getNewSyncItemIds: $deviceid, $source, $since");
     
-    return $this->bo->GetIDList($device_id, $source, 2, $since);
+    return $this->bo->GetIDList($deviceid, $source, 2, $since);
   }
   
  /**
   * get all Updated SyncItemIds since $since
   *
-  * @param int $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
   * @param string $source Source-URI of the source to sync
-  * @param int $since timestamp, since we want to get Items
-  * @return array returns an integer-array of all updated LUIDs 
+  * @param integer $since unix timestamp, since we want to get Items
+  * @return array returns an integer array of all updated LUIDs 
   */
   
-  function getUpdatedSyncItemIds($device_id, $source, $since) {
+  function getUpdatedSyncItemIds($deviceid, $source, $since) {
     if ($this->debug)
-      error_log("getUpdatedSyncItemIds: $device_id, $source, $since");
+      error_log("getUpdatedSyncItemIds: $deviceid, $source, $since");
     
-    return $this->bo->GetIDList($device_id, $source, 3, $since);
+    return $this->bo->GetIDList($deviceid, $source, 3, $since);
   }
   
  /**
   * remove SyncItem with $LUID
   *
-  * @param int $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
   * @param string $source Source-URI of the source to sync
   * @param array $LUIDs - array of the Items Unique Identifier (string) IDs 
which are 
   *        to remove
-  * @return array returns an integer-array of all deleted IDs 
+  * @return array returns an integer array of all deleted IDs 
   */
   
-  function removeSyncItem($device_id, $source, $LUID) {
+  function removeSyncItem($deviceid, $source, $LUID) {
     if ($this->debug)
-      error_log("removeSyncItem: $device_id, $source, $LUID");
+      error_log("removeSyncItem: $deviceid, $source, $LUID");
       
-    return $this->bo->deleteMappingandItem($device_id, $source, $LUID);
+    return $this->bo->deleteMappingandItem($deviceid, $source, $LUID);
   }
 
  /**
   * return the timestamp of the last sync with this device
   *
-  * //TODO: params
-  * @param int $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
   * @param string $source Source-URI of the source to sync
-  * @return array returns an integer-array of all deleted IDs 
+  * @return array hasharray (<br>
+  *    "tag" => string time of last synchronisation, 0 in case of never 
+  *        (format: 20040416T172608Z)<br>
+  *    "start" => string syncstart unix timestamp of start of last 
synchronisation<br> 
+  *    "end" => string syncstop unix timestamp of start of last 
synchronisation<br>
+  *  )
   */
   
-  function readLastTimestamp($device_id, $source) {
+  function readLastTimestamp($deviceid, $source) {
     if ($this->debug)
-      error_log("readLastTimestamp: $device_id, $source");
+      error_log("readLastTimestamp: $deviceid, $source");
     
-    $timestamp = $this->so->GetTimestamp($device_id, $source);
+    $timestamp = $this->so->GetTimestamp($deviceid, $source);
     // return string because php doesn't handle long (don't want to use double)
     $result["tag"] = (string) $timestamp[0];
     $result["start"] = (string) $timestamp[1]; 
@@ -328,38 +360,38 @@
  /**
   * save the timestamp of the last sync with this device
   *
-  * //TODO: params
-  * @param int $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
   * @param string $source Source-URI of the source to sync
-  * @return dbID of the stored stamp or -1 in case of error 
+  * @param string $lastanchor time of last synchronisation, 0 in case of never 
+  *        (format: 20040416T172608Z)
+  * @param string $startsync unix timestamp of start of last synchronisation
+  * @param string $stopsync  unix timestamp of start of last synchronisation
+  * @return integer dbID of the stored stamp or -1 in case of error 
   */
   
-  function storeLastTimestamp($device_id, $source, $lastanchor, $startsync, 
$stopsync) {
+  function storeLastTimestamp($deviceid, $source, $lastanchor, $startsync, 
$stopsync) {
     if ($this->debug)
-      error_log("storeLastTimestamp: $device_id, $source, $lastanchor, 
$startsync, $stopsync");
+      error_log("storeLastTimestamp: $deviceid, $source, $lastanchor, 
$startsync, $stopsync");
     
-    return $this->so->SetTimestamp($device_id, $source, $lastanchor, 
$startsync, $stopsync);
+    return $this->so->SetTimestamp($deviceid, $source, $lastanchor, 
$startsync, $stopsync);
   }
   
  /**
-  * return the mapping of the last sync with this device
+  * return the mapping of the last sync with this device and source
   *
-  * //TODO: params
-  * @param int $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
   * @param string $source Source-URI of the source to sync
-  * @param array $LUIDs - array of the Items Unique Identifier (string) IDs 
which are 
-  *        to remove
-  * @return array returns an integer-array of all deleted IDs 
+  * @return array returns an linear integer array of all deleted IDs 
   */
   
-  function readClientMapping($device_id, $source) {
+  function readClientMapping($deviceid, $source) {
     if ($this->debug)
-      error_log("readClientMapping: $device_id, $source");
+      error_log("readClientMapping: $deviceid, $source");
     
     // get all Ids for this module
-    $LUIDs = $this->bo->GetIDList($device_id, $source, 1);
+    $LUIDs = $this->bo->GetIDList($deviceid, $source, 1);
 
     $result = array();
     foreach($LUIDs as $LUID) {
@@ -375,22 +407,25 @@
  /**
   * add mapping entries of the last sync with this device
   *
-  * //TODO: params
-  * @param int $device_id is the device_id of the device which whant to 
+  * @param integer $deviceid is the deviceid of the device which whant to 
   *        do the sync
   * @param string $source Source-URI of the source to sync
   * @param hasharray $mapping - array of the Items Unique Identifier (string) 
IDs which are 
-  *        to new
+  *        to new; array of (LUID => GUID)
   * @return boolean true if successful 
   */
   
-  function addClientMappings($device_id, $source, $mapping) {
+  function addClientMappings($deviceid, $source, $mapping) {
     if ($this->debug)
-      error_log("addClientMappings: $device_id, $source, $mapping");
+      error_log("addClientMappings: $deviceid, $source, $mapping");
     
     // add IDs
-    return  $this->bo->addClientMappings($device_id, $source, $mapping);
+    return  $this->bo->addClientMappings($deviceid, $source, $mapping);
   }
+  
+ /**
+  * TODO: documentation
+  */
   
   function handleConflict()
   {