Class SyncML_Backend

Description

Located in /SyncML/SyncML/Backend.php (line 190)


	
			
Direct descendents
Variable Summary
 integer $_backendMode
 string $_charset
 string $_debugDir
 boolean $_debugFiles
 integer $_logLevel
 string $_logtext
 string $_user
Method Summary
 static void getParameter (string $url, string $parameter, [string $default = null])
 SyncML_Backend SyncML_Backend (array $params)
 array addEntry (string $databaseURI, string $content, string $contentType, string $cuid)
 boolean|string checkAuthentication ( &$username, string $credData, string $credFormat, string $credType, string $username)
 void close ()
 void createUidMap (string $databaseURI, string $cuid, string $suid, [integer $timestamp = 0])
 boolean deleteEntry (string $databaseURI, string $cuid)
 void eraseMap (string $databaseURI)
 SyncML_Backend factory (string $driver, [array $params = null])
 string getCharset ()
 mixed getServerChanges (string $databaseURI, integer $from_ts, integer $to_ts, array &$adds, array &$mods, array &$dels)
 string getSyncDeviceID ()
 string getUser ()
 boolean isValidDatabaseURI (string $databaseURI)
 void logFile (integer $type, string $content, [boolean $wbxml = false], [boolean $sessionClose = false])
 void logMessage (mixed $message, string $file, integer $line, [integer $priority = PEAR_LOG_INFO])
 mixed readSyncAnchors (string $databaseURI)
 string replaceEntry (string $databaseURI, string $content, string $contentType, string $cuid)
 mixed retrieveEntry (string $databaseURI, string $suid, string $contentType, array $fields)
 void sessionClose ()
 void sessionStart (string $syncDeviceID,  $sessionId, [integer $backendMode = SYNCML_BACKENDMODE_SERVER], string $session_id)
 string setAuthenticated (string $username, string $credData)
 void setCharset (string $charset)
 void setupState (SyncML_State &$state)
 void setUser (string $user)
 void testSetup (string $user, string $pwd)
 void testStart (string $user)
 void testTearDown ()
 void writeSyncAnchors (string $databaseURI, string $clientAnchorNext, string $serverAnchorNext)
 boolean|string _checkAuthentication (string $username, string $password)
 string _normalize (string $databaseURI)
Variables
integer $_backendMode (line 255)

The backend mode. One of the SYNCML_BACKENDMODE_* constants.

string $_charset (line 229)

The charset used in the SyncML messages.

string $_debugDir (line 205)

The directory where debugging information is stored.

boolean $_debugFiles (line 213)

Whether to save SyncML messages in the debug directory.

integer $_logLevel = PEAR_LOG_INFO (line 222)

The log level. One of the PEAR_LOG_* constants.


Redefined in descendants as:
string $_logtext = '' (line 197)

The concatenated log messages.

string $_syncDeviceID (line 248)

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.

string $_user (line 236)

The current user.

Methods
static getParameter (line 1042)

Extracts an HTTP GET like parameter from an URL.

