egwical_resourcehandler Class Reference

Inheritance diagram for egwical_resourcehandler:

bocalupdate_vevents bocalupdate_vfreebusy boinfolog_vtodos Collaboration diagram for egwical_resourcehandler:

Collaboration graph
[legend]
List of all members.

Detailed Description

Abstract Base class with routines to transport and convert iCalendar components to and from Egroupware resources (calendar, infolog, ).

An egwical object is used in an application to transport Ical information to Egw data elements and vice versa.

Synopsis

See the overview in mainpage

Egw Elements (EElts) vs. iCalendar Elements (VElts)

The Ical information can consist of components like VEVENTS VTODOS, VFREEBUSYs etc. We will denote these Vcalendar Elements with the general term VElt.
In the current implementation we use Horde_iCalendar objects for these VElts. In this Horde_iCalendar class a complete icalendar is represented by a VCALENDAR element object (in Horde terminology a Horde_iCalendar object) and non compound elements of such a VCalendar object like VTODO's or or VEVENTS are represented by subclasses of this (in Horde terminology Horde_iCalendar_XYZ objects). In the EgwIcal package we will denote these Non Compound vcalendar elements by the term: NCVElt The Egw data elements (events, task etc.) that reside in different Egw resources (calendar, infolog,...) are denoted with the general term EElts. In the current implementation the Egw resources dont use objects (yet?) to represent EElts (tasks, events,..) but rather manipulate them either as an array of data fields or by an integer that represents the id of the EEltData in the database.
Note:
for this reason many of the export methods in this class can handle polymorphic parameters for EElt. That is the EElt can be passed either as an array (of type EEltData) or as an identifier (of type EEltId).

Abstract Base class and Concrete subclasses

The Egw data elements (events, task etc.) we thus call EElts, reside in different Egw resources (calendar, infolog,...) that handle them. The code for specifically handling such a resources is within Egw contained in specific Egw classes (like bocalupdate, boinfolog,...).

The base class egwical_resourcehandler is a base class that implements generic code to handle these Egw resources. For example parsing or rendering from/to an iCalendar string, or handling sets of EElts and VElts For actual work with the NonCompound Vcalendar Elements (NCElts) it has no code by itself but relies on code within a socalled concrete subclass that is dedicated towards handling a specific Egw resource. These subclass must implement the virtual methods of the base class.

In the current implementation (>= v0.9.30) that uses the pattern of ical accessors as egwical_resourcehandler subclasses the class acts as a Abstract Base Class in the sense that it should not be instantiated directly but rather be used by instantiating one of its concrete subclasses.

Currently there are three such concrete resource handling subclasses available:

UID to ID Mapping and Matching.

A short explanation about the uid_mapping used in the conversion between icalendar elements (aka VElts) on the one hand and Egw Resource Elements (aka EElts) on the other hand. Uid_mapping is the mechanismn to relate the EElts (identified either by their id or uid fields) to VElts (identified by their UID field). In EgwIcal this Uid-Mapping-Mode can be controlled by three variables. Here a short intro into their working. As example of a EElt and VElt an event resp. a VEVENT are taken, but for tasks and VTODO's and other EElt-VElt pairs the situation is the same of course.

If $uid_mapping_export is UMM_ID2UID, then:

If $uid_mapping_export is UMM_UID2UID, then:

if $uid_mapping_import is UMM_UID2ID then:

If $uid_mapping_import is UMM_UID2UID then:

