= Filesystem Usage =

The behaviour and operation of imip-agent is controlled by resources stored
in the filesystem on the host on which the software is running. These resources
are organised as follows:

{{{#!table
'''Resource''' || '''Default Location''' || '''Purpose'''
==
Free/busy || `/var/www/imip-agent/static`
|| Per-user directories containing [[../FreeBusyPublishing|free/busy resources]]
.. for publication over the Web
==
Journal || `/var/lib/imip-agent/journal`
|| Per-quota directories containing journal information recording
.. [[../Resources|resource]] usage
==
Preferences || `/var/lib/imip-agent/preferences`
|| Per-user directories containing [[../Preferences|preferences]] controlling
.. each user's experience of the software
==
Store || `/var/lib/imip-agent/store`
|| Per-user directories containing calendar objects and scheduling information
}}}

Note that the free/busy resources are located in `/var/www` as opposed to
`/var/lib` since they are intended to be published on the Web.

Meanwhile, the journal and store resources are only present in the filesystem
if the [[../FileStore|file store]] is in use. Where a
[[../DatabaseStore|database store]] is being used instead, such resources are
located in a database system.

== Journal Structure ==

Within the journal directory are a collection of subdirectories, each of which
represent a distinct quota group for one or more [[../Resources|resources]].
When a user attempts to reserve a resource in such a group, their ability to
schedule that resource will depend on how much they are using the other
resources in that group.

The directory for each quota group contains the following entries:

{{{{#!table
'''Entry''' || '''Purpose'''
==
`delegates`
|| A file containing details of the identities employing this quota to consolidate
.. their schedules, between which delegation may take place if their schedules
.. permit it
==
`freebusy-other`
|| A directory containing files, one per user (each containing period descriptions
.. for reservations made by that user, in chronological order, structured
.. similarly to the `freebusy` file found in each user's own store) or one per
.. group (for reservations made by users belonging to the groups defined for the
.. quota); the record in each file is consolidated for all resources in a quota
.. group
{{{
freebusy-other/GROUP
freebusy-other/USER
}}}
==
`freebusy-providers`
|| A file containing details of [[../EventRecurrences|recurring events]] for which
.. new free/busy records must be [[../CronIntegration|periodically generated]]
.. because these events recur indefinitely
==
`groups`
|| A mapping from user identities to group identifiers indicating the sharing
.. of a quota across a number of users
==
`limits`
|| A mapping from user identities or group identifiers to quota limits
}}}}

== Store Structure ==

Within the store directory are a collection of user-specific subdirectories
acting as each user's own store directory containing various files and further
subdirectories.

The store directory for each user is considered in isolation from all other
users' directories: imip-agent ''does not'' go looking for information belonging
to other users when processing information on behalf of a particular user.

The following entries are defined within a user's own store directory:

{{{{#!table
'''Entry''' || '''Purpose'''
==
`cancellations`
|| Retains cancelled event details in `objects` and `recurrences` structures
.. corresponding to those at the top level of the store from which the
.. cancelled events originate:
{{{
cancellations/objects/UID
cancellations/recurrences/UID/RECURRENCE-ID
}}}
==
`counters`
|| Retains counter-proposals for events in `objects` and `recurrences`
.. structures corresponding to those at the top level of the store for which
.. the counter-proposals are received, with a counter-proposal for each
.. respondent being held for each object or recurrence involved:
{{{
counters/objects/UID/ATTENDEE
counters/recurrences/UID/RECURRENCE-ID/ATTENDEE
}}}
==
`freebusy`
|| A file containing period descriptions in chronological order, one per line,
.. indicating start and end datetimes (in UTC), unique identifier (`UID`),
.. transparency, summary and organiser
==
`freebusy-offers`
|| A file containing period descriptions in chronological order for
.. scheduling offers made by counter-proposals sent by the user
==
`freebusy-other`
|| A collection of files, one per user, each containing period descriptions
.. received or deduced for that user in chronological order, structured similarly
.. to the store user's own `freebusy` file
{{{
freebusy-other/USER
}}}
==
`freebusy-providers`
|| A file containing details of [[../EventRecurrences|recurring events]] for which
.. new free/busy records must be [[../CronIntegration|periodically generated]]
.. because these events recur indefinitely
==
`objects`
|| A collection of files, one per event, each bearing as its name the unique
.. identifier (`UID`) of the event, with each file containing the event data:
{{{
objects/UID
}}}
==
`recurrences`
|| A collection of directories, one per "parent" event, each bearing as its name
.. the unique identifier (`UID`) of the event, with each directory containing a
.. collection of files, one per event recurrence, each bearing as its name the
.. normalised recurrence identifier (`RECURRENCE-ID`) of the recurrence, with each
.. file containing the data of the event recurrence:
{{{
recurrences/UID/RECURRENCE-ID
}}}
==
`requests`
|| A list of records, one per line, each consisting of a unique identifier (`UID`),
.. normalised recurrence identifier (`RECURRENCE-ID`) if appropriate, and
.. (optionally) a scheduling method, indicating the availability of an incoming
.. scheduling request for handling by a user
}}}}