Example:

  1. getParameter('test?q=1''q'== 1

static void getParameter (string $url, string $parameter, [string $default = null])
  • 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.
Constructor SyncML_Backend (line 276)

Constructor.

Sets up the default logging mechanism.

SyncML_Backend SyncML_Backend (array $params)
  • array $params: 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: PEAR_LOG_*. Only log entries with at least this level. Defaults to PEAR_LOG_INFO.
addEntry (line 534)

Adds an entry into the server database.

  • return: PEAR_Error or suid (Horde guid) of new entry
  • abstract:
array addEntry (string $databaseURI, string $content, string $contentType, string $cuid)
  • 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.

Redefined in descendants as:
checkAuthentication (line 599)

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

  • return: The user name if authentication succeeded, false otherwise.
boolean|string checkAuthentication ( &$username, string $credData, string $credFormat, string $credType, string $username)
  • string $username: Username as provided in the <SyncHdr>. May be overwritten by $credData.
  • string $credData: Authentication data provided by <Cred><Data> in the <SyncHdr>.
  • string $credFormat: Format of data as <Cread><Meta><Format> in the <SyncHdr>. Typically 'b64'.
  • string $credType: Auth type as provided by <Cred><Meta><Type> in the <SyncHdr>. Typically 'syncml:auth-basic'.
  • &$username
close (line 921)

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

void close ()

Redefined in descendants as:
createUidMap (line 742)

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

If an entry already exists, it is overwritten.

  • abstract:
void createUidMap (string $databaseURI, string $cuid, string $suid, [integer $timestamp = 0])
  • 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".

Redefined in descendants as:
deleteEntry (line 572)

Deletes an entry from the server database.

  • return: True on success or false on failed (item not found).
  • abstract:
boolean deleteEntry (string $databaseURI, string $cuid)
  • 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.

Redefined in descendants as:
eraseMap (line 759)

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.

  • abstract:
void eraseMap (string $databaseURI)
  • string $databaseURI: URI of database to sync. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

Redefined in descendants as:
factory (line 308)

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

  • return: The newly created concrete SyncML_Backend instance, or false on an error.
SyncML_Backend factory (string $driver, [array $params = null])
  • 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 'SyncML_Backend_' . basename($driver) and extend SyncML_Backend.
  • array $params: A hash containing any additional configuration or connection parameters a subclass might need.
getCharset (line 349)

Returns the charset.

  • return: The charset used when talking to the backend.
string getCharset ()
getCurrentTimeStamp (line 942)

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.

  • return: A timestamp of the current time.
mixed getCurrentTimeStamp ()
getServerChanges (line 490)

Returns entries that have been modified in the server database.

  • return: True on success or a PEAR_Error object.
  • abstract:
mixed getServerChanges (string $databaseURI, integer $from_ts, integer $to_ts, array &$adds, array &$mods, array &$dels)
  • 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.
  • array &$adds: Output array: hash of adds suid => 0
  • array &$mods: Output array: hash of modifications suid => cuid
  • array &$dels: Output array: hash of deletions suid => cuid

Redefined in descendants as:
getSyncDeviceID (line 359)

Returns the current device's ID.

  • return: The device ID.
string getSyncDeviceID ()
getUser (line 387)

Returns the current user.

  • return: The current user.
string getUser ()
isValidDatabaseURI (line 451)

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

  • return: True if a valid URI.
boolean isValidDatabaseURI (string $databaseURI)
  • string $databaseURI: URI of a database. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

Redefined in descendants as:
logFile (line 836)

Logs data to a file in the debug directory.

void logFile (integer $type, string $content, [boolean $wbxml = false], [boolean $sessionClose = false])
  • integer $type: The data type. One of the SYNCML_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.

Redefined in descendants as:
logMessage (line 781)

Logs a message in the backend.

void logMessage (mixed $message, string $file, integer $line, [integer $priority = PEAR_LOG_INFO])
  • mixed $message: Either a string or a PEAR_Error object.
  • string $file: What file was the log function called from (e.g. __FILE__)?
  • integer $line: What line was the log function called from (e.g. __LINE__)?
  • integer $priority: The priority of the message. One of:
    • PEAR_LOG_EMERG
    • PEAR_LOG_ALERT
    • PEAR_LOG_CRIT
    • PEAR_LOG_ERR
    • PEAR_LOG_WARNING
    • PEAR_LOG_NOTICE
    • PEAR_LOG_INFO
    • PEAR_LOG_DEBUG

Redefined in descendants as:
readSyncAnchors (line 717)

Reads the previously written sync anchors from the database.

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

Redefined in descendants as:
replaceEntry (line 554)

Replaces an entry in the server database.

  • return: PEAR_Error or server ID (Horde GUID) of modified entry.
  • abstract:
string replaceEntry (string $databaseURI, string $content, string $contentType, string $cuid)
  • 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.

Redefined in descendants as:
retrieveEntry (line 514)

Retrieves an entry from the backend.

  • return: A string with the data entry or a PEAR_Error object.
  • abstract:
mixed retrieveEntry (string $databaseURI, string $suid, string $contentType, array $fields)
  • 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 function should return the data.
  • array $fields: Hash of field names and SyncML_Property properties with the requested fields.

Redefined in descendants as:
sessionClose (line 427)

Closes the PHP session.

void sessionClose ()
sessionStart (line 410)

Starts a PHP session.

void sessionStart (string $syncDeviceID,  $sessionId, [integer $backendMode = SYNCML_BACKENDMODE_SERVER], string $session_id)
  • string $syncDeviceID: The device ID.
  • string $session_id: The session ID to use.
  • integer $backendMode: The backend mode, one of the SYNCML_BACKENDMODE_* constants.
  • $sessionId

Redefined in descendants as:
setAuthenticated (line 674)

Sets a user as being authenticated at the backend.

  • return: The user name.
  • abstract:
string setAuthenticated (string $username, string $credData)
  • string $username: A user name.
  • string $credData: Authentication data provided by <Cred><Data> in the <SyncHdr>.

Redefined in descendants as:
setCharset (line 339)

Sets the charset.

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

void setCharset (string $charset)
  • string $charset: A valid charset.

Redefined in descendants as:
setupState (line 398)

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

void setupState (SyncML_State &$state)

Redefined in descendants as:
setUser (line 377)

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.

void setUser (string $user)
  • string $user: A user name.

Redefined in descendants as:
testSetup (line 959)

Creates a clean test environment in the backend.

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

  • abstract:
void testSetup (string $user, string $pwd)
  • string $user: This user accout has to be created in the backend.
  • string $pwd: The password for user $user.

Redefined in descendants as:
testStart (line 969)

Prepares the test start.

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

Redefined in descendants as:
testTearDown (line 981)

Tears down the test environment after the test is run.

  • abstract: Should remove the testuser created during testSetup and all its data.
void testTearDown ()

Redefined in descendants as:
writeSyncAnchors (line 698)

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.

  • abstract:
void writeSyncAnchors (string $databaseURI, string $clientAnchorNext, string $serverAnchorNext)
  • 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.

Redefined in descendants as:
_checkAuthentication (line 658)

Authenticates the user at the backend.

  • return: The user name if authentication succeeded, false otherwise.
  • abstract:
boolean|string _checkAuthentication (string $username, string $password)
  • string $username: A user name.
  • string $password: A password.

Redefined in descendants as:
_normalize (line 997)

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

  • return: The normalized database name.
string _normalize (string $databaseURI)
  • string $databaseURI: URI of a database. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.

Documentation generated on Sun, 30 Jan 2011 05:15:24 +0000 by phpDocumentor 1.4.3