extern/egroupware_official
1
0
Fork 0
mirror of https://github.com/EGroupware/egroupware.git synced 2024-11-22 07:53:39 +01:00
Code Issues Packages Projects Releases Wiki Activity

initial import of icalsrv documentation

Browse Source
This commit is contained in:
Lars Kneschke 2006-02-20 11:37:41 +00:00
parent fb5dc60f3a
commit 4d42f24d49
4 changed files with 424 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
phpgwapi/doc/icalsrv/IcalSrv-BUGS-and-TODOS.txt Normal file
View File

@ -0,0 +1,107 @@
/*! \page bugandtodopage BUGS and TODOS
<PRE>
Know BUGS and things todo
---------------------------
TODO means: should be done/would be nice in a newer release
BUG means: known problem needs to be fixed
FAIl means: known failure to provide (not easily to be done/fixed
(note: this list is probably not quite up todate)
release: VERSION 0.7.80 NEED TO UPDATE THIS!!
new in V0.7.78 versus v0.7.70:
bovevents:
+ whole day events import/export seems to work nice
+ continue on erroneous overwrites (errors only visible in errorlog)
+ no error messages for forbidden overwrite events of non owned events
+ errormessages (when activated) only shows problematic events
++ basic (multiple) VALARM import and export, working! (without action select)
+ allow for vevents with either DTEND or DURATION
+ provided (horde iCalendar) patch to prevent segfaults on some bad iCal inputs
1) general (V0.7)
----------------
1.1 TODO build egw install/setup system for icalsrv
1.2 TODO get it nicely into egw cvs
1.3 TODO build user preferences (export/import period setting) gui
[ ]1.7 TODO/WISH allow for import of ATTENDEEs not in Egw yet (create new addressbook entry?)
(ad hoc solution: add CN and mailto to description)
1.4 TODO check and generate source code documentation(phpdoc or doxygen)
1.5 TODO test these routines in use for syncml import/export
1.6 TODO/WISH: nothing done yet for vfreebusy, vjournal, notes, components
only vevents and vtodos are supported.
2) icalsrv.php (V0.7)
--------------------
[+]2.1 BUG/CHECK repair/improve the http error return (403) (seems to work)
2.2 TODO integrate with 1.3 TODO
[+]2.3 TODO handle (V)alarms
[ ]2.4 TODO(for v0.7.80 ?) for expor: get the agent name from the http header and use
to set the ical product field. Then in egwical use it to set the supportedfields()
3) egwical (V0.7.75)
--------------------
[+?]3.1 TODO check/implement correct timezone handling (seems ok)
3.2 TODO/WISH handle location (GEO), link(?), url, delegation, ()CONTACT?
3.3 TODO set and use the productid in the ical, and use it to
setsupportedFields() (for mozilla, korganizer etc. ... with a default of.. )
4) calendar.bovevents (V0.7.75)
------------------------------
[+?]4.1 TODO check/implement correct timezone handling (related 3.1)
[ ]4.2 FAIL rrule-COUNT import not implemented in egw?
[+]4.2 BUG!!!! rrule-BYDAY import goes wrong. FIXED (v0.7.76)
[+]4.3 TODO check and improve ORGANIZER,ATTENDEE<-> participants mapping
ATTENDEE s import and export (appears to work oke >= V0.7.71)
[+]4.4 TODO handle import and export of ALARMS
[ ]4.7 TODO (ad hoc) add non egw known attendees to description on import
4.9 see 3.2
5) infolog.bovtodos (V0.7.x)
----------------------------
5.1 TODO check/implement correct timezone handling (related 3.1)
5.3 FAIL import/export more than 1 category per task (egw doesnot allow)
5.3 TODO check and improve ORGANIZER,ATTENDEE<-> info_responsible etc mapping
5.4 TODO handle import and export of ALARMS
5.5 TODO rewrite code into supportedFields structure (for next version)
5.9 see 3.2
10.) in used routines from others:
10.1 BUG Horde_iCalendar(1.2rc6): EXDATE bug
-[+]fixed by patch 'exdate ....'
10.2 BUG Horde_iCalendar(1.2rc6): standard.php Warning
-[+]fixed by patch '...??..'
10.3 BUG infolog(1.2rc6): datetime is 1 hour wrong for untimed due field in tasks
11) detected errors/flaws in other programs
11.1 Korganizer 3.5: recurrence endondate display is interpreted different from egw and
mozilla (and probable also rfc 2445)
</PRE>
*/

168
phpgwapi/doc/icalsrv/IcalSrv-Manual-install-howto.txt Normal file
View File

