Documentation

Horde_ActiveSync_State_Sql extends Horde_ActiveSync_State_Base
in package

ActiveSync

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.

SYNCSTAMP_UPDATE_THRESHOLD

When there are no changes found in a collection, but the difference in syncStamp values is more than this threshold, the syncStamp is updated in the collection state without modifying the synckey or anyother state.


    public
        mixed
    SYNCSTAMP_UPDATE_THRESHOLD
    = 30000

$_backend

The backend driver


    protected
        mixed
    $_backend

$_changes

Local cache for changes to *send* to client.


    protected
        array<string|int, mixed>
    $_changes

(Will remain null until getChanges() is called)

$_collection

The collection array for the collection we are currently syncing.


    protected
        array<string|int, mixed>
    $_collection

Keys include:

class: The collection class Contacts, Calendar etc...
synckey: The current synckey
newsynckey: The new synckey sent back to the client
id: Server folder id
filtertype: Filter
conflict: Conflicts
truncation: Truncation

$_db

DB handle


    protected
        Horde_Db_Adapter
    $_db

$_deviceInfo

Device object.


    protected
        Horde_ActiveSync_Device
    $_deviceInfo

$_folder

Caches the current state(s) in memory


    protected
        mixed
    $_folder

Horde_ActiveSync_Folder_Base if request is not a FOLDERSYNC otherwise an array containing all FOLDERSYNC state.

$_folderUidMap

A map of backend folderids to UIDs


    protected
        array<string|int, mixed>
    $_folderUidMap

$_lastSyncStamp

The timestamp for the last syncKey


    protected
        timestamp
    $_lastSyncStamp
     = 0

$_logger

Logger instance


    protected
        Horde_Log_Logger
    $_logger

$_params

Configuration parameters


    protected
        array<string|int, mixed>
    $_params

$_procid

The process id (used for logging).


    protected
        int
    $_procid

$_syncCacheTable

The Synccache table. Holds the sync cache and is used to cache info about SYNC and PING request that are only sent a single time. Also stores data supported looping SYNC requests.


    protected
        string
    $_syncCacheTable

$_syncDeviceTable

Device information table. Holds information about each client.


    protected
        string
    $_syncDeviceTable

$_syncKey

The syncKey for the current request.


    protected
        string
    $_syncKey

$_syncMailMapTable

The Sync Mail Map table. Same principle as self::_syncMapTable, but for email collection data.


    protected
        string
    $_syncMailMapTable

$_syncMapTable

The Sync Map table. This table temporarily holds information about changes received FROM the client and is used to prevent mirroring back changes to the client that originated there.


    protected
        string
    $_syncMapTable

$_syncStateTable

State table name. This table holds the device's current state.


    protected
        string
    $_syncStateTable

$_syncUsersTable

Users table. Holds information specific to a user.


    protected
        string
    $_syncUsersTable

$_thisSyncStamp

The current sync timestamp


    protected
        timestamp
    $_thisSyncStamp
     = 0

$_type

The type of request we are handling.


    protected
        string
    $_type

__construct()

Const'r


    public
                    __construct([array<string|int, mixed> $params = array() ]) : Horde_ActiveSync_State_Sql

Parameters

$params : array<string|int, mixed> = array()

Must contain:

db: (Horde_Db_Adapter_Base) The Horde_Db instance.

Return values

Horde_ActiveSync_State_Sql —

checkCollision()

Check for the (rare) possibility of a synckey collision between collections.


    public
                    checkCollision(string $syncKey) : bool

Parameters

$syncKey : string: The synckey to check.

Return values

bool —

True if there was a collision.

connect()

(Re)open backend storage connection.


    public
                    connect() : mixed

Return values

mixed —

deleteSyncCache()

Delete a complete sync cache


    public
                    deleteSyncCache(string $devid[, string $user = null ]) : mixed

Parameters

$devid : string: The device id
$user : string = null: The user name.

Return values

mixed —

deviceExists()

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.


    public
                    deviceExists(string $devId[, string $user = null ]) : int

Parameters

$devId : string: The device id to check.
$user : string = null: The device should be owned by this user.