Note:
Mostly it is best to disable the UID2UID uid mapping mode always. It prevents that multiple duplicates of a event will be created in Egw, that may not be accessible anymore via for example the Ical-Service interface. Only use it when you really need to reimport into Egw an already once before imported calendar because you accidentally deleted parts of it in Egw. And even in this case a better solution would be to copy these lost events in the client into a downloaded version from Egw of your original calendar and then publish this changed clien calendar to Egw for once, with the uid_mapping_import set still to UID2ID. (This is because UID2UID has namely no effect for new (i.e. not yet know by egw) events on the one hand and on the hand, the old (i.e. already once downloaded to the client) events will be recognized already with the $uid_mapping_import = UMM_UID2ID setting.

The DeviceType system

The Egwical package allows it to tune the conversion between EElts and VElts to the capabilities of the device that is tranferring iCalendar data to and from Egw. This steering of the conversion is done via the deviceType member that determines wich VElt fields are supported for for import and export.
Todo:
write some doc about the devicType steering and supportedFields

Auxiliary Conversion Functions

Developers of Concrete resource handler subclasses, can profitably use the set of auxiliary conversion routines that the library class eicnvutils provides. These methods must be accessed via the $ecu member variable.

Version:
0.9.37-ng-a1 added deviceType2contentType method.
Date:
20060427
Since:
0.9.36 first version with NAPI-3.1 (rsc-owner_id handling)

0.9.30 new api: ical accessors as egwical_resourcehandler subclasses

0.9.22 new api2 using eicnvutils via $ecu

Author:
Jan van Lieshout <jvl (at) xs4all.nl> (This version)

Lars Kneschke <lkneschke@egroupware.org> (original code of reused parts)

Ralf Becker <RalfBecker-AT-outdoor-training.de> (original code of reused parts)

see http://opensource.org/licenses/gpl-license.php GPL - GNU General Public License

Todo:
check signatures of various EElt export methods to see if we should allow both array_of_EElt and array_of_EEltId arguments. The first might be profitable to handle large queries (only one DB search needed)


Class Methods

Methods that can be called without an instance of class egwical_resourcehandler

string deviceType2contentType ($devtyp='all')
 Derive the contentType for export to a devictype.
ProductType I False httpUserAgent2deviceType ($agentidstr)
 Derive the deviceType from a http request agent field.
ProductType I False icalendarProdId2devicetype (string $prodidstr)
 Derive the deviceType for an iCalendar.
VElt I false & parse_vcal2velt (VcalStr &$vcal)
 Parse Vcalstring into a Vcal Element.
ProductType I False product2deviceType ($productManufacturer='all', $productName='')
 Derive the deviceType from a product manufacturer and name description.
VcalStr I false render_velt2vcal (VElt $vobj, array $attribs=null)
 Render a Vcal Element as a VcalString.
array _provided_ical2egwComponents ()
 Deliver the implemented ical to egw components mapping.
array _provided_vcalendar2egwAttributes ()
 Deliver the implemented vcalendar attributes to egw standard values mapping.

Public Member Functions

 egwical_resourcehandler (egwobj $egwrsc=null, $devicetype='all', $rscownerid=null)
 Constructor that inits the handler object.
VcalStr export_vcal (array_of_EEltId-I-array_of_EEltData &$eids, array $attribs=null)
 Export egw elements from bound egw resource as an iCalendar string.
array_of_VElt export_velts (array_of_EEltId-I-array_of_EEltData &$eids)
 Export Egw elements from bound resource as Vcalendar Elements.
array_of_EEltId I false import_vcal (VcalStr &$vcal)
 Import all suited elements from an iCalendar string into the bound Egw resource.
array_of_EEltId I false import_velts (array_of_VElt &$vobjs)
 Import a set of Vcalendar Elements into the bound Egw resource.
Virtual Methods
These methods must be overridden in concrete subclasses

virtual NCVElt export_ncvelt (EEltId-I-EEltData &$eid)
 Export Egw element from bound resource as NonCompound Vcal Element.
virtual false import_ncvelt (VElt $ncvelt, EEltId $eid=-1)
 Import a Non Compound Vcalendar Element into the bound resource.
virtual boolean set_rsc (obj $egw_rsc)
 Set the egw resource and ical element types to handle.
 set_rsc_owner_id (int $account_id='0')
 Define owner (by account_id) for new to import egw elements.

Public Attributes

boolean $reimport_missing_elements = true
 Switch to allow reimport of gone egw elements.
int $uid_mapping_export = UMM_ID2UID
 Switch that determines the way uid fields are generated at export.
int $uid_mapping_import = UMM_UID2ID
 Switch that determines how uid fields are used for import.

Private Member Functions

 _errorlog_evupd (string $vtype, string $fault='ERROR', ind $user_id, array &$new_egwelt, $cur_egwelt)
 Log Egw and Velt update problems to errorlog.

Private Attributes

ProductType $deviceType = 'all'
 the generic type of device now using the egwical_resourcehandler
eicnvutils $ecu
 The library object with the conversion utilities.
int $eidebug = 1
 extra debugging switch
Horde_iCalendar $hi
 Horde calendar used for various conversions.
array $ical2egwComponents = array()
 mapping from iCalendar components to egw elements
egwrscobj $rsc = null
 The Bound Egw Resource that we handle.
int $rsc_owner_id = 0
 Owner of the (virtual) resource is used to add or delete Egw Elements

This variable can be set via the constructor.

array $rsc_vtypes = array()
 This list gives all the vcalendar type supported by the (currently) bounded resource.
array $supportedFields
 supported fields of the importing/exporting device
array $vcalendar2egwAttributes
 Standard attributes values used in rendering a iCalendar string.


Constructor & Destructor Documentation

egwical_resourcehandler::egwical_resourcehandler egwobj $  egwrsc = null,
devicetype = 'all',
rscownerid = null
 

Constructor that inits the handler object.

The auxiliary object $hi, $ecu , $ical2egwComponents and $vcalendar2egwAttributes are all initialized. Optionally an egwresource (like calendar- or infolog object) can already be passed and a devicetype.

Parameters:
$egwrsc Egroupware data resource object that will be used to transport (i.e. import and export) the vcalendar elements to and from. This can also later be set using the set_rsc() method.
$prodid The type identification of the device is used to transport ical data to and from. This can later be set using the set_supportedfields() method.
$rscowernid the id of the resource owner. This is only needed for import in resources not owned by the authenticated user. Default (0) the id of the authenticated user is used.


Member Function Documentation

egwical_resourcehandler::_errorlog_evupd string $  vtype,
string $  fault = 'ERROR',
ind $  user_id,
array &$  new_egwelt,
cur_egwelt
[private]
 

Log Egw and Velt update problems to errorlog.

Parameters:
$vtype type of egw elements that is updated (event ,task,..)
$fault description of the fault type
$user_id the id of the logged in user
$new_egwelt the info converted from the vegwelt to be imported
$cur_egwelt_ids settings of owner, id and uid field of a possibly found corresponding egw egwelt. When no such egwelt found: false.

array egwical_resourcehandler::_provided_ical2egwComponents  )  [private]
 

