API Documentation
\

\Horde_SyncMl_Backend_Horde

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.

Summary

Methods
Properties
Constants
__construct()
factory()
setCharset()
getCharset()
getSyncDeviceID()
setUser()
getUser()
setupState()
sessionStart()
sessionClose()
isValidDatabaseURI()
getServerChanges()
retrieveEntry()
addEntry()
replaceEntry()
deleteEntry()
checkAuthentication()
writeSyncAnchors()
readSyncAnchors()
createUidMap()
eraseMap()
logMessage()
logFile()
close()
getCurrentTimeStamp()
testSetup()
testStart()
testTearDown()
normalize()
getParameter()
getUserAnchors()
removeAnchor()
removeMaps()
$state
LOGFILE_CLIENTMESSAGE
LOGFILE_SERVERMESSAGE
LOGFILE_DEVINF
LOGFILE_DATA
MODE_SERVER
MODE_CLIENT
MODE_TEST
_checkAuthentication()
_setAuthenticated()
_fastsync()
_slowsync()
_getSuid()
_getCuid()
_getChangeTS()
$_logtext
$_debugDir
$_debugFiles
$_logLevel
$_charset
$_user
$_syncDeviceID
$_backendMode
$_db
$_sessionId
N/A
No private methods found
No private properties found
N/A

Constants

LOGFILE_CLIENTMESSAGE

LOGFILE_CLIENTMESSAGE

Types of logfiles. See logFile() method.

LOGFILE_SERVERMESSAGE

LOGFILE_SERVERMESSAGE

LOGFILE_DEVINF

LOGFILE_DEVINF

LOGFILE_DATA

LOGFILE_DATA

MODE_SERVER

MODE_SERVER

Backend modes.

MODE_CLIENT

MODE_CLIENT

MODE_TEST

MODE_TEST

Properties

$_logtext

$_logtext : string

The concatenated log messages.

Type

string

$_debugDir

$_debugDir : string

The directory where debugging information is stored.

Type

string

$_debugFiles

$_debugFiles : boolean

Whether to save SyncML messages in the debug directory.

Type

boolean

$_logLevel

$_logLevel : string

The log level.

Type

string

$_charset

$_charset : string

The charset used in the SyncML messages.

Type

string

$_user

$_user : string

The current user.

Type

string

$_syncDeviceID

$_syncDeviceID : string

The ID of the client device.

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.

Type

string

$_backendMode

$_backendMode : integer

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

Type

integer

$_db

$_db : \Horde_Db_Adapter_Base

A database instance.

Type

\Horde_Db_Adapter_Base

$_sessionId

$_sessionId : string

The session ID used in the Horde session.

Type

string

Methods

__construct()

__construct(array  $params)

Constructor.

Initializes the logger.

Parameters

array $params

Any parameters the backend might need.

factory()

factory(string  $driver, array  $params = null) : \Horde_SyncMl_Backend

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

Parameters

string $driver

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_SyncMlBackend' . basename($driver) and extend Horde_SyncMl_Backend.
array $params

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

Returns

\Horde_SyncMl_Backend —

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

setCharset()

setCharset(string  $charset)

Sets the charset.

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

Parameters

string $charset

A valid charset.

getCharset()

getCharset() : string

Returns the charset.

Returns

string —

The charset used when talking to the backend.

getSyncDeviceID()

getSyncDeviceID() : string

Returns the current device's ID.

Returns

string —

The device ID.

setUser()

setUser(string  $user)

Sets the user used for this session.

This method is called by SyncML right after sessionStart() when either authentication is accepted via checkAuthentication() or a valid user has been retrieved from the state. $this->_user together with $this->_syncDeviceID is used as an additional key for all persistence operations. This method may have to force a "login", when the backend doesn't keep auth state within a session or when in test mode.

Parameters

string $user

A user name.

getUser()

getUser() : string

Returns the current user.

Returns

string —

The current user.

setupState()

setupState()

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

sessionStart()

sessionStart(string  $syncDeviceID,   $sessionId, integer  $backendMode = \Horde_SyncMl_Backend::MODE_SERVER)

Starts a PHP session.

Parameters

string $syncDeviceID

The device ID.
$sessionId
integer $backendMode

The backend mode, one of the Horde_SyncMlBackend::MODE* constants.

sessionClose()

sessionClose()

Closes the PHP session.

isValidDatabaseURI()

isValidDatabaseURI(string  $databaseURI) : boolean

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

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

string $databaseURI

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

Returns

boolean —

True if a valid URI.

getServerChanges()

getServerChanges(string  $databaseURI, integer  $from_ts, integer  $to_ts,   $adds,   $mods,   $dels) : boolean

Returns entries that have been modified in the server database.

Parameters

string $databaseURI

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

Start timestamp.
integer $to_ts

Exclusive end timestamp. Not yet implemented.
$adds
$mods
$dels

Returns

boolean —

true

retrieveEntry()

retrieveEntry(string  $databaseURI, string  $suid, string  $contentType, array  $fields) : mixed

Retrieves an entry from the backend.

Parameters

string $databaseURI

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

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

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

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

Returns

mixed —

A string with the data entry or a PEAR_Error object.

addEntry()

addEntry(string  $databaseURI, string  $content, string  $contentType, string  $cuid = null) : array

Adds an entry into the server database.