Return values

int —

The numer of device entries found for the give devId, user combination. I.e., 0 == no device exists.

disconnect()

Close the underlying backend storage connection.


    public
                    disconnect() : mixed

To be used during PING or looping SYNC operations.

Return values

mixed —

generatePolicyKey()

Generate a random 10 digit policy key


    public
                    generatePolicyKey() : int

Return values

int —

getChangeCount()

Get the number of server changes.


    public
                    getChangeCount() : int

Return values

int —

getChanges()

Get all items that have changed since the last sync time


    public
                    getChanges([array<string|int, mixed> $options = array() ]) : array<string|int, mixed>

Parameters

$options : array<string|int, mixed> = array()

An options array:

ping: (boolean) Only detect if there is a change, do not build any messages. DEFAULT: false (Build full change array).

Return values

array<string|int, mixed> —

An array of hashes describing each change:

id: The id of the item being changed.
type: The type of change. a Horde_ActiveSync::CHANGE_TYPE_* constant.
flags: Used to transport email message flags when type is Horde_ActiveSync::CHANGE_TYPE_FLAGS or set to Horde_ActiveSync::FLAG_NEWMESSAGE when type is Horde_ActiveSync::CHANGE_TYPE_CHANGE and the message represents a new message, as opposed to a change in an existing message.
ignore: Set to true when the change should be ignored, and not sent to the client by the exporter. Usually due to the change being the result of a client originated change.

getCurrentSyncKey()

Get the current synckey


    public
                    getCurrentSyncKey() : string

Return values

string —

The synkey we last retrieved state for

getDeviceRWStatus()

Return a device wipe status


    public
                    getDeviceRWStatus(string $devId[, bool $refresh = false ]) : int

Parameters

$devId : string
$refresh : bool = false: If true, reload the device's rwstatus flag. @since 2.31.0

Return values

int —

getFolderUidForBackendId()

Get a EAS Folder Uid for the given backend server id.


    public
                    getFolderUidForBackendId(string $serverid) : string|bool

Parameters

$serverid : string: The backend server id. E.g., 'INBOX'.

Return values

string|bool —

The EAS UID for the requested serverid, or false if it is not found.

getFolderUidToBackendIdMap()

Return the mapping of folder uids to backend folderids.


    public
                    getFolderUidToBackendIdMap() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An array of backend folderids -> uids.

getKnownFolders()

Return an array of known folders. This is essentially the state for a FOLDERSYNC request. AS uses a seperate synckey for FOLDERSYNC requests also, so need to treat it as any other collection.


    public
                    getKnownFolders() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An array of folder uids.

getLastSyncTimestamp()

Get the last time the loaded device issued a SYNC request.


    public
                    getLastSyncTimestamp([string $id = null ][, string $user = null ]) : int

Parameters

$id : string = null: The (optional) devivce id. If empty will use the currently loaded device.
$user : string = null: The (optional) user id. If empty wil use the currently loaded device.

Return values

int —

The timestamp of the last sync, regardless of collection

getLatestSynckeyForCollection()

Return the most recently seen synckey for the given collection.


    public
                    getLatestSynckeyForCollection(string $collection_id) : string|int

Parameters

$collection_id : string: The activesync collection id.

Return values

string|int —

The synckey or 0 if none found.

getNewSyncKey()

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().


    public
            static        getNewSyncKey(string $syncKey) : string

Parameters

$syncKey : string: The old syncKey

Return values

string —

The new synckey

getNewSyncKeyWrapper()

Non-static wrapper for getNewSyncKey.


    public
                    getNewSyncKeyWrapper(string $syncKey) : string

Parameters

$syncKey : string: The old syncKey

Return values

string —

The new synckey

getPolicyKey()

Obtain the current policy key, if it exists.


    public
                    getPolicyKey(string $devId) : int

Parameters

$devId : string: The device id to obtain policy key for.

Return values

int —

The current policy key for this device, or 0 if none exists.

getSyncCache()

Return the sync cache.


    public
                    getSyncCache(string $devid, string $user[, array<string|int, mixed> $fields = null ]) : array<string|int, mixed>