Deliver the implemented ical to egw components mapping.

--Class Method--

Produce the array of icalcomponent (types) to egw element mappings that this are implemented. This info is used to initialize the variable $ical2egwComponents

Returns:
The initial mapping provided in this implementation.

array egwical_resourcehandler::_provided_vcalendar2egwAttributes  )  [private]
 

Deliver the implemented vcalendar attributes to egw standard values mapping.

--Class Method--

Produce an array that holds the mapping of some VCALENDAR element attributes to Egw fields. These data are also used to initialize the variable $vcalendar2egwAttributes.

Note:
this is mainly used at export time to set the PRODID, VERSIONand METHOD attributes
Returns:
The initial vcalendar attributes mapping provided in this implementation.

string egwical_resourcehandler::deviceType2contentType devtyp = 'all'  ) 
 

Derive the contentType for export to a devictype.

--Class method--

Todo:
implement deviceType2contentType
Parameters:
$devtype the productype of the device that will receive or produce the icaldata content.
Returns:
the required http contenttype setting(as per HTTP / mimetype definition) that the devicetype likes to see for the produced icaldata. On failure: False

virtual NCVElt egwical_resourcehandler::export_ncvelt EEltId-I-EEltData &$  eid  )  [virtual]
 

Export Egw element from bound resource as NonCompound Vcal Element.