@ -0,0 +1,168 @@
/*! @mainpage Ical Service for Egroupware
@NOTE: this text is not up to date
@version 0.9.01
@author jvl
@section secinstall SHORT experimental Install How-To:
- Install the icalsrv package by either checking out the icalsrv module from cvs
or untarring some tarball icalsrv-vx.y.x.tgz of the package (when available).
- @note: The IcalSrv package depends on the availability of an
EgwIcal (>= 0.9.x) package. So if you dont have this already, be sure
to install that too.
- Take care that icalsrv.php is .../egroupware/icalsrv.php (and the
other files from the icalsrv package also in their appropiate places)
- Append something like the following onto your apache httpd.conf part for
egroupware (assuming that your standard egroupware root path is e.g in
/var/www/egroupware and with a http alias 'egroupware' pointing to
it):
<PRE>
<Location /egroupware/icalsrv.php>
Script PUT /var/www/egroupware/icalsrv.php
AddHandler ical/ics .ics
Action ical/ics /var/www/egroupware/icalsrv.php
Order allow,deny
Allow from all
</Location>
</PRE>
- Restart apache (or other webserver) ( /etc/init.d/httpd restart )
- Connect your ical client (e.g: Sunbird)
with http://your.host.com/egroupware/icalsrv.php
- now you should need to authenticate (with your normal EGW login and password)
and when done you receive the calendar on doing a "reload remote calendars" or so.
- using the "publish" calendar action you can write the (modified) calendar
from the sunbird client back to EGW
@section secdeletions Deleting Calendars, events or todos
deletion of the whole remote calendar is not supported see the @ref
webcaldiscusspage webcal protocol discussion.
Individual calendar events or todos cannot be deleted either by just
deleting them on the client and then hoping that this propagates to
Egroupware on publish. There are various reasons for why this is not
implemented.
But, you can though delete items by simply renaming them to
<code>X-DELETE</code>. I you do so they will get deleted in Egw on
publishing. When you later dowload ("reload"/"refresh") the remote
calendar in your client you should notice that the event is gone..
@section secicalsrvclients Clients for IcalSrv
This is tested with egw1.2rc6 and clients:
* Korganizer (3.3.2,(read) 3.4.2, 3.5.0 (READ+WRITE))
* Mozilla calendar (2004040813-cal) (READ+WRITE)
* Evolution 2.2 (READ)
For further use and experience with these clients see @ref
pageicalsrvclients IcalSrvClients page.
@section secpatches Patches
You may need to apply some of the patches found in PATCHES.
Currently there a two patches to fix a warning and a bug (related to EXDATE
fields handling) in the horde routines.
Note these may be already committed in the CVS version.
@section sectest Extra testing
The package contains "compatibility" classes with which you can replace
the current infolog/inc/class.vcalinfolog.inc.php resp. calendar/inc/class.boical.inc.php
files.
When done so, the egw syncml, ical import/export and infolog import/export in egw
will all use the new code. This way you can discover more bugs and failure in the code :)
But, when not renamed, these programs will use the old code (and thus are not broken or
improved by the new one..)
@section secdocumentation Documentation
There is (somewhere) complete doxygen generated documentation for the
IcalSrv package. Otherwise you can generate it yourself by using
doxygen on the source filetree. Maybe you are just reading it now ...
@section sectestandebug Testing and Debugging
As IcalSrv is still a young and experimental new service for
Egroupware, that must mediate between a multitude of clients, each
with their own peculiarities and various internal applications of Egw,
it is very likely that a lot of problems, deficiencies and bugs will
appear.
Thus to get error feedback for it is a healthy thing. You should best
do this --as with any egw application-- using the sourcforge.net
buglist and the dedicated egroupware forums or mailinglist (see the
egroupware wiki for more instructions on this).
What to report? Well you should realize that IcalSrv is --currently--
on it self just a rather simple http interface script, that relies for
it connection to the egw backends heavily on the new (re) written
EgwIcal package. This means that problems with in and export of
iCalendar data will mostly have their source in that (i.e. EgwIcal)
package! So in case of errors allways report info on that package and
when debugging try the debug tools for that package.
@subsection subsecdebugtools Debugging of IcalSrv.
IcalSrv does not generate webpages, so to see any error or debug
information you there a jsut three other places to look at:
+ If you have a really problematic error, IcalSrv will answer your http
request with a 403 error and --hopefully-- a short message. In some
clients (like Korganize) this is reported back via a popup with a
silly message that "exporting went wrong or access denied" or so, instead of displaying
this message it got together with the 403 error. Note: Sunbird does
display the message. Unfortunately at the moment this will be mostly
"VEVENTS import ERROR" or so..
+ The httpd errorlog file/stream. Most problematic errors are reported
to this file of the egw server. So this is indeed the best source for
debug info. But to read it, you need access to the
server and to this log file. So only egw administrators are likely
the only ones for who this can be of help.
+ The ical.log files and ical.exportxxxx plus ical.importxxxx
files. If you did install the icalsrv.php file with the variable
$logdir set to folder where the httpd is allowed to write, you will
get a detailed log in file ical.log of all uploads and downloads via
IcalSrv furhtermore for each of these the associated iCalendar data
will be logged in ical.exportXXXXXX files with XXXX the utime of the
action. These files reside on the egw server, mostly in /tmp. So again
to read them you will need access to this server directory.
Off course this feature needs to be disabled in a production setting:
the file growth and the security issues of it demand it.
@section secbugandtodo BuG and todo list
-see BUGs and TODOs in @ref pageicalsrvbugandtodopage
have fun
JVL
*/

149
phpgwapi/doc/icalsrv/IcalSrv-Overview.txt Normal file
View File