Parameters

$devid : string: The device id.
$user : string: The user id.
$fields : array<string|int, mixed> = null: An array of fields to return. Default is to return the full cache. @since 2.9.0

Return values

array<string|int, mixed> —

The current sync cache for the user/device combination.

getSyncKeyCounter()

Return the counter for the specified syncKey.


    public
            static        getSyncKeyCounter(string $syncKey) : mixed

Parameters

$syncKey : string: The synckey to obtain the counter for.

Return values

mixed —

integer|boolean The increment counter or false if failed.

getSyncKeyUid()

Return the UID portion of a synckey.


    public
            static        getSyncKeyUid(string $syncKey) : string

Parameters

$syncKey : string: The synckey

Return values

string —

The UID.

isConflict()

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.


    public
                    isConflict(array<string|int, mixed> $stat, string $type) : bool

Parameters

$stat : array<string|int, mixed>: A message stat array
$type : string: The type of change (change, delete, add)

Return values

bool —

isDuplicatePIMAddition()

Check and see that we didn't already see the incoming change from the client.


    public
                    isDuplicatePIMAddition(string $id) : string

This would happen e.g., if the client failed to receive the server response after successfully importing new messages.

Parameters

$id : string: The client id sent during message addition.

Return values

string —

The UID for the given clientid, null if none found.

isDuplicatePIMChange()

Check if the UID provided was altered during the SYNC_KEY provided.


    public
                    isDuplicatePIMChange(string $uid, string $synckey) : bool

Parameters

$uid : string: The UID to check.
$synckey : string: The synckey to check.

Return values

bool —

True if the provided UID was updated during the SYNC for the synckey provided.

listDevices()

List all devices that we know about.


    public
                    listDevices([string $user = null ][, array<string|int, mixed> $filter = array() ]) : array<string|int, mixed>

Parameters

$user : string = null: The username to list devices for. If empty, will return all devices.
$filter : array<string|int, mixed> = array(): An array of optional filters where the keys are field names and the values are values to match.

Return values

array<string|int, mixed> —

An array of device hashes

loadDeviceInfo()

Load the device object.


    public
                    loadDeviceInfo(string $devId[, string $user = null ][, array<string|int, mixed> $params = array() ]) : Horde_ActiveSync_Device

Parameters

$devId : string

The device id to obtain

$user : string = null

The user to retrieve user-specific device info for

$params : array<string|int, mixed> = array()

Additional parameters:

force: (boolean) If true, reload the device info even if it's already loaded. Used to refresh values such as device_rwstatus that may have changed during a long running PING/SYNC. DEFAULT: false. @since 2.31.0

Return values

Horde_ActiveSync_Device —

The device object

loadState()

Load and initialize the sync state


    public
                    loadState(array<string|int, mixed> $collection, string $syncKey[, string $type = null ][, string $id = null ]) : mixed

Parameters

$collection : array<string|int, mixed>: The collection array for the collection, if a FOLDERSYNC, pass an empty array.
$syncKey : string: The synckey of the state to load. If empty will force a reset of the state for the class specified in $id
$type : string = null: The type of state a Horde_ActiveSync::REQUEST_TYPE constant.
$id : string = null: The folder id this state represents. If empty assumed to be a foldersync state.

Return values

mixed —

removeState()

Explicitly remove a state from storage.


    public
                    removeState(array<string|int, mixed> $options) : mixed

Parameters

$options : array<string|int, mixed>

An options array containing at least one of:

synckey: (string) Remove only the state associated with this synckey. DEFAULT: All synckeys are removed for the specified device.
devId: (string) Remove all information for this device. DEFAULT: None. If no device, a synckey is required.
user: (string) Restrict to removing data for this user only. DEFAULT: None - all users for the specified device are removed.
id: (string) When removing device state, restrict ro removing data only for this collection.

Return values

mixed —

resetAllPolicyKeys()

Reset ALL device policy keys. Used when server policies have changed and you want to force ALL devices to pick up the changes. This will cause all devices that support provisioning to be reprovisioned.


    public
                    resetAllPolicyKeys() : mixed