Parameters:
$eid a egw element for the bound resource that is to be exported
Returns:
the exported egw element converted to a Non Compound Vcalendar object

VcalStr egwical_resourcehandler::export_vcal array_of_EEltId-I-array_of_EEltData &$  eids,
array $  attribs = null
 

Export egw elements from bound egw resource as an iCalendar string.

All the egw elements in the bound egw resource, refered to by the ids in $eids are exported as Vcalendar elements and then rendered into a iCalendar formatted string. Specific global attributes settings for this string are taken from .....

Parameters:
$eids a list of egw elements (ids) for the bound egw resource that are to be exported.
$attribs optional hash with global iCalendar attributes settings. These attributes will be added and possibly override the standard attributes as found in $this->vcalendar2egwAttributes
Returns:
a iCalendar formatted string corresponding to the VElt data converted from egw elemenent refered to by $eids On error: false

array_of_VElt egwical_resourcehandler::export_velts array_of_EEltId-I-array_of_EEltData &$  eids  ) 
 

Export Egw elements from bound resource as Vcalendar Elements.

Parameters:
$eids a list of egw elements (ids) that are to be used for export.
Returns:
a list of Vcal objects that were exported On error: false (currently error handling not implemented!)

ProductType I False egwical_resourcehandler::httpUserAgent2deviceType agentidstr  ) 
 

Derive the deviceType from a http request agent field.

--Class method--

Todo:
implement httpUserAgent2deviceType()
Parameters:
$agentid stringvalue http user agent id field of a http request
Returns:
the productype derived from the PRODID label On failure: False

ProductType I False egwical_resourcehandler::icalendarProdId2devicetype string $  prodidstr  ) 
 

Derive the deviceType for an iCalendar.

--Class method--

Todo:
implement icalendarProdId2devicetype()
Parameters:
$prodidstr stringvalue of a iCalendar PRODID field
Returns:
the productype derived from the PRODID label On failure: False

virtual false egwical_resourcehandler::import_ncvelt VElt $  ncvelt,
EEltId $  eid = -1
[virtual]
 

Import a Non Compound Vcalendar Element into the bound resource.

Parameters:
$ncvelt a Non Compound vcalendar element that is to be imported in the bound resource. This should not be a full compound VCALENDAR obj!
$eid a fixed id indicating a specific egw element in the bound resource that should be updated with by the (converted) $velt data. When left out, insertion or updating is done on some form of uid-to-id mapping.
Returns:
as it is a non allowed abstract dummy

array_of_EEltId I false egwical_resourcehandler::import_vcal VcalStr &$  vcal  ) 
 

Import all suited elements from an iCalendar string into the bound Egw resource.

This import routine parses the Vcal string and then tries to import into the egw resource bound in $this->rsc all vcalendar elements of the supported type (VEVENTS or VTODOS, ..) for this resource. This supported type is found in $this->??

Parameters:
$vcal a iCalendar formatted string with either a single VElt or a VCALENDAR that contains multiple VElts.
Returns:
a list of id s of the resulting egw elements imported or updated in the bound egw resource. On error: false

array_of_EEltId I false egwical_resourcehandler::import_velts array_of_VElt &$  vobjs  ) 
 

Import a set of Vcalendar Elements into the bound Egw resource.

All vcalendar elements that are of an appropiate type, supported by the bound resource in $this->rsc are converted to egw elements and then imported into the resource. Non appropiate vcalendar element types are simply ignored. Full VCALENDAR objects are decomposed and each (appropiate) part is imported.

Parameters:
$vobjs a list of Vcal ELement objects that are converted and imported into Egw.
Returns:
a list of id s of the resulting egw elements imported or updated in the bound egw resource. On error: false

VElt I false& egwical_resourcehandler::parse_vcal2velt VcalStr &$  vcal  ) 
 

Parse Vcalstring into a Vcal Element.

--Class Method--

