bocalupdate_vevents Class Reference

Inheritance diagram for bocalupdate_vevents:

egwical_resourcehandler Collaboration diagram for bocalupdate_vevents:

Collaboration graph
[legend]
List of all members.

Detailed Description

Concrete subclass resourcehandler for iCal vevents import and export with a egroupware bocalupdate calendar resource.

Synopsis

Some simple examples. Firs we need a couple of egw events and an instance of our (concrete) calendarresource handler class:
  $boc =& CreateObject('calendar.bocalupdate');

  $ev1 = $boc->read(1233);                    // get two events
  $ev2 = $boc->read(4011);

  $calhnd =& CreateObject('egwical.bocalupdate_vevents',$boc);
Now export an event as VEVENT and render it as iCalendar string
   // alternative 1
   $vevent1 = $calhnd->export_vevent($ev1,UMM_ID2UID);
   $vcalstr1 = egwical_resourcehandler::render_velt2vcal($vevent1);

   // alternative 2 (generic for all resourcehandlers)
   $calhnd->uid_mapping_export = UMM_ID2UID;
   $vevent1  = $calhnd->export_ncvelt($ev1);
   $vcalstr1 = egwical_resourcehandler::render_velt2vcal($vevent1);

   // alternative 3 (via baseclass, without intermediate vevent)
   $vcalstr1 = $calhnd->export_vcal($ev1);
An example for importing the vevents
    // alternative 1 (via the concrete method)
    $vevent1  = ..... a good vevent
    $ev_id1 = $calhnd->import_vevent($vevent1, UMM_UID2ID,1);
    if ($ev_id1 > 0)    {
      echo "imported vevent1 as event with id $ev_id1";
    }

    // alternative 2 (generic for all resourcehandlers)
    $calhnd->uid_mapping_import = UMM_UID2ID;
    $ev_id1  = $calhnd->import_ncvelt($vevent1);
    if ($ev_id1 > 0)    {
      echo "imported vevent1 as event with id $ev_id1";
    }

    // alternative 3 (via base class, easier for multiple vevents)
    $my_vevents = array($vevent1,$event2,..);
    $calhnd->uid_mapping_import = UMM_UID2ID;
    $eids = $calhnd->import_velts($my_vevents);
    echo "we imported" . count($eids) . "vevents";

And finally an example of importing all the vevents from a vcalstring
    // alternative 1
    $vcalstr = .. an vcalendar format string with multiple vevents

    $compvelt  = egwical_resourcehandler::parse_vcal2velt($vcalstr);
    if($compvelt === false) exit;

    $eids = $calhnd->import_velts($compvelt);
    if ($eids)
    {
       echo "we imported" . count($eids) . "vevents";
    }

    // alternative 2 (using the baseclass its methods)
   $eids = $calhnd->import_vcal($vcalstr);
   if ($eids)   echo "we imported" . count($eids) . "vevents";

