Documentation

Horde_SyncMl_Backend_Horde extends Horde_SyncMl_Backend
in package

SyncML Backend for the Horde Application framework.

Copyright 2005-2017 Horde LLC (http://www.horde.org/)

See the enclosed file LICENSE for license information (LGPL). If you did not receive this file, see http://www.horde.org/licenses/lgpl21.

Tags
author

Karsten Fourmont karsten@horde.org

Table of Contents

LOGFILE_CLIENTMESSAGE  = 1
Types of logfiles. See logFile() method.
LOGFILE_DATA  = 4
LOGFILE_DEVINF  = 3
LOGFILE_SERVERMESSAGE  = 2
MODE_CLIENT  = 2
MODE_SERVER  = 1
Backend modes.
MODE_TEST  = 3
$state  : Horde_SyncMl_State
The State object.
$_backendMode  : int
The backend mode. One of the Horde_SyncMl_Backend::MODE_* constants.
$_charset  : string
The charset used in the SyncML messages.
$_db  : Horde_Db_Adapter_Base
A database instance.
$_debugDir  : string
The directory where debugging information is stored.
$_debugFiles  : bool
Whether to save SyncML messages in the debug directory.
$_logLevel  : string
The log level.
$_logtext  : string
The concatenated log messages.
$_sessionId  : string
The session ID used in the Horde session.
$_syncDeviceID  : string
The ID of the client device.
$_user  : string
The current user.
__construct()  : mixed
Constructor.
addEntry()  : array<string|int, mixed>
Adds an entry into the server database.
checkAuthentication()  : bool|string
Authenticates the user at the backend.
close()  : mixed
Cleanup public function called after all message processing is finished.
createUidMap()  : mixed
Creates a map entry to map between server and client IDs.
deleteEntry()  : bool
Deletes an entry from the server database.
eraseMap()  : mixed
Erases all mapping entries for one combination of user, device ID.
factory()  : Horde_SyncMl_Backend
Attempts to return a concrete Horde_SyncMl_Backend instance based on $driver.
getCharset()  : string
Returns the charset.
getCurrentTimeStamp()  : mixed
Returns the current timestamp in the same format as used by getServerChanges().
getParameter()  : mixed
Extracts an HTTP GET like parameter from an URL.
getServerChanges()  : bool
Returns entries that have been modified in the server database.
getSyncDeviceID()  : string
Returns the current device's ID.
getUser()  : string
Returns the current user.
getUserAnchors()  : array<string|int, mixed>
Returns all previously written sync anchors for a user.
isValidDatabaseURI()  : bool
Returns whether a database URI is valid to be synced with this backend.
logFile()  : mixed
Logs data to a file in the debug directory.
logMessage()  : mixed
Logs a message in the backend.
normalize()  : string
Normalizes a databaseURI to a database name, so that _normalize('tasks?ignorecompleted') should return just 'tasks'.
readSyncAnchors()  : mixed
Reads the previously written sync anchors from the database.
removeAnchor()  : array<string|int, mixed>
Deletes previously written sync anchors for a user.
removeMaps()  : array<string|int, mixed>
Deletes previously written sync maps for a user.
replaceEntry()  : string
Replaces an entry in the server database.
retrieveEntry()  : mixed
Retrieves an entry from the backend.
sessionClose()  : mixed
Closes the PHP session.
sessionStart()  : mixed
Starts a PHP session.
setCharset()  : mixed
Sets the charset.
setupState()  : mixed
Is called after the Horde_SyncMl_State object has been set up, either restored from the session, or freshly created.
setUser()  : mixed
Sets the user used for this session.
testSetup()  : mixed
Creates a clean test environment in the backend.
testStart()  : mixed
Prepares the test start.
testTearDown()  : mixed
Tears down the test environment after the test is run.
writeSyncAnchors()  : mixed
Stores Sync anchors after a successful synchronization to allow two-way synchronization next time.
_checkAuthentication()  : bool|string
Authenticates the user at the backend.
_fastsync()  : mixed
_getChangeTS()  : mixed
Returns a timestamp stored in the map for a given Server ID.
_getCuid()  : mixed
Retrieves the Client ID for a given Server ID from the map.
_getSuid()  : mixed
Retrieves the Server ID for a given Client ID from the map.
_setAuthenticated()  : string
Sets a user as being authenticated at the backend.
_slowsync()  : mixed

Constants

LOGFILE_CLIENTMESSAGE

Types of logfiles. See logFile() method.

public mixed LOGFILE_CLIENTMESSAGE = 1

LOGFILE_DATA

public mixed LOGFILE_DATA = 4

LOGFILE_DEVINF

public mixed LOGFILE_DEVINF = 3

LOGFILE_SERVERMESSAGE

public mixed LOGFILE_SERVERMESSAGE = 2

MODE_CLIENT

public mixed MODE_CLIENT = 2

MODE_SERVER

Backend modes.

public mixed MODE_SERVER = 1

MODE_TEST

public mixed MODE_TEST = 3

Properties

$_backendMode

The backend mode. One of the Horde_SyncMl_Backend::MODE_* constants.

protected int $_backendMode

$_charset

The charset used in the SyncML messages.

protected string $_charset

$_db

A database instance.

protected Horde_Db_Adapter_Base $_db

$_debugDir

The directory where debugging information is stored.

protected string $_debugDir
Tags
see
Horde_SyncMl_Backend()

$_debugFiles

Whether to save SyncML messages in the debug directory.

protected bool $_debugFiles
Tags
see
Horde_SyncMl_Backend()

$_logLevel

The log level.

protected string $_logLevel = 'INFO'
Tags
see
Horde_SyncMl_Backend()

$_logtext

The concatenated log messages.

protected string $_logtext = ''

$_sessionId

The session ID used in the Horde session.

protected string $_sessionId

$_syncDeviceID

The ID of the client device.

protected string $_syncDeviceID

This is used for all data access as an ID to allow to distinguish between syncs with different devices. $this->_user together with $this->_syncDeviceID is used as an additional key for all persistence operations.

$_user

The current user.

protected string $_user

Methods

__construct()

Constructor.

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

Initializes the logger.

Parameters
$params : array<string|int, mixed>

Any parameters the backend might need.

Return values
mixed

addEntry()

Adds an entry into the server database.

public addEntry(string $databaseURI, string $content, string $contentType[, string $cuid = null ]) : array<string|int, mixed>
Parameters
$databaseURI : string

URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

$content : string

The actual data.

$contentType : string

MIME type of the content.

$cuid : string = null

Client ID of this entry.

Return values
array<string|int, mixed>

PEAR_Error or suid (Horde guid) of new entry

checkAuthentication()

Authenticates the user at the backend.

public checkAuthentication(string &$username, string $credData, string $credFormat, string $credType) : bool|string

For some types of authentications (notably auth:basic) the username gets extracted from the authentication data and is then stored in username. For security reasons the caller must ensure that this is the username that is used for the session, overriding any username specified in .

Parameters
$username : string

Username as provided in the . May be overwritten by $credData.

$credData : string

Authentication data provided by in the .

$credFormat : string

Format of data as in the . Typically 'b64'.

$credType : string

Auth type as provided by in the . Typically 'syncml:auth-basic'.

Return values
bool|string

The user name if authentication succeeded, false otherwise.

close()

Cleanup public function called after all message processing is finished.

public close() : mixed

Allows for things like closing databases or flushing logs. When running in test mode, tearDown() must be called rather than close.

Return values
mixed

createUidMap()

Creates a map entry to map between server and client IDs.

public createUidMap(string $databaseURI, string $cuid, string $suid, int $timestamp) : mixed

If an entry already exists, it is overwritten.

Parameters
$databaseURI : string

URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

$cuid : string

Client ID of the entry.

$suid : string

Server ID of the entry.

$timestamp : int

Optional timestamp. This can be used to 'tag' changes made in the backend during the sync process. This allows to identify these, and ensure that these changes are not replicated back to the client (and thus duplicated). See key concept "Changes and timestamps".

Return values
mixed

deleteEntry()

Deletes an entry from the server database.

public deleteEntry(string $databaseURI, string $cuid) : bool
Parameters
$databaseURI : string

URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

$cuid : string

Client ID of the entry.

Return values
bool

True on success or false on failed (item not found).

eraseMap()

Erases all mapping entries for one combination of user, device ID.

public eraseMap(string $databaseURI) : mixed

This is used during SlowSync so that we really sync everything properly and no old mapping entries remain.

Parameters
$databaseURI : string

URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

Return values
mixed

factory()

Attempts to return a concrete Horde_SyncMl_Backend instance based on $driver.

public factory(string $driver[, array<string|int, mixed> $params = null ]) : Horde_SyncMl_Backend
Parameters
$driver : string

The type of concrete Backend subclass to return. The code is dynamically included from Backend/$driver.php if no path is given or directly with "include_once $driver . '.php'" if a path is included. So make sure this parameter is "safe" and not directly taken from web input. The class in the file must be named 'Horde_SyncMl_Backend_' . basename($driver) and extend Horde_SyncMl_Backend.

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

A hash containing any additional configuration or connection parameters a subclass might need.

Return values
Horde_SyncMl_Backend

The newly created concrete Horde_SyncMl_Backend instance, or false on an error.

getCharset()

Returns the charset.

public getCharset() : string
Return values
string

The charset used when talking to the backend.

getCurrentTimeStamp()

Returns the current timestamp in the same format as used by getServerChanges().

public getCurrentTimeStamp() : mixed

Backends can use their own way to represent timestamps, like unix epoch integers or UTC Datetime strings.

Return values
mixed

A timestamp of the current time.

getParameter()

Extracts an HTTP GET like parameter from an URL.

public getParameter(string $url, string $parameter[, string $default = null ]) : mixed

Example: getParameter('test?q=1', 'q') == 1

Parameters
$url : string

The complete URL.

$parameter : string

The parameter name to extract.

$default : string = null

A default value to return if none has been provided in the URL.

Tags
static
Return values
mixed

getServerChanges()

Returns entries that have been modified in the server database.

public getServerChanges(string $databaseURI, int $from_ts, int $to_ts, array<string|int, mixed> &$adds, array<string|int, mixed> &$mods, array<string|int, mixed> &$dels) : bool
Parameters
$databaseURI : string

URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

$from_ts : int

Start timestamp.

$to_ts : int

Exclusive end timestamp. Not yet implemented.

$adds : array<string|int, mixed>

Output array: hash of adds suid => 0

$mods : array<string|int, mixed>

Output array: hash of modifications suid => cuid

$dels : array<string|int, mixed>

Output array: hash of deletions suid => cuid

Return values
bool

true

getSyncDeviceID()

Returns the current device's ID.

public getSyncDeviceID() : string
Return values
string

The device ID.

getUser()

Returns the current user.

public getUser() : string
Return values
string

The current user.

getUserAnchors()

Returns all previously written sync anchors for a user.

public getUserAnchors(string $user) : array<string|int, mixed>
Parameters
$user : string

A user name.

Return values
array<string|int, mixed>

A hash tree with all devices, databases and sync anchors from the specified user.

isValidDatabaseURI()

Returns whether a database URI is valid to be synced with this backend.

public isValidDatabaseURI(string $databaseURI) : bool

This default implementation accepts "tasks", "calendar", "notes" and "contacts". However individual backends may offer replication of different or completly other databases (like browser bookmarks or cooking recipes).

Parameters
$databaseURI : string

URI of a database. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

Return values
bool

True if a valid URI.

logFile()

Logs data to a file in the debug directory.

public logFile(int $type, string $content[, bool $wbxml = false ][, bool $sessionClose = false ]) : mixed
Parameters
$type : int

The data type. One of the Horde_SyncMl_Backend::LOGFILE_* constants.

$content : string

The data content.

$wbxml : bool = false

Whether the data is wbxml encoded.

$sessionClose : bool = false

Whether this is the last SyncML message in a session. Bump the file number.

Return values
mixed

logMessage()

Logs a message in the backend.

public logMessage(mixed $message[, string $priority = 'INFO' ]) : mixed
Parameters
$message : mixed

Either a string or a PEAR_Error object.

$priority : string = 'INFO'

The priority of the message. One of:

  • EMERG
  • ALERT
  • CRIT
  • ERR
  • WARN
  • NOTICE
  • INFO
  • DEBUG
Return values
mixed

normalize()

Normalizes a databaseURI to a database name, so that _normalize('tasks?ignorecompleted') should return just 'tasks'.

public normalize(string $databaseURI) : string
Parameters
$databaseURI : string

URI of a database. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

Return values
string

The normalized database name.

readSyncAnchors()

Reads the previously written sync anchors from the database.

public readSyncAnchors(string $databaseURI) : mixed
Parameters
$databaseURI : string

URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

Return values
mixed

Two-element array with client anchor and server anchor as stored in previous writeSyncAnchor() calls. False if no data found.

removeAnchor()

Deletes previously written sync anchors for a user.

public removeAnchor(string $user[, string $device = null ][, string $database = null ]) : array<string|int, mixed>

If no device or database are specified, anchors for all devices and/or databases will be deleted.

Parameters
$user : string

A user name.

$device : string = null

The ID of the client device.

$database : string = null

Normalized URI of database to delete. Like calendar, tasks, contacts or notes.

Return values
array<string|int, mixed>

removeMaps()

Deletes previously written sync maps for a user.

public removeMaps(string $user[, string $device = null ][, string $database = null ]) : array<string|int, mixed>

If no device or database are specified, maps for all devices and/or databases will be deleted.

Parameters
$user : string

A user name.

$device : string = null

The ID of the client device.

$database : string = null

Normalized URI of database to delete. Like calendar, tasks, contacts or notes.

Return values
array<string|int, mixed>

replaceEntry()

Replaces an entry in the server database.

public replaceEntry(string $databaseURI, string $content, string $contentType, string $cuid) : string
Parameters
$databaseURI : string

URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

$content : string

The actual data.

$contentType : string

MIME type of the content.

$cuid : string

Client ID of this entry.

Return values
string

PEAR_Error or server ID (Horde GUID) of modified entry.

retrieveEntry()

Retrieves an entry from the backend.

public retrieveEntry(string $databaseURI, string $suid, string $contentType, array<string|int, mixed> $fields) : mixed
Parameters
$databaseURI : string

URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

$suid : string

Server unique id of the entry: for horde this is the guid.

$contentType : string

Content-Type: the MIME type in which the public function should return the data.

$fields : array<string|int, mixed>

Hash of field names and Horde_SyncMl_Property properties with the requested fields.

Return values
mixed

A string with the data entry or a PEAR_Error object.

sessionClose()

Closes the PHP session.

public sessionClose() : mixed
Return values
mixed

sessionStart()

Starts a PHP session.

public sessionStart(string $syncDeviceID, mixed $sessionId[, int $backendMode = Horde_SyncMl_Backend::MODE_SERVER ]) : mixed
Parameters
$syncDeviceID : string

The device ID.

$sessionId : mixed
$backendMode : int = Horde_SyncMl_Backend::MODE_SERVER

The backend mode, one of the Horde_SyncMl_Backend::MODE_* constants.

Return values
mixed

setCharset()

Sets the charset.

public setCharset(string $charset) : mixed

All data passed to the backend uses this charset and data returned from the backend must use this charset, too.

Parameters
$charset : string

A valid charset.

Return values
mixed

setupState()

Is called after the Horde_SyncMl_State object has been set up, either restored from the session, or freshly created.

public setupState() : mixed
Return values
mixed

setUser()

Sets the user used for this session.

public setUser(string $user) : mixed
Parameters
$user : string

A user name.

Return values
mixed

testSetup()

Creates a clean test environment in the backend.

public testSetup(string $user, string $pwd) : mixed

Ensures there's a user with the given credentials and an empty data store.

Parameters
$user : string

This user accout has to be created in the backend.

$pwd : string

The password for user $user.

Tags
throws
Horde_Exception
Return values
mixed

testStart()

Prepares the test start.

public testStart(string $user) : mixed
Parameters
$user : string

This user accout has to be created in the backend.

Return values
mixed

testTearDown()

Tears down the test environment after the test is run.

public testTearDown() : mixed

Should remove the testuser created during testSetup and all its data.

Return values
mixed

writeSyncAnchors()

Stores Sync anchors after a successful synchronization to allow two-way synchronization next time.

public writeSyncAnchors(string $databaseURI, string $clientAnchorNext, string $serverAnchorNext) : mixed

The backend has to store the parameters in its persistence engine where user, syncDeviceID and database are the keys while client and server anchor ar the payload. See readSyncAnchors() for retrieval.

Parameters
$databaseURI : string

URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

$clientAnchorNext : string

The client anchor as sent by the client.

$serverAnchorNext : string

The anchor as used internally by the server.

Return values
mixed

_checkAuthentication()

Authenticates the user at the backend.

protected _checkAuthentication(string $username, string $password) : bool|string
Parameters
$username : string

A user name.

$password : string

A password.

Return values
bool|string

The user name if authentication succeeded, false otherwise.

_fastsync()

protected _fastsync(mixed $databaseURI, mixed $from_ts, mixed $to_ts) : mixed
Parameters
$databaseURI : mixed
$from_ts : mixed
$to_ts : mixed
Return values
mixed

_getChangeTS()

Returns a timestamp stored in the map for a given Server ID.

protected _getChangeTS(string $databaseURI, string $suid) : mixed

The timestamp is the timestamp of the last change to this server ID that was done inside a sync session (as a result of a change received by the server). It's important to distinguish changes in the backend a) made by the user during normal operation and b) changes made by SyncML to reflect client updates. When the server is sending its changes it is only allowed to send type a). However the history feature in the backend my not know if a change is of type a) or type b). So the timestamp is used to differentiate between the two.

Parameters
$databaseURI : string

URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

$suid : string

The server ID.

Return values
mixed

The previously stored timestamp or false if no entry is found.

_getCuid()

Retrieves the Client ID for a given Server ID from the map.

protected _getCuid(string $databaseURI, string $suid) : mixed
Parameters
$databaseURI : string

URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

$suid : string

The server ID.

Return values
mixed

The client ID string or false if no entry is found.

_getSuid()

Retrieves the Server ID for a given Client ID from the map.

protected _getSuid(string $databaseURI, string $cuid) : mixed
Parameters
$databaseURI : string

URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

$cuid : string

The client ID.

Return values
mixed

The server ID string or false if no entry is found.

_setAuthenticated()

Sets a user as being authenticated at the backend.

protected _setAuthenticated(string $username, string $credData) : string
Parameters
$username : string

A user name.

$credData : string

Authentication data provided by in the .

Tags
abstract
Return values
string

The user name.

_slowsync()

protected _slowsync(mixed $databaseURI, mixed $from_ts, mixed $to_ts) : mixed
Parameters
$databaseURI : mixed
$from_ts : mixed
$to_ts : mixed
Return values
mixed

Search results