[Phpgroupware-cvs] sync/inc/class.bo_sync.inc.php, 1.26

[nomail]

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

date: 2004/04/18 12:37:44;  author: mleonhardt;  state: Exp;  lines: +70 -48

Log Message:
- cleaning up code and extending docu
=====================================================================
No syntax errors detected in -
=====================================================================
Index: sync/inc/class.bo_sync.inc.php
diff -u sync/inc/class.bo_sync.inc.php:1.25 sync/inc/class.bo_sync.inc.php:1.26
--- sync/inc/class.bo_sync.inc.php:1.25 Wed Apr 14 17:47:03 2004
+++ sync/inc/class.bo_sync.inc.php      Sun Apr 18 12:37:44 2004
@@ -12,7 +12,7 @@
   */
  
  /**
-  * bo_sync class for the business objects
+  * bo_sync class for the business objects of phpGroupware sync module
   *
   * @package  sync
   */
@@ -65,20 +65,24 @@
     *
     * @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 
+    * @param string $deviceid is the deviceid of the device which whant to 
     *        do the sync
-    * //!! Todo: return parameter is array
-    * @return int deviceid (db-entry-id) >= 0 if is successful 
+    * @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 AuthenticateSyncDevice($URI, $username, $password)
     {
-      $device_id = $this->so->GetDevice($URI, $username, $password);
+      $deviceid = $this->so->GetDevice($URI, $username, $password);
       $phpgw_accountid = $this->so->GetAccountIDfromUsername($username, 
$password);
-      if ($device_id >= 0)
+      if ($deviceid >= 0)
       {
         // device already exists
-        $ret = $device_id;
+        $ret = $deviceid;
       } else {
          // compare to phpGW username/password -> add device, if user exists
          if ($GLOBALS['phpgw']->auth->authenticate($username, $password, 
'text'))
@@ -106,30 +110,49 @@
     }
     
    /**
-    * documentation!!
+    * Authenticate a given source at the phpgw sync module
+    * 
+    * 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
+    *
+    * This function checks for an existing entry first and gives this channelid
+    * 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 or -1 in 
case of error  
     */
     
-    function AuthenticateSyncSource($device_id, $source)
+    function AuthenticateSyncSource($deviceid, $source)
     {
-        return (int) $this->so->AddSyncChannel($device_id, $source);
+        return (int) $this->so->AddSyncChannel($deviceid, $source);
     }
 
     
    /**
     * get the Device-information by a given ID
     *
-    * @param string $device_URI is the device_id of the device which whant to 
-    *        do the sync
-    * @return !!TODO
+    * Get DeviceInfo of a device from phpgw syncdevice database<br>
+    * reads from table phpgw_syncdevices
+    *
+    * @param  $deviceid unique ID in internal devices database (table 
phpgw_syncdevices)
+    * @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 readDeviceInfoByID($device_id) {
+    function readDeviceInfoByID($deviceid) {
       if ($this->debug)
-        error_log("readPrincipalByID device: [$device_id]");
+        error_log("readPrincipalByID device: [$deviceid]");
 
-      $result = $this->so->GetDeviceInfo($device_id);
+      $result = $this->so->GetDeviceInfo($deviceid);
       if (! is_array($result)) return array();
-      $result["id"] = $device_id;
+      $result["id"] = $deviceid;
       return $result;
     }
     
@@ -137,7 +160,7 @@
    /**
     * 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)
@@ -150,14 +173,14 @@
     *  array[2] itemdata - returns the Item binary data
     */
   
-    function getSyncItemFromId($device_id, $source, $LUID, $mimetype) {
+    function getSyncItemFromId($deviceid, $source, $LUID, $mimetype) {
       // get the responsible IPC class
       //TODO: error-handling!
       $this->GetIpcforSource($source);
 
       // get the mapped GUID
       //TODO: Errorhandling!
-      $GUID = $this->so->getGUIDExt($device_id, $source, $LUID);
+      $GUID = $this->so->getGUIDExt($deviceid, $source, $LUID);
       
       if ($GUID == -1)
       {
@@ -171,7 +194,7 @@
        // temporary work around for palm vcard problem: palm uses vcard 3.0, 
others 2.1 (Weblicon Client)
        // will be replaced by mime version handling from device information 
later
         // Synthesis uses also 3.0 for PocketPC
-       $devinfo = $this->so->GetDeviceInfo($device_id);
+       $devinfo = $this->so->GetDeviceInfo($deviceid);
        if ((strpos($devinfo['uri'], "Palm") > 0) || (strpos($devinfo['uri'], 
"ebliconSync_") > 0) 
           || strlen($devinfo['uri'] == 20))
          $data = $this->ipc->getData($GUID, $mimetype, '3.0');
@@ -201,21 +224,21 @@
     *        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)
     * @param string $mimetype - holds the mimetype of Itemdata
     * @param mixed $Itemdata - holds the Item binary data (base64encoded)
-    * @return boolean returns true if SyncItem is successful set
+    * @return boolean true if SyncItem is successful set
     */
   
-    function setSyncItem($device_id, $source, $LUID, $mimetype, $Itemdata) {
+    function setSyncItem($deviceid, $source, $LUID, $mimetype, $Itemdata) {
       // set the responsible IPC class of the responsible module
       if ($this->GetIpcforSource($source) == false) return false;
   
       // get the mapped GUID
-      $GUID = $this->so->getGUIDExt($device_id, $source, $LUID);
+      $GUID = $this->so->getGUIDExt($deviceid, $source, $LUID);
       if ($GUID == -1)
       {
         // no GUID found -> then we have to replace not add
@@ -226,7 +249,7 @@
         {
           // set new GUID
           // TODO ErrorHandling!!
-          $this->so->addMappingExt($device_id, $source, $LUID, $result);
+          $this->so->addMappingExt($deviceid, $source, $LUID, $result);
         }
       }
       else
@@ -251,8 +274,9 @@
    /**
     * switches the actual user (relogin as a new user) 
     *
-    * !! This function works only with SQL managed accounts but not with LDAP!
-    * // !!
+    * @param integer $deviceid is the deviceid of the device which whant to 
+    *        do the sync
+    * @return string new sessionid 
     */
     
     function SwitchUser($deviceid)
@@ -277,6 +301,7 @@
     *
     *        if GetSourceModule returns a mapped name of a phpgw module,
     *        the ipc class of this modul will be returned
+    *
     * @param string $source Source-URI of the source to sync
     * @return string sets $self->ipc to the responsible ipc class of the 
requested $source
     *         and returns the application name the $source otherwise 
@@ -298,18 +323,18 @@
     * get an array of LUIDs 
     *
     *        depending on the $type this routine returns an array of LUIDs
-    * @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 $type 1: all IDs; 2: all new IDs; 3: all changed IDs
-    * @param int $lastmod optional parameter for a timestamp at the last 
change to the data
+    * @param integer $type 1: all IDs; 2: all new IDs; 3: all changed IDs
+    * @param integer $lastmod optional parameter for a timestamp at the last 
change to the data
     * @return array returns an array of string (LUIDs)
     */
   
-    function GetIDList($device_id, $source, $type, $lastmod = -1)
+    function GetIDList($deviceid, $source, $type, $lastmod = -1)
     {
       // cache channelid for our $deviceid and $source
-      $channelid = $this->so->GetChannelIDfromSourceAndDeviceID($device_id, 
$source);
+      $channelid = $this->so->GetChannelIDfromSourceAndDeviceID($deviceid, 
$source);
       
       //TODO: error-handling!
       $this->GetIpcforSource($source);
@@ -349,17 +374,17 @@
    /**
     * get an array of deleted LUIDs 
     *
-    * @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 string (LUIDs)
     */
   
-    function GetDeletedIdList($device_id, $source)
+    function GetDeletedIdList($deviceid, $source)
     {
       $GLOBALS['phpgw']->db->query('SELECT luid, guid, mappingid ' .
          'FROM phpgw_syncmapping, phpgw_syncchannels,phpgw_syncsources ' .
-         "WHERE phpgw_syncsources.uri='$source' and 
phpgw_syncchannels.deviceid='$device_id' ".
+         "WHERE phpgw_syncsources.uri='$source' and 
phpgw_syncchannels.deviceid='$deviceid' ".
          "and phpgw_syncchannels.sourceid = phpgw_syncsources.sourceid and ".
          "phpgw_syncmapping.channelid = phpgw_syncchannels.channelid",
          __LINE__,__FILE__);
@@ -399,18 +424,17 @@
    /**
     * 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 
+    * @param hasharray $mapping array of the Items Unique Identifier (string) 
IDs which are 
     *        to new
     * @return boolean true if successful 
     */
     
-    function addClientMappings($device_id, $source, $mapping) {
+    function addClientMappings($deviceid, $source, $mapping) {
       // cache channelid for our $deviceid and $source
-      $channelid = $this->so->GetChannelIDfromSourceAndDeviceID($device_id, 
$source);
+      $channelid = $this->so->GetChannelIDfromSourceAndDeviceID($deviceid, 
$source);
       error_log("channelid: $channelid");
       
       foreach($mapping as $LUID => $GUID)
@@ -426,19 +450,17 @@
    /**
     * delete mapping entries of a given LUID
     *
-    * //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
+    * @param string LUID local unique identifier (devicespecific id)
     * @return boolean true if successful 
     */
     
-    function deleteMappingandItem($device_id, $source, $LUID) {
+    function deleteMappingandItem($deviceid, $source, $LUID) {
       $result = false;
       // cache channelid for our $deviceid and $source
-      $channelid = $this->so->GetChannelIDfromSourceAndDeviceID($device_id, 
$source);
+      $channelid = $this->so->GetChannelIDfromSourceAndDeviceID($deviceid, 
$source);
       
       if ($this->debug)
         error_log("deleteMapping: removing Mapping and Item $LUID");