SQL based state management. Responsible for maintaining device state information such as last sync time, provisioning status, client-sent changes, and for calculating deltas between server and client.
Needs a number of SQL tables present: syncStateTable (horde_activesync_state): sync_timestamp: - The timestamp of last sync sync_key: - The syncKey for the last sync sync_pending: - If the last sync resulted in a MOREAVAILABLE, this contains a list of UIDs that still need to be sent to the client. sync_data: - Any state data that we need to track for the specific syncKey. Data such as current folder list on the client (for a FOLDERSYNC) and IMAP email UIDs (for Email collections during a SYNC). sync_devid: - The device id. sync_folderid:- The folder id for this sync. sync_user: - The user for this synckey. sync_mod: - The last modification stamp.
syncMapTable (horde_activesync_map): message_uid - The server uid for the object sync_modtime - The time the change was received from the client and applied to the server data store. sync_key - The syncKey that was current at the time the change was received. sync_devid - The device id this change was done on. sync_user - The user that initiated the change.
syncDeviceTable (horde_activesync_device): device_id - The unique id for this device device_type - The device type the client identifies itself with device_agent - The user agent string sent by the device device_policykey - The current policykey for this device device_rwstatus - The current remote wipe status for this device
syncUsersTable (horde_activesync_device_users): device_user - A username attached to the device device_id - The device id device_policykey - The provisioned policykey for this device/user combination.
$_collection : array
The collection array for the collection we are currently syncing.
Keys include:
$_deviceInfo : \Horde_ActiveSync_Device
Device object.
__construct(array $params = array()) : \Horde_ActiveSync_State_Sql
Const'r
| array | $params | Must contain:
|
setBackend(\Horde_ActiveSync_Driver_Base $backend) : void
Set the backend driver (should really only be called by a backend object when passing this object to client code)
| \Horde_ActiveSync_Driver_Base | $backend | The backend driver |
isConflict(array $stat, string $type) : boolean
Determines if the server version of the message represented by $stat conflicts with the client version of the message. For this driver, this is true whenever $lastSyncTime is older then $stat['mod']. Method is only called from the Importer during an import of a non-new change from the client.
| array | $stat | A message stat array |
| string | $type | The type of change (change, delete, add) |
getFolderUidForBackendId(string $serverid) : string|boolean
Get a EAS Folder Uid for the given backend server id.
| string | $serverid | The backend server id. E.g., 'INBOX'. |
The EAS UID for the requested serverid, or false if it is not found.
getChanges(array $options = array()) : array
Get all items that have changed since the last sync time
| array | $options | An options array:
|
An array of hashes describing each change:
getNewSyncKey(string $syncKey) : string
Gets the new sync key for a specified sync key. You must save the new sync state under this sync key when done sync'ing by calling setNewSyncKey(), then save().
| string | $syncKey | The old syncKey |
The new synckey
loadState(array $collection, string $syncKey, string $type = null, string $id = null)
Load and initialize the sync state
| array | $collection | The collection array for the collection, if a FOLDERSYNC, pass an empty array. |
| string | $syncKey | The synckey of the state to load. If empty will force a reset of the state for the class specified in $id |
| string | $type | The type of state a Horde_ActiveSync::REQUEST_TYPE constant. |
| string | $id | The folder id this state represents. If empty assumed to be a foldersync state. |
Horde_ActiveSync_Exception_StateGone
updateSyncStamp()
Update the syncStamp in the collection state, outside of any other changes.
Used to prevent extremely large differences in syncStamps for clients and collections that don't often have changes and the backend server doesn't keep separate syncStamp values per collection.
updateState(string $type, array $change, integer $origin = \Horde_ActiveSync::CHANGE_ORIGIN_NA, string $user = null, string $clientid = '')
Update the state to reflect changes
Notes: If we are importing client changes, need to update the syncMapTable so we don't mirror back the changes on next sync. If we are exporting server changes, we need to track which changes have been sent (by removing them from $this->_changes) so we know which items to send on the next sync if a MOREAVAILBLE response was needed. If this is being called from a FOLDERSYNC command, update state accordingly.
| string | $type | The type of change (change, delete, flags or foldersync) |
| array | $change | A stat/change hash describing the change. Contains:
|
| integer | $origin | Flag to indicate the origin of the change: Horde_ActiveSync::CHANGE_ORIGIN_NA - Not applicapble/not important Horde_ActiveSync::CHANGE_ORIGIN_PIM - Change originated from client |
| string | $user | The current sync user, only needed if change origin is CHANGE_ORIGIN_PIM |
| string | $clientid | client clientid sent when adding a new message |
loadDeviceInfo(string $devId, string $user = null, array $params = array()) : \Horde_ActiveSync_Device
Load the device object.
| string | $devId | The device id to obtain |
| string | $user | The user to retrieve user-specific device info for |
| array | $params | Additional parameters:
|
The device object
deviceExists(string $devId, string $user = null) : integer
Check that a given device id is known to the server. This is regardless of Provisioning status. If $user is provided, checks that the device is attached to the provided username.
| string | $devId | The device id to check. |
| string | $user | The device should be owned by this user. |
The numer of device entries found for the give devId, user combination. I.e., 0 == no device exists.
setDeviceInfo(\Horde_ActiveSync_Device $data, array $dirty = array())
Set new device info
| \Horde_ActiveSync_Device | $data | The device information |
| array | $dirty | Array of dirty properties. @since 2.9.0 |
removeState(array $options)
Explicitly remove a state from storage.
| array | $options | An options array containing at least one of:
|
listDevices(string $user = null, array $filter = array()) : array
List all devices that we know about.
| string | $user | The username to list devices for. If empty, will return all devices. |
| array | $filter | An array of optional filters where the keys are field names and the values are values to match. |
An array of device hashes
getLastSyncTimestamp(string $id = null, string $user = null) : integer
Get the last time the loaded device issued a SYNC request.
| string | $id | The (optional) devivce id. If empty will use the currently loaded device. |
| string | $user | The (optional) user id. If empty wil use the currently loaded device. |
The timestamp of the last sync, regardless of collection
getSyncCache(string $devid, string $user, array $fields = null) : array
Return the sync cache.
| string | $devid | The device id. |
| string | $user | The user id. |
| array | $fields | An array of fields to return. Default is to return the full cache. @since 2.9.0 |
The current sync cache for the user/device combination.
saveSyncCache(array $cache, string $devid, string $user, array $dirty = array())
Save the provided sync_cache.
| array | $cache | The cache to save. |
| string | $devid | The device id. |
| string | $user | The user id. |
| array | $dirty | An array of dirty properties. @since 2.9.0 |
isDuplicatePIMAddition(string $id) : string
Check and see that we didn't already see the incoming change from the client.
This would happen e.g., if the client failed to receive the server response after successfully importing new messages.
| string | $id | The client id sent during message addition. |
The UID for the given clientid, null if none found.
updateServerIdInState(string $uid, string $serverid)
Update the serverid for a given folder uid in the folder's state object.
Needed when a folder is renamed on a client, but the UID must remain the same.
| string | $uid | The folder UID. |
| string | $serverid | The new serverid for this uid. |
isDuplicatePIMChange(string $uid, string $synckey) : boolean
Check if the UID provided was altered during the SYNC_KEY provided.
| string | $uid | The UID to check. |
| string | $synckey | The synckey to check. |
True if the provided UID was updated during the SYNC for the synckey provided.
_havePIMChanges() : boolean
Check for the existence of ANY entries in the map table for this device and user.
An extra database query for each sync, but the payoff is that we avoid having to stat every message change we send to the client if there are no client generated changes for this sync period.
_getMailMapChanges(array $changes) : array
Return all available mailMap changes for the current folder.
| array | $changes | The changes array |
An array of hashes, each in the form of {uid} => array( Horde_ActiveSync::CHANGE_TYPE_FLAGS => true|false, Horde_ActiveSync::CHANGE_TYPE_DELETE => true|false, Horde_ActiveSync::CHANGE_TYPE_DRAFT => true|false, )
_getPIMChangeTS(array $changes) : array
Return an array of timestamps from the map table for the last client-initiated change for the provided uid. Used to avoid mirroring back changes to the client that it sent to the server.
| array | $changes | The changes array, each entry a hash containing 'id' and 'type' keys. |
An array of UID -> timestamp of the last client-initiated change for the specified UIDs, or null if none found.