Documentation

Horde_ActiveSync_Driver_Base
in package

Base ActiveSync Driver backend. Provides communication with the actual server backend that ActiveSync will be syncing devices with. This is an abstract class, servers must implement their own backend to provide the needed data.

Tags
license

http://www.horde.org/licenses/gpl GPLv2

copyright

2010-2020 Horde LLC (http://www.horde.org)

author

Michael J Rubinsky mrubinsk@horde.org

Table of Contents

$_authPass  : string
User password
$_authUser  : string
Authenticating user
$_device  : Horde_ActiveSync_Device
The device object
$_logger  : Horde_Log_Logger
Logger instance
$_params  : array<string|int, mixed>
Parameters
$_state  : Horde_ActiveSync_State_Base
The state driver for this request. Needs to be injected into this class.
$_tempMap  : array<string|int, mixed>
Temporary serverid to uid map. Used when creating the hierarchy for the first time
$_typeMap  : mixed
$_user  : string
The username to sync with the backend as
$_version  : float
Protocol version
__construct()  : Horde_ActiveSync_Driver
Const'r
__destruct()  : mixed
Prevent circular dependency issues.
addDefaultBodyPrefTruncation()  : array<string|int, mixed>
Add default truncation values for this driver.
authenticate()  : mixed
Any code needed to authenticate to backend as the actual user.
autoDiscover()  : array<string|int, mixed>
Return properties for an AUTODISCOVER request.
buildFbString()  : string
Build a EAS style FB string. Essentially, each digit represents 1/2 hour.
changeFolder()  : Horde_ActiveSync_Message_Folder
Change a folder on the server.
changeMessage()  : array<string|int, mixed>|bool
Add/Edit a message
clearAuthentication()  : bool
Clear authentication
deleteFolder()  : mixed
Delete a folder on the server.
deleteMessage()  : mixed
Delete a message
fetch()  : Horde_ActiveSync_Message_Base
Obtain the FULL message from the backend, regardless of any truncation options.
getAttachment()  : array<string|int, mixed>
Return the specified attachment.
getCurrentPolicy()  : array<string|int, mixed>
Return the security policies.
getFolder()  : Horde_ActiveSync_Message_Folder
Return the ActiveSync message object for the specified folder.
getFolderList()  : array<string|int, mixed>
Get the list of folder stat arrays @see self::statFolder()
getFolders()  : array<string|int, mixed>
Return an array of folder objects.
getFreebusy()  : mixed
Request freebusy information from the server
getHeartbeatConfig()  : array<string|int, mixed>
Obtain the ping heartbeat settings
getMessage()  : Horde_ActiveSync_Message_Base
Obtain an ActiveSync message from the backend.
getProvisioning()  : mixed
Returns the provisioning support for the current request.
getSearchResults()  : array<string|int, mixed>
Returns array of items which contain contact information
getServerChanges()  : array<string|int, mixed>
Get a list of server changes that occured during the specified time period.
getSettings()  : array<string|int, mixed>
Return settings from the backend for a SETTINGS request.
getSpecialFolderNameByType()  : string
Return the server id of the specified special folder type.
getSyncStamp()  : int
Return the SyncStamp - the value used to determine the end of the current sync range. Default implementation uses timestamps. Concrete drivers can override this to provide another method to do this, such as using modification sequences.
getUser()  : string
Get the username for this request.
getUsernameFromEmail()  : string
Attempt to guess a username based on the email address passed from EAS Autodiscover requests.
getWasteBasket()  : string|bool
Get the wastebasket folder.
itemOperationsFetchMailbox()  : Horde_ActiveSync_Message_Base
Returnmail object represented by the specified longid. Used to fetch email objects from a search result, which only returns a 'longid'.
itemOperationsGetAttachmentData()  : mixed
Return the specified attachement data for an ITEMOPERATIONS request.
itemOperationsGetDocumentLibraryLink()  : array<string|int, mixed>
Return a documentlibrary item.
meetingResponse()  : string
Hanlde meeting responses.
moveMessage()  : array<string|int, mixed>
Move message
resolveRecipient()  : array<string|int, mixed>
Handle ResolveRecipient requests
sendMail()  : bool
Sends the email represented by the rfc822 string received by the client.
setDevice()  : mixed
Set the currently connected device
setLogger()  : mixed
Setter for the logger instance
setProtocolVersion()  : mixed
Set the protocol version. Can't do it in constructer since we don't know the version at the time this driver is instantiated.
setReadFlag()  : mixed
Set the read (\seen) flag on the specified message.
setSettings()  : array<string|int, mixed>
Set backend settings from a SETTINGS request.
setup()  : bool
Setup sync parameters. The user provided here is the user the backend will sync with. This allows you to authenticate as one user, and sync as another, if the backend supports this.
statFolder()  : a
Stat folder. Note that since the only thing that can ever change for a folder is the name, we use that as the 'mod' value.
statMailMessage()  : array<string|int, mixed>
Build a stat structure for an email message.
statMessage()  : hash
Get a message stat.
_getClassFromType()  : string
Convert a TYPE constant into it's associated CLASS constant.
_getFolderUidForBackendId()  : string
Get an activesync uid for the given backend serverid. If we've seen this serverid before, return the previously created uid, otherwise return a new one.
_isSpecialMailbox()  : true
Return if the specified folder is a special folder.

Properties

$_authPass

User password

protected string $_authPass

$_authUser

Authenticating user

protected string $_authUser

$_logger

Logger instance

protected Horde_Log_Logger $_logger

$_params

Parameters

protected array<string|int, mixed> $_params

$_tempMap

Temporary serverid to uid map. Used when creating the hierarchy for the first time

protected array<string|int, mixed> $_tempMap = array()

$_typeMap

protected mixed $_typeMap = array('F' => \Horde_ActiveSync::CLASS_EMAIL, 'C' => \Horde_ActiveSync::CLASS_CONTACTS, 'A' => \Horde_ActiveSync::CLASS_CALENDAR, 'T' => \Horde_ActiveSync::CLASS_TASKS, 'N' => \Horde_ActiveSync::CLASS_NOTES)

$_user

The username to sync with the backend as

protected string $_user

$_version

Protocol version

protected float $_version = \Horde_ActiveSync::VERSION_FOURTEENONE

Methods

__construct()

Const'r

public __construct([array<string|int, mixed> $params = array() ]) : Horde_ActiveSync_Driver
Parameters
$params : array<string|int, mixed> = array()

Any configuration parameters or injected objects the concrete driver may need.

  • logger: (Horde_Log_Logger) The logger. DEFAULT: none (No logging).
  • state: (Horde_ActiveSync_State_Base) The state driver. DEFAULT: none (REQUIRED).
Return values
Horde_ActiveSync_Driver

__destruct()

Prevent circular dependency issues.

public __destruct() : mixed
Return values
mixed

addDefaultBodyPrefTruncation()

Add default truncation values for this driver.

public addDefaultBodyPrefTruncation(array<string|int, mixed> $bodyprefs) : array<string|int, mixed>
Parameters
$bodyprefs : array<string|int, mixed>

BODYPREFERENCE data.

Tags
deprecated

Will be removed in 3.0. We don't need and indeed shouldn't set default values for truncationsize. Not to mention we were setting the incorrect constant value instead of the byte value.

todo
Return values
array<string|int, mixed>

The BODYPREFERENCE data, with default truncationsize values.

authenticate()

Any code needed to authenticate to backend as the actual user.

public authenticate(string $username, string $password[, string $domain = null ]) : mixed
Parameters
$username : string

The username to authenticate as

$password : string

The password

$domain : string = null

The user domain (unused in this driver).

Return values
mixed

Boolean true on success, boolean false on credential failure or Horde_ActiveSync::AUTH_REASON_* constant on policy failure.

autoDiscover()

Return properties for an AUTODISCOVER request.

public abstract autoDiscover() : array<string|int, mixed>
Tags
todo

Purposely leaving out parameters from the signature to avoid php warnings when using older implementations that only take the one argument.

Return values
array<string|int, mixed>

An array of properties.

buildFbString()

Build a EAS style FB string. Essentially, each digit represents 1/2 hour.

public static buildFbString(stdClass $fb, Horde_Date $start, Horde_Date $end) : string

The values are as follows: 0 - Free 1 - Tentative 2 - Busy 3 - OOF 4 - No data available.

Though currently we only provide a Free/Busy/Unknown differentiation.

Parameters
$fb : stdClass

The fb information. An object containing:

  • s: The start of the period covered.
  • e: The end of the period covered.
  • b: An array of busy periods.
$start : Horde_Date

The start of the period requested by the client.

$end : Horde_Date

The end of the period requested by the client.

Tags
since
2.4.0
Return values
string

The EAS freebusy string.

changeFolder()

Change a folder on the server.

public abstract changeFolder(string $id, string $displayname, string $parent[, string $uid = null ]) : Horde_ActiveSync_Message_Folder
Parameters
$id : string

The server's folder id

$displayname : string

The new display name.

$parent : string

The folder's parent, if needed.

$uid : string = null

The existing folder uid, if this is an edit. @since 2.9.0 (@todo Look at this for H6. It's here now to save an extra DB lookup for data we already have.)

Tags
throws
Horde_ActiveSync_Exception
Return values
Horde_ActiveSync_Message_Folder

changeMessage()

Add/Edit a message

public abstract changeMessage(string $folderid, string $id, Horde_ActiveSync_Message_Base $message, Horde_ActiveSync_Device $device) : array<string|int, mixed>|bool
Parameters
$folderid : string

The server id for the folder the message belongs to.

$id : string

The server's uid for the message if this is a change to an existing message, null if new.

$message : Horde_ActiveSync_Message_Base

The activesync message

$device : Horde_ActiveSync_Device

The device information

Return values
array<string|int, mixed>|bool

A stat array if successful, otherwise false.

clearAuthentication()

Clear authentication

public clearAuthentication() : bool
Return values
bool

deleteFolder()

Delete a folder on the server.

public abstract deleteFolder(string $id[, string $parent = Horde_ActiveSync::FOLDER_ROOT ]) : mixed
Parameters
$id : string

The server's folder id.

$parent : string = Horde_ActiveSync::FOLDER_ROOT

The folder's parent, if needed.

Return values
mixed

deleteMessage()

Delete a message

public abstract deleteMessage(string $folderid, array<string|int, mixed> $ids) : mixed
Parameters
$folderid : string

The folder id containing the messages.

$ids : array<string|int, mixed>

An array of message ids to delete.

Return values
mixed

fetch()

Obtain the FULL message from the backend, regardless of any truncation options.

public fetch(string $folderid, string $id, array<string|int, mixed> $collection) : Horde_ActiveSync_Message_Base
Parameters
$folderid : string

Folder id containing data to fetch.

$id : string

Server id of data to fetch.

$collection : array<string|int, mixed>

The collection data.

Return values
Horde_ActiveSync_Message_Base

The message data

getAttachment()

Return the specified attachment.

public abstract getAttachment(string $name[, array<string|int, mixed> $options = array() ]) : array<string|int, mixed>
Parameters
$name : string

The attachment identifier. For this driver, this consists of 'mailbox:uid:mimepart'

$options : array<string|int, mixed> = array()

Any options requested. Currently supported:

  • stream: (boolean) Return a stream resource for the mime contents.
Return values
array<string|int, mixed>

The attachment in the form of an array with the following structure: array('content-type' => {the content-type of the attachement}, 'data' => {the raw attachment data})

getCurrentPolicy()

Return the security policies.

public abstract getCurrentPolicy() : array<string|int, mixed>
Return values
array<string|int, mixed>

An array of provisionable properties and values.

getFolderList()

Get the list of folder stat arrays @see self::statFolder()

public abstract getFolderList() : array<string|int, mixed>
Return values
array<string|int, mixed>

An array of folder stat arrays.

getFolders()

Return an array of folder objects.

public abstract getFolders() : array<string|int, mixed>
Return values
array<string|int, mixed>

An array of Horde_ActiveSync_Message_Folder objects.

getFreebusy()

Request freebusy information from the server

public abstract getFreebusy(string $user[, array<string|int, mixed> $options = array() ]) : mixed
Parameters
$user : string

The user to request FB information for.

$options : array<string|int, mixed> = array()

Options.

Tags
deprecated

Will be removed in 3.0 - this is provided by resolveRecipients

Return values
mixed

boolean|array The FB information, if available. Otherwise false.

getHeartbeatConfig()

Obtain the ping heartbeat settings

public getHeartbeatConfig() : array<string|int, mixed>
Return values
array<string|int, mixed>

getMessage()

Obtain an ActiveSync message from the backend.

public abstract getMessage(string $folderid, string $id, array<string|int, mixed> $collection) : Horde_ActiveSync_Message_Base
Parameters
$folderid : string

The server's folder id this message is from

$id : string

The server's message id

$collection : array<string|int, mixed>

The colletion data. May contain things like:

  • mimesupport: (integer) Indicates if the device has MIME support. DEFAULT: 0 (No MIME support)
  • truncation: (integer) Non-MIME truncation limit. Anything larger than this amount of bytes will be truncated. DEFAULT: 0 (No truncation)
  • mimetruncation: (integer) MIME truncation limit. Anything larger than this amount of bytes will be truncated. DEFAULT: 0 (No truncation)
  • bodyprefs: (array) The bodypref array from the device.
Tags
throws

Horde_ActiveSync_Exception, Horde_Exception_NotFound

Return values
Horde_ActiveSync_Message_Base

The message data

getProvisioning()

Returns the provisioning support for the current request.

public abstract getProvisioning() : mixed
Return values
mixed

The value of the provisiong support flag.

getSearchResults()

Returns array of items which contain contact information

public abstract getSearchResults(string $type, array<string|int, mixed> $query) : array<string|int, mixed>
Parameters
$type : string

The search type; ['gal'|'mailbox']

$query : array<string|int, mixed>

The search query. An array containing:

  • query: (string) The search term. DEFAULT: none, REQUIRED
  • range: (string) A range limiter. DEFAULT: none (No range used).
Return values
array<string|int, mixed>

An array containing:

  • rows: An array of search results
  • status: The search store status code.

getServerChanges()

Get a list of server changes that occured during the specified time period.

public abstract getServerChanges(Horde_ActiveSync_Folder_Base $folder, int $from_ts, int $to_ts, int $cutoffdate, bool $ping) : array<string|int, mixed>
Parameters
$folder : Horde_ActiveSync_Folder_Base

The ActiveSync folder object to request changes for.

$from_ts : int

The starting timestamp.

$to_ts : int

The ending timestamp.

$cutoffdate : int

The earliest date to retrieve back to.

$ping : bool

If true, returned changeset may not contain the full changeset, may only contain a single change, designed only to indicate some change has taken place. The value should not be used to determine what change has taken place.

Tags
throws
Horde_Exception_AuthenticationFailure

Thrown when the requested collection appears to be no longer available. For H6, we should have the application APIs be responsible for differentiating between deleted/not-visible.

todo

Horde 6

  • Change return structure to (optionally) include the actual $to_ts value that was used. This is needed because if using something like Kolab/IMAP storage backend in Horde, then we must synchronize Horde <-> Kolab to get any changes from external Kolab clients and this may cause new/changed entries that would change the current MODSEQ. Not critical, since without this it only results in having to wait until the next SYNC cycle. By returning the actual $to_ts value we can update the state with THIS value instead of the one we were originally sent.
Return values
array<string|int, mixed>

A list of messge uids that have chnaged in the specified time period.

getSettings()

Return settings from the backend for a SETTINGS request.

public abstract getSettings(array<string|int, mixed> $settings, Horde_ActiveSync_Device $device) : array<string|int, mixed>
Parameters
$settings : array<string|int, mixed>

An array of settings to return.

$device : Horde_ActiveSync_Device

The device to obtain settings for.

Return values
array<string|int, mixed>

The requested settings.

getSpecialFolderNameByType()

Return the server id of the specified special folder type.

public abstract getSpecialFolderNameByType(string $type) : string
Parameters
$type : string

The self::SPECIAL_* constant.

Return values
string

The folder's server id.

getSyncStamp()

Return the SyncStamp - the value used to determine the end of the current sync range. Default implementation uses timestamps. Concrete drivers can override this to provide another method to do this, such as using modification sequences.

public getSyncStamp( $collection) : int
Parameters
$collection :

string The collection id we are currently requesting.

Return values
int

The SyncStamp

getUser()

Get the username for this request.

public getUser() : string
Return values
string

The current username

getUsernameFromEmail()

Attempt to guess a username based on the email address passed from EAS Autodiscover requests.

public abstract getUsernameFromEmail(string $email) : string
Parameters
$email : string

The email address

Return values
string

The username to use to authenticate to Horde with.

getWasteBasket()

Get the wastebasket folder.

public abstract getWasteBasket(string $class) : string|bool
Parameters
$class : string

The collection class.

Return values
string|bool

Returns name of the trash folder, or false if not using a trash folder.

itemOperationsFetchMailbox()

Returnmail object represented by the specified longid. Used to fetch email objects from a search result, which only returns a 'longid'.

public abstract itemOperationsFetchMailbox(string $longid, array<string|int, mixed> $bodyprefs, bool $mimesupport) : Horde_ActiveSync_Message_Base
Parameters
$longid : string

The unique search result identifier.

$bodyprefs : array<string|int, mixed>

The bodypreference array.

$mimesupport : bool

Mimesupport flag.

Return values
Horde_ActiveSync_Message_Base

The message requested.

itemOperationsGetAttachmentData()

Return the specified attachement data for an ITEMOPERATIONS request.

public abstract itemOperationsGetAttachmentData(string $filereference) : mixed
Parameters
$filereference : string

The attachment identifier.

Return values
mixed

Return a documentlibrary item.

public abstract itemOperationsGetDocumentLibraryLink(string $linkid, array<string|int, mixed> $cred) : array<string|int, mixed>
Parameters
$linkid : string

The linkid

$cred : array<string|int, mixed>

A credential array:

  • username: A hash with 'username' and 'domain' key/values.
  • password: User password
Return values
array<string|int, mixed>

An array containing the data and metadata:

meetingResponse()

Hanlde meeting responses.

public abstract meetingResponse(array<string|int, mixed> $response) : string
Parameters
$response : array<string|int, mixed>

The response data. Contains:

  • requestid: The identifier of the meeting request. Used by the server to fetch the original meeting request details.
  • response: The user's response to the request. One of the response code constants.
  • folderid: The collection id that contains the meeting request.
Tags
throws

Horde_ActiveSync_Exception, Horde_Exception_NotFound

Return values
string

The UID of any created calendar entries, otherwise false.

moveMessage()

Move message

public abstract moveMessage(string $folderid, array<string|int, mixed> $ids, string $newfolderid) : array<string|int, mixed>
Parameters
$folderid : string

Existing folder id

$ids : array<string|int, mixed>

Message UIDs

$newfolderid : string

The new folder id

Return values
array<string|int, mixed>

The new uids for the message.

resolveRecipient()

Handle ResolveRecipient requests

public abstract resolveRecipient(string $type, string $search[, array<string|int, mixed> $options = array() ]) : array<string|int, mixed>
Parameters
$type : string

The type of recipient request. e.g., 'certificate'

$search : string

The email to resolve.

$options : array<string|int, mixed> = array()
Return values
array<string|int, mixed>

An array of results containing any of the following:

  • type: (string) The type of result a GAL entry or personal address book entry. A Horde_ActiveSync::RESOLVE_RESULT constant.
  • displayname: (string) The display name of the contact.
  • emailaddress: (string) The emailaddress.
  • entries: (array) An array of certificates.
  • availability: (string) A EAS style FB string.
  • picture: (Horde_ActiveSync_Message_ResolveRecipientsPicture)

sendMail()

Sends the email represented by the rfc822 string received by the client.

public abstract sendMail(mixed $rfc822[, int $forward = null ][, int $reply = null ][, string $parent = null ][, bool $save = true ]) : bool
Parameters
$rfc822 : mixed

The rfc822 mime message, a string or stream resource.

$forward : int = null

The UID of the message, if forwarding.

$reply : int = null

The UID of the message if replying.

$parent : string = null

The collection id of parent message if forwarding/replying.

$save : bool = true

Save in sent messages.

Return values
bool

setLogger()

Setter for the logger instance

public setLogger(Horde_Log_Logger $logger) : mixed
Parameters
$logger : Horde_Log_Logger

The logger

Return values
mixed

setProtocolVersion()

Set the protocol version. Can't do it in constructer since we don't know the version at the time this driver is instantiated.

public setProtocolVersion(float $version) : mixed
Parameters
$version : float

The EAS protocol version to use.

Return values
mixed

setReadFlag()

Set the read (\seen) flag on the specified message.

public abstract setReadFlag(string $folderid, int $uid, int $flag) : mixed
Parameters
$folderid : string

The folder id containing the message.

$uid : int

The message IMAP UID.

$flag : int

The value to set the flag to.

Tags
deprecated

Will be removed in 3.0, use changeMessage() instead.

Return values
mixed

setSettings()

Set backend settings from a SETTINGS request.

public abstract setSettings(array<string|int, mixed> $settings, Horde_ActiveSync_Device $device) : array<string|int, mixed>
Parameters
$settings : array<string|int, mixed>

The settings to store.

$device : Horde_ActiveSync_Device

The device to store settings for.

Return values
array<string|int, mixed>

An array of status responses for each set request. e.g.,: array('oof' => Horde_ActiveSync_Request_Settings::STATUS_SUCCESS, 'deviceinformation' => Horde_ActiveSync_Request_Settings::STATUS_SUCCESS);

setup()

Setup sync parameters. The user provided here is the user the backend will sync with. This allows you to authenticate as one user, and sync as another, if the backend supports this.

public setup(string $user) : bool
Parameters
$user : string

The username to sync as on the backend.

Return values
bool

statFolder()

Stat folder. Note that since the only thing that can ever change for a folder is the name, we use that as the 'mod' value.

public abstract statFolder(string $id, mixed $parent[, mixed $mod = null ]) : a
Parameters
$id : string

The folder id

$parent : mixed

The parent folder (or 0 if none).

$mod : mixed = null

Modification indicator. For folders, this is the name of the folder, since that's the only thing that can change.

Return values
a

stat hash

statMailMessage()

Build a stat structure for an email message.

public abstract statMailMessage(string $folderid, int|array<string|int, mixed> $id) : array<string|int, mixed>
Parameters
$folderid : string

The mailbox name.

$id : int|array<string|int, mixed>

The message(s) to stat (IMAP UIDs).

Return values
array<string|int, mixed>

statMessage()

Get a message stat.

public abstract statMessage(string $folderId, string $id) : hash
Parameters
$folderId : string

The folder id

$id : string

The message id (??)

Return values
hash

with 'id', 'mod', and 'flags' members

_getClassFromType()

Convert a TYPE constant into it's associated CLASS constant.

protected _getClassFromType(int $type) : string
Parameters
$type : int

The TYPE.

Return values
string

The CLASS

_getFolderUidForBackendId()

Get an activesync uid for the given backend serverid. If we've seen this serverid before, return the previously created uid, otherwise return a new one.

protected _getFolderUidForBackendId(string $id[, string $type = null ][, string $old_id = null ]) : string
Parameters
$id : string

The server's current folder name E.g., INBOX

$type : string = null

The folder type, a Horde_ActiveSync::FOLDER_TYPE_* constant. If empty, assumes FOLDER_TYPE_USER_MAIL

$old_id : string = null

The previous folder name for this folder, if the folder is being renamed. @since 2.15.0 @todo This is tempoarary until 3.0 (H6) when we will have the collection manager take care of ALL of the folder name <-> UID mapping management.

Tags
since
2.4.0
Return values
string

A unique identifier for the specified backend folder id. The first character indicates the foldertype as such: 'F' - Email 'C' - Contact 'A' - Appointment 'T' - Task 'N' - Note

_isSpecialMailbox()

Return if the specified folder is a special folder.

protected _isSpecialMailbox(string $server_id) : true
Parameters
$server_id : string

The server id of the folder.

Return values
true

if $server_id is a special folder, otherwise false.

Search results