[Phpgroupware-cvs] sync/inc/class.so_sync.inc.php, 1.24

[nomail]

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

date: 2004/04/18 10:51:40;  author: mleonhardt;  state: Exp;  lines: +123 -56

Log Message:
- cleaning up code and extending docu
=====================================================================
No syntax errors detected in -
=====================================================================
Index: sync/inc/class.so_sync.inc.php
diff -u sync/inc/class.so_sync.inc.php:1.23 sync/inc/class.so_sync.inc.php:1.24
--- sync/inc/class.so_sync.inc.php:1.23 Tue Apr  6 09:30:55 2004
+++ sync/inc/class.so_sync.inc.php      Sun Apr 18 10:51:40 2004
@@ -12,7 +12,7 @@
   */
 
  /**
-  * so_sync class for the storage objects
+  * so_sync class for the storage objects of the phpGroupware sync module
   *
   * @package  sync
   */
@@ -22,19 +22,21 @@
     /** functions for phpgw_syncdevices *******************************/
     /******************************************************************/
      
-               /**
+         /**
      * Get DeviceID for a device from device database
      *
      * @param string $URI unique identifier (e.g. EMSI) of the device
      * @param string $username name of the device owner (do not mix with phpGW 
username)
      * @param string $password password of the device owner (do not mix with 
phpGW password) 
-     * @return integer $DeviceID unique ID for internal devices database, -1 
in case of error or not found
+     * @return integer deviceid unique ID for internal devices database, 
+     *         -1 in case of error or not found
      */
        
        function GetDevice($URI, $username, $password)
     {
-      $GLOBALS['phpgw']->db->query("SELECT deviceid FROM phpgw_syncdevices 
WHERE URI='" .$URI. "' and username='".$username."' and 
password='".$password."'",__LINE__,__FILE__);
-                       $GLOBALS['phpgw']->db->next_record();
+      $GLOBALS['phpgw']->db->query("SELECT deviceid FROM phpgw_syncdevices 
WHERE URI='" .$URI. 
+                 "' and username='".$username."' and 
password='".$password."'",__LINE__,__FILE__);
+      $GLOBALS['phpgw']->db->next_record();
                        
       $id = $GLOBALS['phpgw']->db->f('deviceid');
                        if (isset($id))  
@@ -45,10 +47,13 @@
     
 
    /**
-    * Get DeviceID for a device from device database
+    * Get the phpgw DeviceID for a device from device database
+    *
+    * reads from table phpgw_sync_devices
     *
     * @param string $URI unique identifier (e.g. EMSI) of the device
-    * @return integer $DeviceID unique ID for internal devices database, -1 in 
case of error or not found
+    * @return integer DeviceID unique ID for internal devices database, 
+    *         -1 in case of error or not found
     */
     
     function GetDeviceID($URI)
@@ -64,10 +69,12 @@
     }
    
    /**
-    * Get AccountID for a device from device database
+    * Get AccountID for a device from device database 
     *
-    * @param  $URI unique identifier (e.g. EMSI) of the device
-    * @return integer $DeviceID unique ID for internal devices database, -1 in 
case of error or not found
+    * reads from table phpgw_syncdevices
+    *
+    * @param  $deviceid unique ID in internal devices database (table 
phpgw_syncdevices)
+    * @return integer accountid of phpgw account or -1 in case of error or not 
found
     */
     
     function GetAccountID($deviceid)
@@ -83,11 +90,13 @@
     }
     
    /**
-    * Get AccountID for a device from phpgw global user database (works only 
with sql-auth)
+    * Get AccountID of the user which owns a device from phpgw global user 
database 
+    *
+    * table phpgw_accounts; works only with sql-auth!
     *
     * @param string $username name of user to authenticate
     * @param string $password clear text password of user to authenticate
-    * @return integer $AccountID or boolean false in case of non existent 
useraccount
+    * @return integer accountid or boolean false in case of non existent 
useraccount
     */
     
     function GetAccountIDfromUsername($username, $password)
@@ -101,8 +110,13 @@
     }
 
    /**
-    * Get DeviceInfo a device from device database
-    * //!!
+    * Get DeviceInfo of a device from phpgw syncdevice database
+    *
+    * reads from table phpgw_syncdevices
+    *
+    * @param  $deviceid unique ID in internal devices database (table 
phpgw_syncdevices)
+    * @return array deviceinfoarray 'uri'=>unique identifier (e.g. EMSI) of 
the device, 'username'=>phpgw username of the deviceowner, 
+    *         integer -1 in case of error or not found
     */
     
     function GetDeviceInfo($deviceid)
