Extracts an HTTP GET like parameter from an URL.
Example:
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.
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.
Adds an entry into the server database.
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:
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>.
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
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:
Creates a map entry to map between server and client IDs.
If an entry already exists, it is overwritten.
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:
Deletes an entry from the server database.
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:
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.
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:
Attempts to return a concrete SyncML_Backend instance based on $driver.
-
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.
Returns the charset.
string
getCharset
()
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.
mixed
getCurrentTimeStamp
()
Returns entries that have been modified in the server database.
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:
Returns the current device's ID.
string
getSyncDeviceID
()
Returns the current user.
string
getUser
()
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).
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:
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:
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:
Reads the previously written sync anchors from the database.
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:
Replaces an entry in the server database.
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:
Retrieves an entry from the backend.
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:
Closes the PHP session.
void
sessionClose
()
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:
Sets a user as being authenticated at the backend.
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:
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:
Is called after the SyncML_State object has been set up, either restored from the session, or freshly created.
Redefined in descendants as:
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:
Creates a clean test environment in the backend.
Ensures there's a user with the given credentials and an empty data store.
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:
Prepares the test start.
void
testStart
(string $user)
-
string
$user: This user accout has to be created in the backend.
Redefined in descendants as:
Tears down the test environment after the test is run.
void
testTearDown
()
Redefined in descendants as:
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.
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:
Authenticates the user at the backend.
boolean|string
_checkAuthentication
(string $username, string $password)
-
string
$username: A user name.
-
string
$password: A password.
Redefined in descendants as:
Normalizes a databaseURI to a database name, so that _normalize('tasks?ignorecompleted') should return just 'tasks'.
string
_normalize
(string $databaseURI)
-
string
$databaseURI: URI of a database. Like calendar, tasks, contacts or notes. May include optional parameters: tasks?options=ignorecompleted.