Return values

mixed —

RowCmp()

Helper function for the _diff method


    public
            static        RowCmp( $a,  $b) : unknown_type

Parameters

$a :
$b :

Return values

unknown_type —

save()

Save the current state to storage


    public
                    save() : mixed

Return values

mixed —

saveSyncCache()

Save the provided sync_cache.


    public
                    saveSyncCache(array<string|int, mixed> $cache, string $devid, string $user[, array<string|int, mixed> $dirty = array() ]) : mixed

Parameters

$cache : array<string|int, mixed>: The cache to save.
$devid : string: The device id.
$user : string: The user id.
$dirty : array<string|int, mixed> = array(): An array of dirty properties. @since 2.9.0

Return values

mixed —

setBackend()

Set the backend driver (should really only be called by a backend object when passing this object to client code)


    public
                    setBackend(Horde_ActiveSync_Driver_Base $backend) : void

Parameters

$backend : Horde_ActiveSync_Driver_Base: The backend driver

Return values

void —

setDeviceInfo()

Set new device info


    public
                    setDeviceInfo(Horde_ActiveSync_Device $data[, array<string|int, mixed> $dirty = array() ]) : mixed

Parameters

$data : Horde_ActiveSync_Device: The device information
$dirty : array<string|int, mixed> = array(): Array of dirty properties. @since 2.9.0

Return values

mixed —

setDeviceProperties()

Set the device's properties as sent by a SETTINGS request.


    public
                    setDeviceProperties(array<string|int, mixed> $data, string $deviceId) : mixed

Parameters

$data : array<string|int, mixed>: The device settings
$deviceId : string: The device id.

Return values

mixed —

setDeviceRWStatus()

Set a new remotewipe status for the device


    public
                    setDeviceRWStatus(string $devId, string $status) : mixed

Parameters

$devId : string: The device id.
$status : string: A Horde_ActiveSync::RWSTATUS_* constant.

Return values

mixed —

setLogger()

Set the logger instance for this object.


    public
                    setLogger(Horde_Log_Logger $logger) : mixed

Parameters

$logger : Horde_Log_Logger

Return values

mixed —

setNewSyncKey()

Update the $oldKey syncState to $newKey.


    public
                    setNewSyncKey(string $newKey) : mixed

Parameters

$newKey : string

Return values

mixed —

setPolicyKey()

Save a new device policy key to storage.


    public
                    setPolicyKey(string $devId, int $key) : mixed

Parameters

$devId : string: The device id
$key : int: The new policy key

Return values

mixed —

updateServerIdInState()

Update the serverid for a given folder uid in the folder's state object.


    public
                    updateServerIdInState(string $uid, string $serverid) : mixed

Needed when a folder is renamed on a client, but the UID must remain the same.

Parameters

$uid : string: The folder UID.
$serverid : string: The new serverid for this uid.

Return values

mixed —

updateState()

Update the state to reflect changes


    public
                    updateState(string $type, array<string|int, mixed> $change[, int $origin = Horde_ActiveSync::CHANGE_ORIGIN_NA ][, string $user = null ][, string $clientid = '' ]) : mixed

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.

Parameters

$type : string

The type of change (change, delete, flags or foldersync)

$change : array<string|int, mixed>

A stat/change hash describing the change. Contains:

id: (mixed) The message uid the change applies to.
serverid: (string) The backend server id for the folder.
folderuid: (string) The EAS folder UID for the folder.
parent: (string) The parent of the current folder, if any.
flags: (array) If this is a flag change, the state of the flags.
mod: (integer) The modtime of this change.

$origin : int = Horde_ActiveSync::CHANGE_ORIGIN_NA

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

$user : string = null

The current sync user, only needed if change origin is CHANGE_ORIGIN_PIM

$clientid : string = ''

client clientid sent when adding a new message

Return values

mixed —

updateSyncStamp()

Update the syncStamp in the collection state, outside of any other changes.


    public
                    updateSyncStamp() : mixed

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.

Return values

mixed —

_checkCollision()