@ -0,0 +1,149 @@
/*! @mainpage Ical Service for Egroupware
@NOTE: this text is not up to date
@version 0.9.01
@author jvl
@section secinstall SHORT experimental Install How-To:
- Install the icalsrv package by either checking out the icalsrv module from cvs
or untarring some tarball icalsrv-vx.y.x.tgz of the package (when available).
- @note: The IcalSrv package depends on the availability of an
EgwIcal (>= 0.9.x) package. So if you dont have this already, be sure
to install that too.
- Take care that icalsrv.php is .../egroupware/icalsrv.php (and the
other files from the icalsrv package also in their appropiate places)
- Append something like the following onto your apache httpd.conf part for
egroupware (assuming that your standard egroupware root path is e.g in
/var/www/egroupware and with a http alias 'egroupware' pointing to
it):
<PRE>
<Location /egroupware/icalsrv.php>
Script PUT /var/www/egroupware/icalsrv.php
AddHandler ical/ics .ics
Action ical/ics /var/www/egroupware/icalsrv.php
Order allow,deny
Allow from all
</Location>
</PRE>
- Restart apache (or other webserver) ( /etc/init.d/httpd restart )
- Connect your ical client (e.g: Sunbird)
with http://your.host.com/egroupware/icalsrv.php
- now you should need to authenticate (with your normal EGW login and password)
and when done you receive the calendar on doing a "reload remote calendars" or so.
- using the "publish" calendar action you can write the (modified) calendar
from the sunbird client back to EGW
@section secdeletions Deleting Calendars, events or todos
deletion of the whole remote calendar is not supported see the @ref
webcaldiscusspage webcal protocol discussion.
Individual calendar events or todos cannot be deleted either by just
deleting them on the client and then hoping that this propagates to
Egroupware on publish. There are various reasons for why this is not
implemented.
But, you can though delete items by simply renaming them to
<code>X-DELETE</code>. I you do so they will get deleted in Egw on
publishing. When you later dowload ("reload"/"refresh") the remote
calendar in your client you should notice that the event is gone..
@section secicalsrvclients Clients for IcalSrv
This is tested with egw1.2rc6 and clients:
* Korganizer (3.3.2,(read) 3.4.2, 3.5.0 (READ+WRITE))
* Mozilla calendar (2004040813-cal) (READ+WRITE)
* Evolution 2.2 (READ)
For further use and experience with these clients see @ref
pageicalsrvclients IcalSrvClients page.
@section secdocumentation Documentation
There is (somewhere) complete doxygen generated documentation for the
IcalSrv package. Otherwise you can generate it yourself by using
doxygen on the source filetree. Maybe you are just reading it now ...
@section sectestandebug Testing and Debugging
As IcalSrv is still a young and experimental new service for
Egroupware, that must mediate between a multitude of clients, each
with their own peculiarities and various internal applications of Egw,
it is very likely that a lot of problems, deficiencies and bugs will
appear.
Thus to get error feedback for it is a healthy thing. You should best
do this --as with any egw application-- using the sourcforge.net
buglist and the dedicated egroupware forums or mailinglist (see the
egroupware wiki for more instructions on this).
What to report? Well you should realize that IcalSrv is --currently--
on it self just a rather simple http interface script, that relies for
it connection to the egw backends heavily on the new (re) written
EgwIcal package. This means that problems with in and export of
iCalendar data will mostly have their source in that (i.e. EgwIcal)
package! So in case of errors allways report info on that package and
when debugging try the debug tools for that package.
@subsection subsecdebugtools Debugging of IcalSrv.
IcalSrv does not generate webpages, so to see any error or debug
information you there a jsut three other places to look at:
+ If you have a really problematic error, IcalSrv will answer your http
request with a 403 error and --hopefully-- a short message. In some
clients (like Korganize) this is reported back via a popup with a
silly message that "exporting went wrong or access denied" or so, instead of displaying
this message it got together with the 403 error. Note: Sunbird does
display the message. Unfortunately at the moment this will be mostly
"VEVENTS import ERROR" or so..
+ The httpd errorlog file/stream. Most problematic errors are reported
to this file of the egw server. So this is indeed the best source for
debug info. But to read it, you need access to the
server and to this log file. So only egw administrators are likely
the only ones for who this can be of help.
+ The ical.log files and ical.exportxxxx plus ical.importxxxx
files. If you did install the icalsrv.php file with the variable
$logdir set to folder where the httpd is allowed to write, you will
get a detailed log in file ical.log of all uploads and downloads via
IcalSrv furhtermore for each of these the associated iCalendar data
will be logged in ical.exportXXXXXX files with XXXX the utime of the
action. These files reside on the egw server, mostly in /tmp. So again
to read them you will need access to this server directory.
Off course this feature needs to be disabled in a production setting:
the file growth and the security issues of it demand it.
@section secbugandtodo BuG and todo list
-see BUGs and TODOs in @ref pageicalsrvbugandtodopage
have fun
JVL
*/

BIN
phpgwapi/doc/icalsrv/IcalSrv-doxydoc-0.9.02.tgz Normal file
View File

Binary file not shown.