Parameters

string $databaseURI

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

The actual data.
string $contentType

MIME type of the content.
string $cuid

Client ID of this entry.

Returns

array —

PEAR_Error or suid (Horde guid) of new entry

replaceEntry()

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

Replaces an entry in the server database.

Parameters

string $databaseURI

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

The actual data.
string $contentType

MIME type of the content.
string $cuid

Client ID of this entry.

Returns

string —

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

deleteEntry()

deleteEntry(string  $databaseURI, string  $cuid) : boolean

Deletes an entry from the server database.

Parameters

string $databaseURI

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

Client ID of the entry.

Returns

boolean —

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

checkAuthentication()

checkAuthentication(string  $username, string  $credData, string  $credFormat, string  $credType) : boolean|string

Authenticates the user at the backend.

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

string $username

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

Authentication data provided by in the .
string $credFormat

Format of data as in the . Typically 'b64'.
string $credType

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

Returns

boolean|string —

The user name if authentication succeeded, false otherwise.

writeSyncAnchors()

writeSyncAnchors(string  $databaseURI, string  $clientAnchorNext, string  $serverAnchorNext)

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

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

string $databaseURI

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

The client anchor as sent by the client.
string $serverAnchorNext

The anchor as used internally by the server.

readSyncAnchors()

readSyncAnchors(string  $databaseURI) : mixed

Reads the previously written sync anchors from the database.

Parameters

string $databaseURI

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

Returns

mixed —

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

createUidMap()

createUidMap(string  $databaseURI, string  $cuid, string  $suid, integer  $timestamp)

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

If an entry already exists, it is overwritten.

Parameters

string $databaseURI

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

Client ID of the entry.
string $suid

Server ID of the entry.
integer $timestamp

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".

eraseMap()

eraseMap(string  $databaseURI)

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

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

Parameters

string $databaseURI

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

logMessage()

logMessage(mixed  $message, string  $priority = 'INFO')

Logs a message in the backend.

TODO: This should be done via Horde_Log or the equivalent.

Parameters

mixed $message

Either a string or a PEAR_Error object.
string $priority

The priority of the message. One of:

  • EMERG
  • ALERT
  • CRIT
  • ERR
  • WARN
  • NOTICE
  • INFO
  • DEBUG

logFile()

logFile(integer  $type, string  $content, boolean  $wbxml = false, boolean  $sessionClose = false)

Logs data to a file in the debug directory.

Parameters

integer $type

The data type. One of the Horde_SyncMlBackend::LOGFILE* constants.
string $content

The data content.
boolean $wbxml

Whether the data is wbxml encoded.
boolean $sessionClose

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

close()

close()

Cleanup public function called after all message processing is finished.

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

getCurrentTimeStamp()

getCurrentTimeStamp() : mixed

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

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

Returns

mixed —

A timestamp of the current time.

testSetup()

testSetup(string  $user, string  $pwd)

Creates a clean test environment in the backend.

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

Parameters

string $user

This user accout has to be created in the backend.
string $pwd

The password for user $user.

Throws

\Horde_Exception

testStart()

testStart(string  $user)

Prepares the test start.

Parameters

string $user

This user accout has to be created in the backend.

testTearDown()

testTearDown()

Tears down the test environment after the test is run.

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

normalize()

normalize(string  $databaseURI) : string

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

Parameters

string $databaseURI

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

Returns

string —

The normalized database name.

getParameter()

getParameter(string  $url, string  $parameter, string  $default = null)

Extracts an HTTP GET like parameter from an URL.

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

Parameters

string $url

The complete URL.
string $parameter

The parameter name to extract.
string $default

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

getUserAnchors()

getUserAnchors(string  $user) : array

Returns all previously written sync anchors for a user.

Parameters

string $user

A user name.

Returns

array —

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

removeAnchor()

removeAnchor(string  $user, string  $device = null, string  $database = null) : array

Deletes previously written sync anchors for a user.

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

Parameters

string $user

A user name.
string $device

The ID of the client device.
string $database

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

Returns

array

removeMaps()

removeMaps(string  $user, string  $device = null, string  $database = null) : array

Deletes previously written sync maps for a user.

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

Parameters

string $user

A user name.
string $device

The ID of the client device.
string $database

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

Returns

array

_checkAuthentication()

_checkAuthentication(string  $username, string  $password) : boolean|string

Authenticates the user at the backend.

Parameters

string $username

A user name.
string $password

A password.

Returns

boolean|string —

The user name if authentication succeeded, false otherwise.

_setAuthenticated()

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

Sets a user as being authenticated at the backend.

Parameters

string $username

A user name.
string $credData

Authentication data provided by in the .

Returns

string —

The user name.

_fastsync()

_fastsync(  $databaseURI,   $from_ts,   $to_ts)

Parameters

$databaseURI
$from_ts
$to_ts

_slowsync()

_slowsync(  $databaseURI,   $from_ts,   $to_ts)

Parameters

$databaseURI
$from_ts
$to_ts

_getSuid()

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

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

Parameters

string $databaseURI

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

The client ID.

Returns

mixed —

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

_getCuid()

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

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

Parameters

string $databaseURI

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

The server ID.

Returns

mixed —

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

_getChangeTS()

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

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

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

string $databaseURI

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

The server ID.

Returns

mixed —

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