Documentation

Horde_SyncMl_Backend_Horde extends Horde_SyncMl_Backend
in package

SyncMl

SyncML Backend for the Horde Application framework.

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

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

$state

The State object.


    public
        Horde_SyncMl_State
    $state

$_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

$_debugFiles

Whether to save SyncML messages in the debug directory.


    protected
        bool
    $_debugFiles

$_logLevel

The log level.


    protected
        string
    $_logLevel
     = 'INFO'

$_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

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

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.

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 .

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 —

Horde_SyncMl_Backend_Horde extends Horde_SyncMl_Backend in package SyncMl

Tags

Table of Contents

Constants

LOGFILE_CLIENTMESSAGE

LOGFILE_DATA

LOGFILE_DEVINF

LOGFILE_SERVERMESSAGE

MODE_CLIENT

MODE_SERVER

MODE_TEST

Properties

$state

$_backendMode

$_charset

$_db

$_debugDir

Tags

$_debugFiles

Tags

$_logLevel

Tags

$_logtext

$_sessionId

$_syncDeviceID

$_user

Methods

__construct()

Parameters

Return values

addEntry()

Parameters

Return values

checkAuthentication()

Parameters

Return values

close()

Return values

createUidMap()

Parameters

Return values

deleteEntry()

Parameters

Return values

eraseMap()

Parameters

Return values

factory()

Parameters

Return values

getCharset()

Return values

getCurrentTimeStamp()

Return values

getParameter()

Parameters

Tags

Return values

getServerChanges()

Parameters

Return values

getSyncDeviceID()

Return values

getUser()

Return values

getUserAnchors()

Parameters

Return values

isValidDatabaseURI()

Parameters

Return values

logFile()

Parameters

Return values

logMessage()

Parameters

Return values

normalize()

Parameters

Return values

Horde_SyncMl_Backend_Horde extends Horde_SyncMl_Backend
in package

SyncMl