PHP Class Horde_SyncMl_Backend, horde

The backend provides the following groups of functions: 1) Access to the datastore Reading, adding, replacing and deleting of entries. Also retrieve information about changes in data store. This is done via the retrieveEntry(), addEntry(), replaceEntry(), deleteEntry() and getServerChanges() methods. 2) User management functions This is the checkAuthentication() method to verify that a given user password combination is allowed to access the backend data store, and the setUser() method which does a "login" to the backend data store if required by the type of backend data store. Please note that the password is only transferred once in a sync session, so when handling the subsequent packets messages, the user may need to be "logged in" without a password. (Or the session management keeps the user "logged in"). 3) Maintainig the client ID <-> server ID map The SyncML protocol does not require clients and servers to use the same primary keys for the data entries. So a map has to be in place to convert between client primary keys (called cuid's here) and server primary keys (called suid's). It's up to the server to maintain this map. Method for this is createUidMap(). 4) Sync anchor handling After a successful initial sync, the client and server sync timestamps are stored. This allows to perform subsequent syncs as delta syncs, where only new changes are replicated. Servers as well as clients need to be able to store two sync anchors (the client's and the server's) for a sync. Methods for this are readSyncAnchors() and writeSyncAnchors(). 5) Test supporting functions The SyncML module comes with its own testing framework. All you need to do is implement the two methods testSetup() and testTearDown() and you are able to test your backend with all the test cases that are part of the module. 6) Miscellaneous functions This involves session handling (sessionStart() and sessionClose()), logging (logMessage() and logFile()), timestamp creation (getCurrentTimeStamp()), charset handling (getCharset(), setCharset()) and database identification (isValidDatabaseURI()). For all of these functions, a default implementation is provided in Horde_SyncMl_Backend. If you want to create a backend for your own appliction, you can either derive from Horde_SyncMl_Backend and implement everything in groups 1 to 5 or you derive from Horde_SyncMl_Backend_Sql which implements an example backend based on direct database access using the PEAR MDB2 package. In this case you only need to implement groups 1 to 3 and can use the implementation from Horde_SyncMl_Backend_Sql as a guideline for these functions. Key Concepts ------------ In order to successfully create a backend, some understanding of a few key concepts in SyncML and the Horde_SyncMl package are certainly helpful. So here's some stuff that should make some issues clear (or at lest less obfuscated): 1) DatabaseURIs and Databases The SyncML protocol itself is completly independant from the data that is replicated. Normally the data are calendar or address book entries but it may really be anything from browser bookmarks to comeplete database tables. An ID (string name) of the database you want to actually replicate has to be configured in the client. Typically that's something like 'calendar' or 'tasks'. Client and server must agree on these names. In addition this string may be used to provide additional arguments. These are provided in a HTTP GET query style: like tasks?ignorecompletedtasks to replicate only pending tasks. Such a "sync identifier" is called a DatabaseURI and is really a database name plus some additional options. The Horde_SyncMl package completly ignores these options and simply passes them on to the backend. It's up to the backend to decide what to do with them. However when dealing with the internal maps (cuid<->suid and sync anchors), it's most likely to use the database name only rather than the full databaseURI. The map information saying that server entry [email protected] has id 768 in the client device is valid for the database "tasks", not for "tasks?somesillyoptions". So what you normally do is calling some kind of $database = $this->normalize($databaseURI) in every backend method that deals with databaseURIs and use $database afterwards. However actual usage of options is up to the backend implementation. SyncML works fine without. 2) Suid and Guid mapping This is the mapping of client IDs to server IDs and vice versa. Please note that this map is per user and per client device: the server entry [email protected] may have ID 720 in your PDA and AA10FC3A in your mobile phone. 3) Sync Anchors
Author: Karsten Fourmont ([email protected])
Exibir arquivo Open project: horde/horde Class Usage Examples

Public Properties

Property Type Description
$state Horde_SyncMl_State The State object.

Protected Properties

Property Type Description
$_backendMode integer The backend mode. One of the Horde_SyncMl_Backend::MODE_* constants.
$_charset string The charset used in the SyncML messages.
$_debugDir string The directory where debugging information is stored.
$_debugFiles boolean Whether to save SyncML messages in the debug directory.
$_logLevel string The log level.
$_logtext string The concatenated log messages.
$_syncDeviceID string 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 string The current user.

Public Methods

