Add example activesync_device_modify hook.

horde/config/hooks.php.dist

@@ -267,7 +267,7 @@
  *
  * activesync_device_check
  * -----------------------
- * This hooks allows the enforcement of arbitrary device policies like E.g.,
+ * This hook allows the enforcement of arbitrary device policies like E.g.,
  * not allowing certain user agents to connect, or only allowing certain user
  * agents for certain users etc...
  *
@@ -281,6 +281,20 @@
  *   [integer] A Horde_ActiveSync_Status:: constant identifying the reason for
  *             disallowing the device.
  *
+ * activesync_device_modify
+ * ------------------------
+ * This hook gives the chance to modify the device object before the request is
+ * handled. This can be used, for instance, in forcing certain devices to always
+ * use multiplexed collections for certain collection types, while other devices
+ * are allowed to use non-multiplexed collections.
+ *
+ * Parameters in:
+ *   $device (Horde_ActiveSync_Device):  The device object.
+ *
+ * The return value from this hook is as follows:
+ *   [throw Horde_Exception] - Fatal error.
+ *   [Horde_ActiveSync_Device]  The possibly modified device object.
+ *
  * TODO: groupldap, share_add, share_modify, share_remove
  *
  * $Id$
@@ -1013,5 +1027,75 @@ class Horde_Hooks
    //    return true;
    // }
 
+   /**
+    * Hook for modifying the device object prior to request processing. The
+    * device object is fully populated here, so you have access to all
+    * properties:
+    *   - id:         The device id.
+    *   - policykey:  The device's policy key, if provisioned.
+    *   - userAgent:  The device's user agent string.
+    *   - multiplex:  Bitmask for forced multiplex collections.
+    *                 @see Horde_ActiveSync_Device
+    *   - version:    The EAS version in use by the device.
+    *   - properties: A hash containing the following key/values (note that not
+    *                 all devices provide all values):
+    *       - Horde_ActiveSync_Device::MODEL:         => The model name.
+    *       - Horde_ActiveSync_Device::IMEI:          => The device's IMEI #.
+    *       - Horde_ActiveSync_Device::NAME:          => The device's common
+    *                                                    name.
+    *       - Horde_ActiveSync_Device::OS:            => The device's OS.
+    *       - Horde_ActiveSync_Device::OS_LANGUAGE    => The language.
+    *       - Horde_ActiveSync_Device::PHONE_NUMBER   => The phone number.
+    *
+    * @param Horde_ActiveSync_Device $device  The device object.
+    *
+    * @return Horde_ActiveSync_Device  The possibly modified device object.
+    */
+   public function activesync_device_modify(Horde_ActiveSync_Device $device)
+   {
+        // Example for forcing certain device to force multiplexed collections
+        // for collection types they don't support multiple collections for.
+        // Note that this doesn't apply to email folders, which are NEVER
+        // sent multiplexed.
+
+        // iOS seems to support multiple collections for everything except
+        // Notes.
+        if (strpos($device->userAgent, 'iOS') === 0 ) {
+            $device->multiplex =
+                Horde_ActiveSync_Device::MULTIPLEX_NOTES;
+        }
+
+        // For this example, just flag android devices as requiring
+        // multiplexed data for all collections. Probably some version sniffing
+        // or manufacturer sniffing to be done here.
+        if (strpos($device->userAgent, 'Android') !== false) {
+            $device->multiplex =
+                Horde_ActiveSync_Device::MULTIPLEX_NOTES |
+                Horde_ActiveSync_Device::MULTIPLEX_CONTACTS |
+                Horde_ActiveSync_Device::MULTIPLEX_CALENDAR |
+                Horde_ActiveSync_Device::MULTIPLEX_TASKS;
+        }
+
+        // Windows Phone. For the devices I've tested, it seems that
+        // only multiple tasklists are accepted. The rest must be
+        // multiplexed.
+        if (strpos($device->userAgent, 'MSFT-WP/8.0') !== false || $device->deviceType == 'WP8') {
+            $device->multiplex =
+                Horde_ActiveSync_Device::MULTIPLEX_CONTACTS |
+                Horde_ActiveSync_Device::MULTIPLEX_CALENDAR;
+        }
+
+        // PocketPC versions seem to not support any user defined
+        // collections at all, though I've only tested on a single HTC device.
+        if (strpos($device->userAgent, 'MSFT-PPC') !== false || $device->deviceType == 'PocketPC') {
+            $device->multiplex =
+                Horde_ActiveSync_Device::MULTIPLEX_CONTACTS |
+                Horde_ActiveSync_Device::MULTIPLEX_CALENDAR |
+                Horde_ActiveSync_Device::MULTIPLEX_NOTES |
+                Horde_ActiveSync_Device::MULTIPLEX_TASKS;
+        }
+
+        return $device;
+   }
 
 }