Check for the (rare) possibility of a synckey collision between collections.


    protected
                    _checkCollision(string $guid) : bool

Parameters

$guid : string: The GUID portion of the synckey to check.

Return values

bool —

true if there was a collision.

_gc()

Garbage collector - clean up from previous sync requests.


    protected
                    _gc(string $syncKey) : mixed

Parameters

$syncKey : string: The sync key

Return values

mixed —

_getCutOffDate()

Returns the timestamp of the earliest modification time to consider


    protected
            static        _getCutOffDate(int $restrict) : int

Parameters

$restrict : int: The time period to restrict to

Return values

int —

_getDiff()

Helper function that performs the actual diff between client state and server state FOLDERSYNC arrays.


    protected
                    _getDiff(array<string|int, mixed> $old, array<string|int, mixed> $new) : unknown_type

Parameters

$old : array<string|int, mixed>: The client state
$new : array<string|int, mixed>: The current server state

Return values

unknown_type —

_getFolderChanges()

Get folder changes. Populates $this->_changes with an array of change entries each containing 'type', 'id' and possibly 'flags'.


    protected
                    _getFolderChanges() : mixed

Return values

mixed —

_getMailMapChanges()

Return all available mailMap changes for the current folder.


    protected
                    _getMailMapChanges(array<string|int, mixed> $changes) : array<string|int, mixed>

Parameters

$changes : array<string|int, mixed>: The changes array

Return values

array<string|int, mixed> —

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()

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.


    protected
                    _getPIMChangeTS(array<string|int, mixed> $changes) : array<string|int, mixed>

Parameters

$changes : array<string|int, mixed>: The changes array, each entry a hash containing 'id' and 'type' keys.

Return values

array<string|int, mixed> —

An array of UID -> timestamp of the last client-initiated change for the specified UIDs, or null if none found.

_havePIMChanges()

Check for the existence of ANY entries in the map table for this device and user.


    protected
                    _havePIMChanges() : bool

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.

Return values

bool —

_loadState()

Load the state represented by $syncKey from storage.


    protected
                    _loadState() : mixed

Return values

mixed —

_loadStateFromResults()

Actually load the state data into the object from the query results.


    protected
                    _loadStateFromResults(array<string|int, mixed> $results) : mixed

Parameters

$results : array<string|int, mixed>: The results array from the state query.

Return values

mixed —

_resetDeviceState()

Reset the sync state for this device, for the specified collection.


    protected
                    _resetDeviceState(string $id) : void

Parameters

$id : string: The collection to reset.

Return values

void —

Horde_ActiveSync_State_Sql extends Horde_ActiveSync_State_Base in package ActiveSync

Tags

Table of Contents

Constants

SYNCSTAMP_UPDATE_THRESHOLD

Properties

$_backend

$_changes

$_collection

$_db

$_deviceInfo

$_folder

$_folderUidMap

$_lastSyncStamp

$_logger

$_params

$_procid

$_syncCacheTable

$_syncDeviceTable

$_syncKey

$_syncMailMapTable

$_syncMapTable

$_syncStateTable

$_syncUsersTable

$_thisSyncStamp

$_type

Methods

__construct()

Parameters

Return values

checkCollision()

Parameters

Return values

connect()

Return values

deleteSyncCache()

Parameters

Tags

Return values

deviceExists()

Parameters

Return values

disconnect()

Return values

generatePolicyKey()

Return values

getChangeCount()

Return values

getChanges()

Parameters

Tags

Return values

getCurrentSyncKey()

Return values

getDeviceRWStatus()

Parameters

Return values

getFolderUidForBackendId()

Parameters

Tags

Return values

getFolderUidToBackendIdMap()

Tags

Return values

getKnownFolders()

Return values

getLastSyncTimestamp()

Parameters

Tags

Return values

getLatestSynckeyForCollection()

Parameters

Return values

getNewSyncKey()

Parameters

Tags

Return values

getNewSyncKeyWrapper()

Parameters

Tags

Horde_ActiveSync_State_Sql extends Horde_ActiveSync_State_Base
in package

ActiveSync