Method Description
__construct ( array $params ) Constructor.
addEntry ( string $databaseURI, string $content, string $contentType, string $cuid ) : array Adds an entry into the server database.
checkAuthentication ( string &$username, string $credData, string $credFormat, string $credType ) : boolean | string Authenticates the user at the backend.
close ( ) Cleanup public function called after all message processing is finished.
createUidMap ( string $databaseURI, string $cuid, string $suid, integer $timestamp ) Creates a map entry to map between server and client IDs.
deleteEntry ( string $databaseURI, string $cuid ) : boolean Deletes an entry from the server database.
eraseMap ( string $databaseURI ) Erases all mapping entries for one combination of user, device ID.
factory ( string $driver, array $params = null ) : 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 ( string $url, string $parameter, string $default = null ) Extracts an HTTP GET like parameter from an URL.
getServerChanges ( string $databaseURI, integer $from_ts, integer $to_ts, &$adds, &$mods, &$dels ) : mixed Returns entries that have been modified in the server database.
getSyncDeviceID ( ) : string Returns the current device's ID.
getUser ( ) : string Returns the current user.
isValidDatabaseURI ( string $databaseURI ) : boolean Returns whether a database URI is valid to be synced with this backend.
logFile ( integer $type, string $content, boolean $wbxml = false, boolean $sessionClose = false ) Logs data to a file in the debug directory.
logMessage ( mixed $message, integer $priority = 'INFO' ) Logs a message in the backend.
normalize ( string $databaseURI ) : string Normalizes a databaseURI to a database name, so that _normalize('tasks?ignorecompleted') should return just 'tasks'.
readSyncAnchors ( string $databaseURI ) : mixed Reads the previously written sync anchors from the database.
replaceEntry ( string $databaseURI, string $content, string $contentType, string $cuid ) : string Replaces an entry in the server database.
retrieveEntry ( string $databaseURI, string $suid, string $contentType, array $fields ) : mixed Retrieves an entry from the backend.
sessionClose ( ) Closes the PHP session.
sessionStart ( string $syncDeviceID, $sessionId, integer $backendMode = Horde_SyncMl_Backend::MODE_SERVER ) Starts a PHP session.
setCharset ( string $charset ) Sets the charset.
setUser ( string $user ) Sets the user used for this session.
setupState ( ) Is called after the Horde_SyncMl_State object has been set up, either restored from the session, or freshly created.
testSetup ( string $user, string $pwd ) Creates a clean test environment in the backend.
testStart ( string $user ) Prepares the test start.
testTearDown ( ) Tears down the test environment after the test is run.
writeSyncAnchors ( string $databaseURI, string $clientAnchorNext, string $serverAnchorNext ) Stores Sync anchors after a successful synchronization to allow two-way synchronization next time.

Protected Methods

Method Description
_checkAuthentication ( string $username, string $password ) : boolean | string Authenticates the user at the backend.
_setAuthenticated ( string $username, string $credData ) : string Sets a user as being authenticated at the backend.

Method Details

__construct() public method

Sets up the default logging mechanism.
public __construct ( array $params )
$params array A hash with parameters. The following are supported by the default implementation. Individual backends may support other parameters. - debug_dir: A directory to write debug output to. Must be writeable by the web server. - debug_files: If true, log all incoming and outgoing packets and data conversions and devinf log in debug_dir. - log_level: Only log entries with at least this level. Defaults to 'INFO'.

_checkAuthentication() protected method

Authenticates the user at the backend.
protected _checkAuthentication ( string $username, string $password ) : boolean | string
$username string A user name.
$password string A password.
return boolean | string The user name if authentication succeeded, false otherwise.

_setAuthenticated() protected method

Sets a user as being authenticated at the backend.
protected _setAuthenticated ( string $username, string $credData ) : string
$username string A user name.
$credData string Authentication data provided by in the .
return string The user name.

addEntry() public method

Adds an entry into the server database.
public addEntry ( string $databaseURI, string $content, string $contentType, string $cuid ) : array
$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 array PEAR_Error or suid (Horde guid) of new entry

checkAuthentication() public method

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 .
public checkAuthentication ( string &$username, string $credData, string $credFormat, string $credType ) : boolean | string
$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 boolean | string The user name if authentication succeeded, false otherwise.

close() public method

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

createUidMap() public method

If an entry already exists, it is overwritten.
public createUidMap ( string $databaseURI, string $cuid, string $suid, integer $timestamp )
$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 integer 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".

deleteEntry() public method

Deletes an entry from the server database.
public deleteEntry ( string $databaseURI, string $cuid ) : boolean
$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 boolean True on success or false on failed (item not found).

eraseMap() public method

This is used during SlowSync so that we really sync everything properly and no old mapping entries remain.
public eraseMap ( string $databaseURI )
$databaseURI string URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

factory() public method

Attempts to return a concrete Horde_SyncMl_Backend instance based on $driver.
public factory ( string $driver, array $params = null ) : Horde_SyncMl_Backend
$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 A hash containing any additional configuration or connection parameters a subclass might need.
return Horde_SyncMl_Backend The newly created concrete Horde_SyncMl_Backend instance, or false on an error.

getCharset() public method

Returns the charset.
public getCharset ( ) : string
return string The charset used when talking to the backend.

getCurrentTimeStamp() public method

Backends can use their own way to represent timestamps, like unix epoch integers or UTC Datetime strings.
public getCurrentTimeStamp ( ) : mixed
return mixed A timestamp of the current time.

getParameter() public method