Note:
Warning: When importing a vevent resulting from parsing a vcalstring or any other VElt for which you do not know if it is a single vevent or possibily a compound element with multiple vevents in it, you should preferable use the import_velts(0 routine of the baseclass instead of the import_ncvelt() or the import_vevent() routines. This is because the former can handle compound VElts, while the latter two cannot!
Inpackage: egwical

Todo:
add Lars his VERSION=1.0 handling of recur events in here.
Author:
Jan van Lieshout <jvl-AT-xs4all.nl> (This version. new api rewrite, refactoring, and extension).

Lars Kneschke <lkneschke@egroupware.org> (parts from boical that are reused here)

Ralf Becker <RalfBecker-AT-outdoor-training.de> (parts from boical that are reused here)

Version:
0.9.37-ng-a6 empty summary fields fix (semi)
Date:
20060508
Since:
0.9.37-ng-a2 removed double charset translation

0.9.36 update does not change owner anymore

0.9.36 first version with NAPI-3.1 (rsc_owner_id parameter)

0.9.30 first version for napi3 license http://opensource.org/licenses/gpl-license.php GPL - GNU General Public License


Public Member Functions

 bocalupdate_vevents (egwobj $egwrsc=null, ProductType $devicetype='all', string $rscownid='0')
 Our Constructor, if given it sets the egw resource $egwrsc is set as so called bound egw resource.
VEVENT export_ncvelt (EventId-I-EventData &$eid)
 Wrapper around export_vevent() with simplified parameters.
VEVENT I false export_vevent (EventId-I-EventData &$event, int $uid_mapping_export=ID2UID)
 Export calendar event from bound bocalupdate resource as VEVENT.
EventId I errorstring import_ncvelt (VEVENT &$ncvelt, int $eid=-1)
 Wrapper around import_vevent() with simplified set of call parameters.
EventId I Errorstring import_vevent (VEVENT &$vevent, int $uid_mapping_import, boolean $reimport_missing_events=false, int $cal_id=0)
 Import a VEVENT as a event into the bound Egw calendar resource.
boolean set_rsc (egwobj $egw_rsc)
 Set the egw calendar resource that this class will handle.
void setSupportedFields (ProductType $devicetype= 'all')
 Set the list of ical fields that are supported during the next imports and exports.

Private Member Functions

array _provided_vevent2eventFields ()
 Deliver the implemented vevent to event mapping as provided by this class.

Private Attributes

boolean $evdebug = true
 Switch to print extra debugging about imported and exported events to the httpd errorlog stream.
bocalupdate $rsc = null
 The Bound Egw Resource that we handle.
array $vevent2eventFields = array()
 mapping from iCalendar VEVENT fields to egw calendar fields


Constructor & Destructor Documentation

bocalupdate_vevents::bocalupdate_vevents egwobj $  egwrsc = null,
ProductType $  devicetype = 'all',
string $  rscownid = '0'
 

Our Constructor, if given it sets the egw resource $egwrsc is set as so called bound egw resource.

And $prodid, the product id of the client that will use or produce ical data is set to determine which fields to use in coming import and exportd conversions between vcalendar and egw data.

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.
$devicetype The type identification of the device that is used to the transport the ical data to and from. This is used to set the supportedFields already.
Note:
These can also later be set using the setSupportedFields() method.
Parameters:
$rscownid the id of the calendar owner. This is only needed for import in calendars not owned by the authenticated user. Default (0) the id of the authenticated user is used.


Member Function Documentation

array bocalupdate_vevents::_provided_vevent2eventFields  )  [private]
 

Deliver the implemented vevent to event mapping as provided by this class.

Produce the array of vevent to event field mappings that this class implements. These are stored on instantiation in the variable $vevent2eventFields

Returns:
The provided vevent to event fields mapping.

VEVENT bocalupdate_vevents::export_ncvelt EventId-I-EventData &$  eid  ) 
 

Wrapper around export_vevent() with simplified parameters.

Note:
the settings of $this->uid_mapping_export is respected as to chose the method of UID field generation for the VEVENT. See UID to ID Mapping and Matching. in the egwical_resourcehandler documentation.
Parameters:
$eid eventdata or event id in the bound bocalupdate resource that is to be exported.
Returns:
the exported egw event converted to a VEVENT object. on error False.

VEVENT I false bocalupdate_vevents::export_vevent EventId-I-EventData &$  event,
int $  uid_mapping_export = ID2UID
 

Export calendar event from bound bocalupdate resource as VEVENT.

The eGW event in $event is exported to iCalendar VEVENT (of type Horde_iCalendar_vevent) Note that only the set of supported Fields, as indicated by the $supportedFields member variable, are exported into the VEVENT.

The uid field of the generated VEVENT will be filled according to the setting of the $uid_mapping_export parameter. Either with the event id encoded (ID2UID) or with the event uid field copied (UID2UID) or with a completey new generated string (NEWUID). For more info see UID to ID Mapping and Matching.

Parameters:
$event array data (or id) of the eGW event that will be exported
$uid_mapping_export switch to set the export mode for the uid fields. Default UMM_ID2UID is used.
Returns:
the iCalendar VEVENT object representing the data from the egw input event. On error: false $supportedFields determines which fields in the VEVENT will be filled

EventId I errorstring bocalupdate_vevents::import_ncvelt VEVENT &$  ncvelt,
int $  eid = -1
 

Wrapper around import_vevent() with simplified set of call parameters.

Note:
this function only imports VEvent elements!
The value of the member variable $reimport_missing_elements is used to possibly allow to reimport of gone events in the calendar.

The value of the member variable $uid_mapping_import is used to control the set of iCalendar fields that are imported.