The Vcalstring should form a single Vcal element, thus it should be of the form BEGIN:veltype ...... END:veltype with veltype the name of a valid Vcal Element such as VCALENDAR, VEVENT etc. When a single component is contained in a VCALENDAR, this container is automatically unpacked!

Parameters:
$vcal a iCalendar formatted string with a more Vcalendar Element
Returns:
the created Vcal Element When a VCalendar with many sub Vcal Elements (like VEVENT's and VTODO's) is parsed, only the outermost (a Vcalendar object) is returned. The sub VElts should somehow be accessible through membership of this object for routines that need them. On error: false

ProductType I False egwical_resourcehandler::product2deviceType productManufacturer = 'all',
productName = ''
 

Derive the deviceType from a product manufacturer and name description.

--Class method--

Todo:
implement product2devicetype
Parameters:
$_productManufacturer a string indicating the device manufacturer
$_productName a further specification of the current device that is used for import or export.
Returns:
the productype derived from the input strings On failure: False

VcalStr I false egwical_resourcehandler::render_velt2vcal VElt $  vobj,
array $  attribs = null
 

Render a Vcal Element as a VcalString.

--Class Method--

Note:
if the $vobj is a iCalendar sub element, a Vcalendar container is put around it.
Parameters:
$vobj a Vcal object that is rendered (serialized) as Vcal formatted string.
$attribs optional hash with global iCalendar attributes settings. These attributes will be added and possibly override the standard attributes as given by the _provided_vcalendar2egwAttributes() routine.
Note:
if the $vobj argument is a iCalendar these attributes stay added as a side-effect!
Returns:
the rendered Vcal formatted string. On error: false

virtual boolean egwical_resourcehandler::set_rsc obj $  egw_rsc  )  [virtual]
 

Set the egw resource and ical element types to handle.

The egw resource and ical element types that are used to handle are registered in the variable $rsc and $rsc_vtypes.

Note:
this method needs to be implemented in a concrete subclass of egwical_resourcehandler as these only these classes can check if the $egw_rsc passed is of the correct (supported) type for the handler. And they are also the only ones thatknow what the vtypes associated with the resource are!
Parameters:
$egw_rsc the resource that will be used to transport the ical data to and from.
Returns:
false always as this abstract version should never be called from this base class directly.

egwical_resourcehandler::set_rsc_owner_id int $  account_id = '0'  ) 
 

Define owner (by account_id) for new to import egw elements.

Just fill the member variable $this->rsc_owner_id by the appropiae value

Parameters:
$account_id the id of the egw account that will be used to set ownership for new to create egw elements in the egw resource.


Member Data Documentation

ProductType egwical_resourcehandler::$deviceType = 'all' [private]
 

the generic type of device now using the egwical_resourcehandler

Label that identifies the device capabilities for import and export of the currently connected client device.

This ProductType will be used to control the import and export by using it as argument for setSupportedFields(). This label is a string with a slash separating generic and the more specific description. Examples are:

		   all                         // the default
		   siemens/sx11
		   nexthaus corporation/
		   sonyericsson/
		   multisync/
		   ...
		   remotecalendars/
		
See icalendarProdId2devicetype() and httpAgent2deviceType() to derive the ProductType from a iCalendar resp. a http request.

eicnvutils egwical_resourcehandler::$ecu [private]
 

The library object with the conversion utilities.

This object can be reused in other egwical objects, it is used readonly. Therefore you can pass an instantion of it via the class constructor, if you have one. Else the constructor will create a new version.

int egwical_resourcehandler::$eidebug = 1 [private]
 

extra debugging switch