Example: getParameter('test?q=1', 'q') == 1
public getParameter ( string $url, string $parameter, string $default = null )
$url string The complete URL.
$parameter string The parameter name to extract.
$default string A default value to return if none has been provided in the URL.

getServerChanges() public method

Returns entries that have been modified in the server database.
public getServerChanges ( string $databaseURI, integer $from_ts, integer $to_ts, &$adds, &$mods, &$dels ) : mixed
$databaseURI string URI of Database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
$from_ts integer Start timestamp.
$to_ts integer Exclusive end timestamp. Not yet implemented.
return mixed True on success or a PEAR_Error object.

getSyncDeviceID() public method

Returns the current device's ID.
public getSyncDeviceID ( ) : string
return string The device ID.

getUser() public method

Returns the current user.
public getUser ( ) : string
return string The current user.

isValidDatabaseURI() public method

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).
public isValidDatabaseURI ( string $databaseURI ) : boolean
$databaseURI string URI of a database. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
return boolean True if a valid URI.

logFile() public method

Logs data to a file in the debug directory.
public logFile ( integer $type, string $content, boolean $wbxml = false, boolean $sessionClose = false )
$type integer The data type. One of the Horde_SyncMl_Backend::LOGFILE_* constants.
$content string The data content.
$wbxml boolean Whether the data is wbxml encoded.
$sessionClose boolean Whether this is the last SyncML message in a session. Bump the file number.

logMessage() public method

TODO: This should be done via Horde_Log or the equivalent.
public logMessage ( mixed $message, integer $priority = 'INFO' )
$message mixed Either a string or a PEAR_Error object.
$priority integer The priority of the message. One of: - EMERG - ALERT - CRIT - ERR - WARN - NOTICE - INFO - DEBUG

normalize() public method

Normalizes a databaseURI to a database name, so that _normalize('tasks?ignorecompleted') should return just 'tasks'.
public normalize ( string $databaseURI ) : string
$databaseURI string URI of a database. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
return string The normalized database name.

readSyncAnchors() public method

Reads the previously written sync anchors from the database.
public readSyncAnchors ( string $databaseURI ) : mixed
$databaseURI string URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.
return mixed Two-element array with client anchor and server anchor as stored in previous writeSyncAnchor() calls. False if no data found.

replaceEntry() public method

Replaces an entry in the server database.
public replaceEntry ( string $databaseURI, string $content, string $contentType, string $cuid ) : string
$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 string PEAR_Error or server ID (Horde GUID) of modified entry.

retrieveEntry() public method

Retrieves an entry from the backend.
public retrieveEntry ( string $databaseURI, string $suid, string $contentType, array $fields ) : mixed
$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 Hash of field names and Horde_SyncMl_Property properties with the requested fields.
return mixed A string with the data entry or a PEAR_Error object.

sessionClose() public method

Closes the PHP session.
public sessionClose ( )

sessionStart() public method

Starts a PHP session.
public sessionStart ( string $syncDeviceID, $sessionId, integer $backendMode = Horde_SyncMl_Backend::MODE_SERVER )
$syncDeviceID string The device ID.
$backendMode integer The backend mode, one of the Horde_SyncMl_Backend::MODE_* constants.

setCharset() public method

All data passed to the backend uses this charset and data returned from the backend must use this charset, too.
public setCharset ( string $charset )
$charset string A valid charset.

setUser() public method

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.
public setUser ( string $user )
$user string A user name.

setupState() public method

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

testSetup() public method

Ensures there's a user with the given credentials and an empty data store.
public testSetup ( string $user, string $pwd )
$user string This user accout has to be created in the backend.
$pwd string The password for user $user.

testStart() public method

Prepares the test start.
public testStart ( string $user )
$user string This user accout has to be created in the backend.

testTearDown() public method

Tears down the test environment after the test is run.
public testTearDown ( )

writeSyncAnchors() public method

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.
public writeSyncAnchors ( string $databaseURI, string $clientAnchorNext, string $serverAnchorNext )
$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.

Property Details

$_backendMode protected_oe property

The backend mode. One of the Horde_SyncMl_Backend::MODE_* constants.
protected int $_backendMode
return integer

$_charset protected_oe property

The charset used in the SyncML messages.
protected string $_charset
return string

$_debugDir protected_oe property

The directory where debugging information is stored.
See also: Horde_SyncMl_Backend()
protected string $_debugDir
return string

$_debugFiles protected_oe property

Whether to save SyncML messages in the debug directory.
See also: Horde_SyncMl_Backend()
protected bool $_debugFiles
return boolean

$_logLevel protected_oe property

The log level.
See also: Horde_SyncMl_Backend()
protected string $_logLevel
return string

$_logtext protected_oe property

The concatenated log messages.
protected string $_logtext
return string

$_syncDeviceID protected_oe property

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.
protected string $_syncDeviceID
return string

$_user protected_oe property

The current user.
protected string $_user
return string

$state public_oe property

The State object.
public Horde_SyncMl_State $state
return Horde_SyncMl_State