/*!  @mainpage  Ical Service for Egroupware

@note this is still <b>EXPERIMENTAL, USE AT YOUR OWN RISK! </b> and better not yet in a
production environment.
@version 0.9.01R2
@author jvl
@date 20060314

@section secabout About IcalSrv

At the moment IcalSrv is a small package that allows a socalled
<i>ical client</i> like Mozilla Sunbird, Apple iCal or Korganizer to
access the events and tasks from a persons egroupware calendar and
infolog application, remotely via a "icalendar over http"
connection. (see @ref secicalsrvclients)

This means that in the client you can download (aka <i> reload </i>)
the data from an a socalled <i> subscribed </i> calendar on the
egroupware server and then read and manipulate it offline.  On a
later moment you can upload (aka <i> publish </i>) this client
calendardata again to egroupware. The changes made in your client
should then propagate to your calendars and infolog maintained on the
egw server. All this provided you have the appropiate access rights
for the egroupware server data.

At the moment, the IcalSrv service is just a simple --experimental-- variant
that is not based on webdav (as most of these services), but that may
nevertheless can be quite practical. It allows only upload and
download of complete calendars (with events and todos) and no direct
deletions of events. (Read more on this below at @ref secdeletions ) 

We are working on extensions towards real groupdav and caldav behaviour.


@note We tried to prevent that accidental misuse of the service can ruin all
your egroupware data. But, <b> be warned: when you use the service for
<i>publishing</i> from the client, you can (and want to) change data
in the egroupware server, and thus you have a potential risk of damaging
or losing egroupware data!</b>




@section secinstall SHORT experimental Install How-To:
		 
 - Best thing to do before installing, is to have a look at the
   egroupware wiki page about IcalSrv
   at @url http://www.egroupware.org/egroupware/wiki/index.php?page=IcalSrv
   .
   There you can find the current status of the project and see what
   the latest available versions are and where to find them. In @ref pageicalsrvreleaselog
   you find a small release notes document that tells of about the changes in
   the releases.

 - Install the icalsrv package by either checking out the icalsrv stuff from cvs
  or untarring some tarball icalsrv-vx.y.x.tgz of the package (if available). 
  At the moment (200602xx) the icalsrv is partly in cvs module <i>egroupware</i> and
  partly (the documentation only) in module <i>phpgwapi</i>. So be sure to update at least the first one!
 - @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. Likewise this can be installed by untarring an appropiate
   egwical-vx.y.z.tgz tarball or by checking out the <i> egwical</i> module from cvs (HEAD).

 - Take care that icalsrv.php is <code>.../egroupware/icalsrv.php</code>
(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 <code>/var/www/egroupware</code> and with a http alias
 <code>egroupware</code> 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 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)
  - Apple Ical, is reported to be working too. (READ+WRITE)

 See @ref pageicalsrvclients for further use and experience with these
 clients and supported features <i>Now with screenshots too!!</i>


@section secdeletions Deleting Calendars, events or todos

deletion of the whole remote calendar is not supported see the webcal
protocol discussion in @ref pagewebcaldiscussion

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 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-- by following the guidelines
See the egroupware wiki at @url http://www.egroupware.org/bug-reports
for more instructions on this)

This will point you to the sourceforge.net Egroupware buglist at @url
https://sourceforge.net/tracker/?group_id=78745&atid=554338 and the
dedicated egroupware forums or mailinglist at @url
http://www.egroupware.org/forum/?page_name=forum

What to report? Well you should realize that IcalSrv is --currently--
on it self just a rather simple http interface script, that relies for
its 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, there a just three other places to look at:

-# The HTTP error message. <br>
  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. <br>
  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 <br>
  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.
  Of 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 pageicalsrvbugandtodo
  -see Todo page in ..



have fun


JVL


*/