• Главная
• Horde_SyncMl_Backend

PHP Класс 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

Автор: Karsten Fourmont ([email protected])

Показать файл Открыть проект Примеры использования класса

Открытые свойства

Свойство	Тип	Описание
$state	Horde_SyncMl_State	The State object.

Защищенные свойства (Protected)

Свойство	Тип	Описание
$_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.

Открытые методы

Метод	Описание
__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.

Защищенные методы

Метод	Описание
_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.

Описание методов

__construct() публичный Метод

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() защищенный Метод

Authenticates the user at the backend.

protected _checkAuthentication ( string $username, string $password ) : boolean | string
$username	string	A user name.
$password	string	A password.
Результат	boolean | string	The user name if authentication succeeded, false otherwise.

_setAuthenticated() защищенный Метод

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 .
Результат	string	The user name.

addEntry() публичный Метод

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.
Результат	array	PEAR_Error or suid (Horde guid) of new entry

checkAuthentication() публичный Метод

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'.
Результат	boolean | string	The user name if authentication succeeded, false otherwise.

close() публичный Метод

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

public close ( )

createUidMap() публичный Метод

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() публичный Метод

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.
Результат	boolean	True on success or false on failed (item not found).

eraseMap() публичный Метод

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() публичный Метод

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.
Результат	Horde_SyncMl_Backend	The newly created concrete Horde_SyncMl_Backend instance, or false on an error.

getCharset() публичный Метод

Returns the charset.

public getCharset ( ) : string
Результат	string	The charset used when talking to the backend.

getCurrentTimeStamp() публичный Метод

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

public getCurrentTimeStamp ( ) : mixed
Результат	mixed	A timestamp of the current time.

getParameter() публичный Метод

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() публичный Метод

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.
Результат	mixed	True on success or a PEAR_Error object.

getSyncDeviceID() публичный Метод

Returns the current device's ID.

public getSyncDeviceID ( ) : string
Результат	string	The device ID.

getUser() публичный Метод

Returns the current user.

public getUser ( ) : string
Результат	string	The current user.

isValidDatabaseURI() публичный Метод

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.
Результат	boolean	True if a valid URI.

logFile() публичный Метод

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() публичный Метод

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() публичный Метод

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.
Результат	string	The normalized database name.

readSyncAnchors() публичный Метод

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.
Результат	mixed	Two-element array with client anchor and server anchor as stored in previous writeSyncAnchor() calls. False if no data found.

replaceEntry() публичный Метод

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.
Результат	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 $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.
Результат	mixed	A string with the data entry or a PEAR_Error object.

sessionClose() публичный Метод

Closes the PHP session.

public sessionClose ( )

sessionStart() публичный Метод

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() публичный Метод

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() публичный Метод

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() публичный Метод

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

public setupState ( )

testSetup() публичный Метод

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() публичный Метод

Prepares the test start.

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

testTearDown() публичный Метод

Tears down the test environment after the test is run.

public testTearDown ( )

writeSyncAnchors() публичный Метод

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.

Описание свойств

$_backendMode защищенное свойство

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

protected int $_backendMode
Результат	integer

$_charset защищенное свойство

The charset used in the SyncML messages.

protected string $_charset
Результат	string

$_debugDir защищенное свойство

The directory where debugging information is stored.

См. также: Horde_SyncMl_Backend()

protected string $_debugDir
Результат	string

$_debugFiles защищенное свойство

Whether to save SyncML messages in the debug directory.

См. также: Horde_SyncMl_Backend()

protected bool $_debugFiles
Результат	boolean

$_logLevel защищенное свойство

The log level.

См. также: Horde_SyncMl_Backend()

protected string $_logLevel
Результат	string

$_logtext защищенное свойство

The concatenated log messages.

protected string $_logtext
Результат	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.

protected string $_syncDeviceID
Результат	string

$_user защищенное свойство

The current user.

protected string $_user
Результат	string

$state публичное свойство

The State object.

public Horde_SyncMl_State $state
Результат	Horde_SyncMl_State