Parameters:
$ncvelt VEVENT object (horde_iCalendar_vevent)
$eid id for a selected event to be updated by the info from $velt If left out or set to -1 then uid_mapping_import is switched back to its standard setting as found in the member variable $uid_mapping_import.
Returns:
the id of the imported(or updated) ege calendar event. On error: a string indicating the error: ERROR | NOACC | DELOK | NOELT

EventId I Errorstring bocalupdate_vevents::import_vevent VEVENT &$  vevent,
int $  uid_mapping_import,
boolean $  reimport_missing_events = false,
int $  cal_id = 0
 

Import a VEVENT as a event into the bound Egw calendar resource.

The ical VEVENT component is converted to an eGW event for the calendar resource in $rsc and then imported into this eGW calendar resource.

Depending on the value of $uid_mapping_import, the conversion will either:

  • generate either an eGW event with a completely new id (UMM_NEWID) and fill that with the data. Or
  • search for an existing Egw event based on a id search, with an id search key decoded from the VEVENT uid field (UMM_UID2ID) to update with the data. Or
  • use the value in the VEVENT uid field a search key for a uid search amongst the Egw events (UMM_UID2UID) to use as event to update. Or finally
  • update a specific existing Egw event defined by the $cal_id parameter, with the data (UMM_FIXEDID).

Default the mode UMM_UID2ID is used. For more info see UID to ID Mapping and Matching.

$supportedFields determines the VEVENTS that will be used for import

For importing vevents the calendar of $this->rsc_owner_id is taken. That is the ownership of the new event is set to that owner. For editing(and deleting) of existing events the id of the current owner is always (re-) used.

Parameters:
$vevent VEVENT object (horde_iCalendar_vevent)
$uid_mapping_import uid mapping import mode used. see UID to ID Mapping and Matching. Default UMM_UID2ID.
$reimport_missing_events enable the import of previously exported events that are now gone in egw (probably deleted by someone else) Default false.
$cal_id the id of the egw event that is to be updated when UMM_FIXEDID mode is is set for $uid_mapping_import. If set as -1 the uid_mapping_import will switch to UMM_NEWID mode, if set as 0 the uid_mapping_import will switch to the default UMM_UID2ID mode.
Returns:
the id of the imported(or updated) egw calendar event. On error: a string indicating the error: ERROR | NOACC | DELOK | NOELT | BTYPE

boolean bocalupdate_vevents::set_rsc egwobj $  egw_rsc  ) 
 

Set the egw calendar resource that this class will handle.

This worker is only capable of handling bocalupdate calendar objects, so it should be of that class. The $egw_rsc is registered in the $rsc variable and the supported ical element is set to be 'vevent'. This is registered in $rsc_vtypes.

Parameters:
$egw_rsc the resource object of type bocalupdate that will be used to transport the ical data to and from.
Returns:
false on error, true if the $egw_rsc was indeed a correct resource of the supported type (bocalupdate).

void bocalupdate_vevents::setSupportedFields ProductType $  devicetype = 'all'  ) 
 

Set the list of ical fields that are supported during the next imports and exports.

The list of iCal fields that should be converted during the following imports and exports of VEVENTS is set. This is done according to a given ProductType as mostly set in the $deviceType field of the egwical_resourcehandler. See there for a further description.

In a small lookup table the set of currently supported fields is searched for and then and then these are set accordingly in the class member $supportedFields.

Note:
to find the ProductType for a device (like a iCalendar, browser, a syncml client etc.) the egwical_resoucehandler class provides some handy methods, like: icalendarProdId2devicetype(), httpUserAgent2deviceType() and product2devicetype()
Parameters:
$devicetype a string indicating the communicating client his type of device
Returns:


Member Data Documentation

boolean bocalupdate_vevents::$evdebug = true [private]
 

Switch to print extra debugging about imported and exported events to the httpd errorlog stream.

bocalupdate bocalupdate_vevents::$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 from egwical_resourcehandler.

array bocalupdate_vevents::$vevent2eventFields = array() [private]
 

mapping from iCalendar VEVENT fields to egw calendar fields

An array containing roughly the mapping from iCalendar to egw fields. Set by constructor. example entry (rn stands for "Resourced_Name"):

			'SUMMARY'	=> array('rn' => 'title'),
  	    
Here rn stands for "Resourced Name", to indicate the name of the related related field in the bound egw resource
Todo:
integrate this with the egwical base $ical2egw conversion table


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