@@ -121,17 +135,18 @@
     }
 
    /**
-    * Get all devices for a given phpGW user
+    * Get all devices of a given phpGW user
     *
-    * @param string $account_id internal phpGW account id (same as 
$GLOBALS['phpgw_info']['user']['account_id']) of the user who owns this device 
+    * @param string $accountid internal phpGW account id (same as 
$GLOBALS['phpgw_info']['user']['account_id'])
+    *        of the user who owns this device (table phpgw_syncdevices) 
     * @param array &$devicelist output var which holds the devicelist
     * @return boolean true if the user has devices
     */
     
-    function GetDeviceList($account_id, &$devicelist)
+    function GetDeviceList($accountid, &$devicelist)
     {
       $devicelist = array();
-      $result = $GLOBALS['phpgw']->db->query("SELECT deviceid, accountid, uri, 
description, username FROM phpgw_syncdevices WHERE 
accountid='".$account_id."'",__LINE__,__FILE__);
+      $result = $GLOBALS['phpgw']->db->query("SELECT deviceid, accountid, uri, 
description, username FROM phpgw_syncdevices WHERE 
accountid='".$accountid."'",__LINE__,__FILE__);
       while ($GLOBALS['phpgw']->db->next_record())
       {
         $devicelist[$GLOBALS['phpgw']->db->f('deviceid')] = array(
@@ -145,13 +160,17 @@
     }
 
    /**
-    * Add entry to syncdevice for a device, use 
+    * Add an entry for a device to phpgw_syncdevices
+    *
+    * if the useraccount exists in phpgw the device will added
     *
-    * @param string $account_id internal phpGW account id (same as 
$GLOBALS['phpgw_info']['user']['account_id']) of the user who owns this device 
+    * @param string $accountid internal phpGW account id (same as 
$GLOBALS['phpgw_info']['user']['account_id'])
+    *        of the user who owns this device 
     * @param string $URI unique identifier of the device
     * @param string $username name of user which owns the devices
     * @param string $password password of the device 
-    * @return boolean DeviceID of the new added device
+    * @return integer deviceid of the new added device or of the existing 
deviceentry
+    *        or -1 in case of error
     */
        
        function AddDevice($accountid, $URI, $username, $password)
@@ -173,18 +192,18 @@
     /**
      * Delete a Device with all connected ressources from the database
      *
-     * @param string $DeviceID unique internal identifier of the device
-     * @return boolean DeviceID of the deleted device
+     * @param string $deviceid unique internal identifier of the device
+     * @return integer deviceid of the deleted device
     */
 
-    function DeleteDevice($DeviceID)
+    function DeleteDevice($deviceid)
     {
       // todo: error handling
-      $GLOBALS['phpgw']->db->query("DELETE FROM phpgw_syncdevices WHERE 
deviceid='".$DeviceID."'",__LINE__,__FILE__);
+      $GLOBALS['phpgw']->db->query("DELETE FROM phpgw_syncdevices WHERE 
deviceid='".$deviceid."'",__LINE__,__FILE__);
       
       
-      $GLOBALS['phpgw']->db->query("DELETE FROM phpgw_syncdevices WHERE 
deviceid='".$DeviceID."'",__LINE__,__FILE__);
-      $GLOBALS['phpgw']->db->query("DELETE FROM phpgw_syncchannels WHERE 
deviceid='".$DeviceID."'",__LINE__,__FILE__);
+      $GLOBALS['phpgw']->db->query("DELETE FROM phpgw_syncdevices WHERE 
deviceid='".$deviceid."'",__LINE__,__FILE__);
+      $GLOBALS['phpgw']->db->query("DELETE FROM phpgw_syncchannels WHERE 
deviceid='".$deviceid."'",__LINE__,__FILE__);
       
       
       return $GLOBALS['phpgw']->db->f('deviceid');      
@@ -204,7 +223,7 @@
      * @param string $modulename phpGW application name
      * @param string $mimetype supported mimetype of the phpGW application
      * @param string $displayname Name to show in the list of sources in the 
UI     
-     * @return boolean SourceID of already existing or new entry
+     * @return integer SourceID of already existing or new entry
     */
          
     function AddSyncSource($URI, $modulename, $mimetype, $mimeversion, 
$displayname)
@@ -222,8 +241,8 @@
    /**
     * Get name of the corresponding phpGW application for a source URI
     *
-    * @param string $source  Source name from device (e.g. 'contacts')
-    * @return boolean Name of the phpGW application (e.g. 'addressbook')
+    * @param string $source source name from device (e.g. 'contacts')
+    * @return boolean name of the phpGW application (e.g. 'addressbook')
     * 
     */
     
@@ -240,7 +259,12 @@
     }
     
    /**
-    * !! add documentation
+    * 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()
@@ -255,7 +279,14 @@
     }
     
    /**
-    * !! add documentation
+    * 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 getSourceInfo($source)
@@ -281,10 +312,14 @@
     /******************************************************************/
     
    /**
-    * Get internal ChannelID from DeviceID (stored in principal in Sync4j) and 
Source
+    * Get ChannelID from DeviceID and Source
+    *
+    * this channelid should be used for any
+    * access to mapping etc. in the syncmodule (index field of table 
phpgw_syncchannels)
     * 
     * @param integer $deviceid unique device ID for internal devices database  
   
     * @param string  $source Source name from device (e.g. 'contacts')
+    * @return integer channelid or -1 in case of non existing channel or error 
     */
     function GetChannelIDfromSourceAndDeviceID($deviceid, $source)
     {
@@ -305,8 +340,8 @@
     * instead of adding a new one 
     * 
     * @param integer $deviceid unique device ID for internal devices database
-    * @param string $source Source name from device (e.g. 'contacts')
-    * @return integer ChannelID of newly added entry or existing one  
+    * @param string $source source name from device (e.g. 'contacts')
+    * @return integer channelid of newly added entry or existing one or -1 in 
case of error  
     */
     
     function AddSyncChannel($deviceid, $source)
@@ -328,14 +363,14 @@
     }
     
    /**
-    * Set Timestamp from device for existing channel
+    * Set Timestamp from device for an existing channel
     *
     * @param integer $deviceid unique device ID for internal devices database
     * @param string $source Source name from device (e.g. 'contacts')
     * @param string $lastanchor last anchor from sync device (see SyncML 
specification) 
     * @param string $startsync time stamp from sync device (see SyncML 
specification)
     * @param string $stopsnyc time stamp from sync device (see SyncML 
specification)
-    * @return integer $channelid ChannelID of the modified record  
+    * @return integer channelid of the modified source or -1 in case of error  
     */
        
     function SetTimestamp($deviceid, $source, $lastanchor, $startsync, 
$stopsync)
@@ -353,12 +388,15 @@
     }
     
    /**
-    * Get Timestamp for existing channel (given trough $deviceid and $source) 
-    * 
-    * !! add more documentation
+    * Get Timestamp for existing channel (given trough $deviceid and $source)
     *
+    * Timestamp consists of lastanchor (e.g. 20040416T172608Z), startsync 
(unix-timestamp in ms) 
+    * and stopsync (unix-timestamp in ms)  
+    * 
     * @param integer $deviceid unique device ID for internal devices database
     * @param string $source Source name from device (e.g. 'contacts')
+    * @return array timestamp [lastanchor, startsync, stopsync], in case of 
first sync for this channel  
+    *         array[0,0,0] will be returned which results in a slow/full sync  
  
     */
     
     function GetTimestamp($deviceid, $source)
@@ -383,9 +421,14 @@
     /******************************************************************/
     
    /**
-    * Get mappingid fgiven LUID, use ChannelID as reference
+    * Get mappingid for a given LUID, use ChannelID as reference
     *
-    * !! add more documentation
+    * mappings are stored in phpgw_syncmapping
+    *
+    * @param string $channelid reference to a source for a specific device 
+    * @param string $LUID local identifier of a record in the source (local 
recordid of the syncdevice) 
+    * @return integer mappingid (index of phpgw_syncmapping) to the given 
$LUID or -1 if there is 
+    *         no mapping yet  
     */
     
     function GetMappingID($channelid, $LUID)
@@ -404,7 +447,10 @@
    /**
     * Get matching GUID for given LUID, use ChannelID as reference
     *
-    * !! add more documentation
+    * @param integer $channelid unique sync channel reference to a source for 
a specific device 
+    * @param string $LUID local identifier of a record in the source (local 
recordid of the syncdevice) 
+    * @return string GUID (phpgw recordid) of a datarecord to the given $LUID 
or -1 if there is 
+    *         no mapping yet  
     */
     
     function GetGUID($channelid, $LUID)
@@ -425,6 +471,9 @@
     *
     * @param integer $deviceid unique device ID for internal devices database
     * @param string $source Source name from device (e.g. 'contacts')
+    * @param string $LUID local identifier of a record in the source (local 
recordid of the syncdevice) 
+    * @return string GUID (phpgw recordid) of a datarecord to the given $LUID 
or -1 if there is 
+    *         no mapping yet  
     */
     
     function GetGUIDExt($deviceid, $source, $LUID)
@@ -448,9 +497,9 @@
     /**
      * generate a temporary mapping (LUID) for new entries till we get a real 
from the device
      *
-     * @param Integer $channelid unique sync channel for a specific device and 
source 
+     * @param integer $channelid unique sync channel for a specific device and 
source 
      * @param string $GUID global unique Identifier for a data item to sync 
(phpgw DB-id) 
-     * @return string $LUID temporary local Identifier to send to sync-server
+     * @return string LUID temporary local Identifier to send to sync-server
      */
      
     function generateandsettempLUID($channelid, $GUID)
@@ -467,9 +516,13 @@
     
     /**
      * Add one entry to the internal mapping database, use given ChannelID
+     *
+     * stores in table phpgw_syncmapping
      * 
-     * @param Integer $channelid unique sync channel for a specific device and 
source 
-     * !! add more documentation
+     * @param integer $channelid unique sync channel for a specific device and 
source 
+     * @param string $GUID global unique Identifier for a data item to sync 
(phpgw DB-id) 
+     * @param string $LUID temporary local Identifier to send to sync-server
+     * @return integer new mappingid of the stored mapping
     */
 
     function AddMapping($channelid, $LUID, $GUID)
@@ -479,14 +532,18 @@
        return $GLOBALS['phpgw']->db->get_last_insert_id('phpgw_syncmapping', 
'channelid');
     }
     
-   /**
+    /**
     * Add one entry to the internal mapping database, use given DeviceID and 
Source
     *
+    * stores in table phpgw_syncmapping
+    *
     * @param integer $deviceid unique device ID for internal devices database
     * @param string  $source Source name from device (e.g. 'contacts')
-    * !! add more documentation
+    * @param string $GUID global unique Identifier for a data item to sync 
(phpgw DB-id) 
+    * @param string $LUID temporary local Identifier to send to sync-server
+    * @return integer new mappingid of the stored mapping or -1 in case of 
error (channel doesn't exist)
     */
-
+    
     function AddMappingExt($deviceid, $source, $LUID, $GUID)
     {
       $channelid = $this->GetChannelIDfromSourceAndDeviceID($deviceid, 
$source);
@@ -503,8 +560,12 @@
    /**
     * Set new $LUID for a given $GUID
     *
-    * @param integer $deviceid unique device ID for internal devices database
-    * @param string $source Source name from device (e.g. 'contacts')
+    * also replaces a temporary LUID ('_templuid'->'luid')
+    *
+    * @param integer $channelid unique sync channel for a specific device and 
source 
+    * @param string $GUID global unique Identifier for a data item to sync 
(phpgw DB-id) 
+    * @param string $LUID temporary local Identifier to send to sync-server
+    * @return boolean true if mapping set successfull
     */
        
     function SetLUID($channelid, $GUID, $LUID)
@@ -521,9 +582,12 @@
     }
 
    /**
-    * Get matching mappingid for given LUID
+    * Get matching LUID for given GUID, use ChannelID as reference
     *
-    * !! add more documentation
+    * @param integer $channelid unique sync channel for a specific device and 
source 
+    * @param string $GUID global unique Identifier for a data item to sync 
(phpgw DB-id) 
+    * @return string LUID local identifier of a record in the source (local 
recordid of the syncdevice)
+    *        or -1 if there is no mapping yet  
     */
     
     function GetLUID($channelid, $GUID)
@@ -540,7 +604,10 @@
     }
 
    /**
-    * !! add more documentation
+    * Delete mapping referenced by mappingid
+    *
+    * @param integer mappingid (index of phpgw_syncmapping)
+    * @return boolean true if successfull, false in case of error  
     */
 
     function DeleteMapping($mappingid)