Switch to print extra debugging about imported and exported events to the httpd errorlog stream. (0 is off 1 is on 2 is more on ...

Horde_iCalendar egwical_resourcehandler::$hi [private]
 

Horde calendar used for various conversions.

Placeholder object used to access various Horde_iCalendar methods In here the constructor will create a Horde_iCalendar object that can be used by the various routines in the class

array egwical_resourcehandler::$ical2egwComponents = array() [private]
 

mapping from iCalendar components to egw elements

An (nested0 hash array containing the mapping from iCalendar components to egw elements. This is set by constructor. And for each component (like 'VEVENT', 'VTODO' etc) the entry will point to an array that gives a mapping of fields and subcomponents of that component type. These arrays are set either by

  • the constructors of the workerclass, if we are instantiating a workerclass egwical object. or:
  • the add_rsc() routine if we add a resource and associated workerobj to a base egwical class.
    Note:
    in the concrete subclasses the supportedFields system will copy keys from this table to indicate if some mapping is supported.

boolean egwical_resourcehandler::$reimport_missing_elements = true
 

Switch to allow reimport of gone egw elements.

Switch that determines if events not anymore in egw are allowed to be reimported

Default this is on

egwrscobj egwical_resourcehandler::$rsc = null [private]
 

The Bound Egw Resource that we handle.

Registry for the egw resource object (calendar, infolog,..) that will be used to transport ical elements from and to: The socalled Bound Resource This can be set by the constructor or later by set_rsc().

Reimplemented in bocalupdate_vevents, bocalupdate_vfreebusy, and boinfolog_vtodos.

int egwical_resourcehandler::$rsc_owner_id = 0 [private]
 

Owner of the (virtual) resource is used to add or delete Egw Elements

This variable can be set via the constructor.

When not used it has the default value 0, meaning that the resource owned by the authenticated user is taken.

array egwical_resourcehandler::$rsc_vtypes = array() [private]
 

This list gives all the vcalendar type supported by the (currently) bounded resource.

As only a concrete resource handler subclass has this knowledge, it should be set by such a subclass!

array egwical_resourcehandler::$supportedFields [private]
 

supported fields of the importing/exporting device

An array with the current supported fields of the importing/exporting device. To detect if a certain ical property (eg ORGANIZER) is supported in the current data import/export do a isset($this->supportedFields['ORGANIZER']). To detect if a certain egw field (eg status) is supported in the current data import/export do a in_array(array_flatten(array_values($this->supportedFields)),'status') or something like that (not tested, implemented, or needed yet..) Maybe should implement a method for this..

Note:
this variable is only set and used in real worker classes

int egwical_resourcehandler::$uid_mapping_export = UMM_ID2UID
 

Switch that determines the way uid fields are generated at export.

According to the value, on export, a uid will be generated:

  • completely unrelated to the related egw element id (UMM_NEWUID) or
  • with the related egw element id encoded (UMM_ID2UID Default situation!) or
  • directly copied from the uid field of the related egw element (UMM_UID2UID Strongly discouraged!). For more info see secuidmappping

int egwical_resourcehandler::$uid_mapping_import = UMM_UID2ID
 

Switch that determines how uid fields are used for import.

According to the value, on import, the uid field of a vcalendar element will be determine how the search for a matching egw element is done. The choices are:

  • no search for a related egw element id is done, Just a new element is added to the bound egw resource (UMM_NEWID) or
  • a related egw element is searched for based on a egw id decoded from the uid field of the ical element(UMM_ID2UID Note: Default situation!). This requires of course that at some earlier (exportd) moment an actual egw id was encoded in this uid field.
  • a related egw element is searched for based on the full value of the uid field of the ical element by searching trough the uid fields of the egw elements (UMM_UID2UID Note: Strongly discouraged!). This requires that the egw resource does support correct and unique manipulation (storage etc.) of the egw element uid fields! For more info see UID to ID Mapping and Matching.

array egwical_resourcehandler::$vcalendar2egwAttributes [private]
 

Standard attributes values used in rendering a iCalendar string.

Hash of some standard attributes of a VCALENDAR element. These used for rendering a Vcal formatted string. Mostly these are only the PRODID, VERSIONand METHOD attribute. These are set to default values in the constructor. You can change these before exporting some Vcal.You can set them back to their default values with the method _set_vcalendar2egwAttributes().


The documentation for this class was generated from the following file:
Generated on Thu Jun 8 21:57:23 2006 for EgwIcal by  doxygen 1.4.6