imip-agent

Annotated docs/wiki/Preferences

1362:d96b4761e6f0
1214:3bc482b5f33e
2017-10-24 Paul Boddie file changeset files shortlog Remove superfluous result collection slicing and count method parameter.
paul@961 1 
= Preferences =
paul@961 2 
 
 paul@961      3 
The correspondence between user preferences (stored in user preference
 
 paul@1214      4 
directories) and the default settings (stored in `config.txt`) is described
 
 paul@961      5 
below.
 
 paul@961      6 
 
 paul@961      7 
|| '''Preference'''        || '''Default Setting''' ||
 
 paul@961      8 
|| `LANG`                  || `LANG` ||
 
 paul@961      9 
|| `add_method_response`   || `ADD_RESPONSE_DEFAULT` ||
 
 paul@961     10 
|| `event_refreshing`      || `REFRESHING_DEFAULT` ||
 
 paul@961     11 
|| `freebusy_bundling`     || `BUNDLING_DEFAULT` ||
 
 paul@961     12 
|| `freebusy_messages`     || `NOTIFYING_DEFAULT` ||
 
 paul@961     13 
|| `freebusy_offers`       || `FREEBUSY_OFFER_DEFAULT` ||
 
 paul@961     14 
|| `freebusy_publishing`   || `PUBLISHING_DEFAULT` ||
 
 paul@961     15 
|| `freebusy_sharing`      || `SHARING_DEFAULT` ||
 
 paul@961     16 
|| `incoming`              || `INCOMING_DEFAULT` ||
 
 paul@961     17 
|| `organiser_replacement` || `ORGANISER_REPLACEMENT_DEFAULT` ||
 
 paul@961     18 
|| `participating`         || `PARTICIPATING_DEFAULT` ||
 
 paul@961     19 
 
 paul@961     20 
See the [[../Configuration|configuration guide]] for more information about
 
 paul@1214     21 
the `config.txt` file.
 
 paul@961     22 
 
 paul@1112     23 
{{{#!wiki tip
 
 paul@1112     24 
=== Text Encoding ===
 
 paul@1112     25 
The textual encoding employed by all preferences files is UTF-8.
 
 paul@1112     26 
}}}
 
 paul@1112     27 
 
 paul@961     28 
== User Preference Settings ==
 
 paul@961     29 
 
 paul@961     30 
<<TableOfContents(3,3)>>
 
 paul@961     31 
 
 paul@961     32 
Each of the user preferences or settings are stored in a separate file within
 
 paul@961     33 
a dedicated preferences directory for each user, with the filename bearing the
 
 paul@988     34 
name of the setting concerned. See the [[../FilesystemUsage|filesystem guide]]
 
 paul@988     35 
for more information.
 
 paul@961     36 
 
 paul@961     37 
=== CN ===
 
 paul@961     38 
 
 paul@961     39 
 Default:: (none)
 
 paul@961     40 
 Alternatives:: (see below)
 
 paul@961     41 
 
 paul@961     42 
The common name of the user, employed in iCalendar objects and user
 
 paul@961     43 
interfaces.
 
 paul@961     44 
 
 paul@961     45 
=== LANG ===
 
 paul@961     46 
 
 paul@961     47 
 Default:: `en` (English)
 
 paul@961     48 
 Alternatives:: (any recognised and supported locale)
 
 paul@961     49 
 
 paul@961     50 
The language for messages and user interface text.
 
 paul@961     51 
 
 paul@961     52 
=== TZID ===
 
 paul@961     53 
 
 paul@961     54 
 Default:: system timezone (see `/etc/timezone`)
 
 paul@961     55 
 Alternatives:: (any recognised Olson time zone identifier)
 
 paul@961     56 
 
 paul@961     57 
The default time zone/regime for calendars, new events and local times.
 
 paul@961     58 
 
 paul@1032     59 
=== acl ===
 
 paul@1032     60 
 
 paul@1032     61 
 Default:: (none)
 
 paul@1032     62 
 Alternatives:: (see below)
 
 paul@1032     63 
 
 paul@1032     64 
Provides an access control list for the `access_control_list` scheduling
 
 paul@1032     65 
function, invoked using the `scheduling_functions` setting. An access control
 
 paul@1032     66 
list consists of a collection of lines of text describing the handling policy
 
 paul@1032     67 
for an incoming invitation.
 
 paul@1032     68 
 
 paul@1032     69 
{{{#!table
 
 paul@1032     70 
`accept` || indicates that if no rule matches, the invitation will be accepted
 
 paul@1032     71 
         .. (provisionally)
 
 paul@1032     72 
==
 
 paul@1032     73 
`decline` ||<rowspan="2"> indicates that if no rule matches, the invitation
 
 paul@1032     74 
                       .. will be declined (provisionally)
 
 paul@1032     75 
==
 
 paul@1032     76 
`reject`
 
 paul@1032     77 
==
 
 paul@1032     78 
`accept` ''`role`'' ''`identity`'' || indicates that where the given
 
 paul@1032     79 
                                   .. ''`identity`'' exists in the given
 
 paul@1032     80 
         .. ''`role`'' in the event, and unless a subsequent rule contradicts
 
 paul@1032     81 
         .. this result, the invitation will be accepted (provisionally)
 
 paul@1032     82 
==
 
 paul@1032     83 
`decline` ''`role`'' ''`identity`'' ||<rowspan="2"> indicates that where the
 
 paul@1032     84 
                                                 .. given ''`identity`'' exists
 
 paul@1032     85 
         .. in the given ''`role`'' in the event, and unless a subsequent rule
 
 paul@1032     86 
         .. contradicts this result, the invitation will be declined
 
 paul@1032     87 
         .. (provisionally)
 
 paul@1032     88 
 
 paul@1032     89 
==
 
 paul@1032     90 
`reject` ''`role`'' ''`identity`''
 
 paul@1032     91 
}}}
 
 paul@1032     92 
 
 paul@1032     93 
In the above, `role` is either `organiser` (or `organizer`) or `attendee`;
 
 paul@1032     94 
`identity` is an address or URL.
 
 paul@1032     95 
 
 paul@1032     96 
Note that even if an accepted result is returned by the `access_control_list`
 
 paul@1032     97 
scheduling function, other functions that follow it in the list of functions
 
 paul@1032     98 
may overturn this result.
 
 paul@1032     99 
 
 paul@1032    100 
See the [[../Resources|resources guide]] for examples and more information.
 
 paul@1032    101 
 
 paul@961    102 
=== add_method_response ===
 
 paul@961    103 
 
 paul@961    104 
 Default:: `refresh`
 
 paul@961    105 
 Alternatives:: (see below)
 
 paul@961    106 
 
 paul@961    107 
Indicate how `ADD` methods shall be responded to when received by a recipient:
 
 paul@961    108 
 
 paul@961    109 
{{{#!table
 
 paul@961    110 
`add`     || apply them to events as received
 
 paul@961    111 
==
 
 paul@961    112 
`ignore`  || ignore attempts to add event occurrences
 
 paul@961    113 
==
 
 paul@961    114 
`refresh` || respond with a `REFRESH` message to obtain a proper request with
 
 paul@961    115 
          .. all event details
 
 paul@961    116 
}}}
 
 paul@961    117 
 
 paul@961    118 
=== event_refreshing ===
 
 paul@961    119 
 
 paul@961    120 
 Default:: `never`
 
 paul@961    121 
 Alternative:: `always`
 
 paul@961    122 
 
 paul@961    123 
Indicate whether messages requesting a refresh of event details shall be
 
 paul@961    124 
handled automatically. If not, such messages will be passed on to the
 
 paul@961    125 
recipient for their mail program to handle.
 
 paul@961    126 
 
 paul@961    127 
=== freebusy_bundling ===
 
 paul@961    128 
 
 paul@961    129 
 Default:: `never`
 
 paul@961    130 
 Alternative:: `always`
 
 paul@961    131 
 
 paul@961    132 
Indicate whether to bundle free/busy details with other payloads such as
 
 paul@961    133 
event and free/busy objects. The `freebusy_sharing` setting must be
 
 paul@961    134 
configured for bundling to operate.
 
 paul@961    135 
 
 paul@961    136 
=== freebusy_messages ===
 
 paul@961    137 
 
 paul@961    138 
 Default:: `none`
 
 paul@961    139 
 Alternative:: `notify`
 
 paul@961    140 
 
 paul@961    141 
Indicate whether recipients are notified about received free/busy payloads.
 
 paul@961    142 
 
 paul@961    143 
=== freebusy_offers ===
 
 paul@961    144 
 
 paul@961    145 
 Default:: (none)
 
 paul@961    146 
 Alternative:: (see below)
 
 paul@961    147 
 
 paul@961    148 
Define the period for which free/busy offers are extended by participants
 
 paul@961    149 
supporting this setting when counter-proposals are made during event
 
 paul@961    150 
scheduling.
 
 paul@961    151 
 
 paul@961    152 
This setting requires a value indicating a duration as described in the
 
 paul@961    153 
iCalendar format specification:
 
 paul@961    154 
 
 paul@961    155 
http://tools.ietf.org/html/rfc5545#section-3.3.6
 
 paul@961    156 
 
 paul@961    157 
For example:
 
 paul@961    158 
 
 paul@961    159 
|| `PT10M`  || extend scheduling offers for 10 minutes ||
 
 paul@961    160 
|| `PT600S` || extend scheduling offers for 600 seconds (10 minutes) ||
 
 paul@961    161 
|| `PT1D`   || extend offers for 1 day ||
 
 paul@961    162 
 
 paul@961    163 
=== freebusy_publishing ===
 
 paul@961    164 
 
 paul@961    165 
 Default:: `no`
 
 paul@961    166 
 Alternative:: `publish`
 
 paul@961    167 
 
 paul@961    168 
Indicate whether to publish free/busy details as Web resources. The
 
 paul@961    169 
`freebusy_sharing` setting must be configured for publishing to operate.
 
 paul@961    170 
 
 paul@961    171 
=== freebusy_sharing ===
 
 paul@961    172 
 
 paul@961    173 
 Default:: `no`
 
 paul@961    174 
 Alternative:: `share`
 
 paul@961    175 
 
 paul@961    176 
Share free/busy details generally:
 
 paul@961    177 
 
 paul@961    178 
  * bundling in e-mail messages if bundling is configured
 
 paul@961    179 
  * responding to free/busy requests via e-mail
 
 paul@961    180 
  * publishing as Web resources if a static Web resource is configured and if
 
 paul@961    181 
  publishing is configured
 
 paul@961    182 
 
 paul@961    183 
=== incoming ===
 
 paul@961    184 
 
 paul@961    185 
 Default:: `summary-wraps-message`
 
 paul@961    186 
 Alternatives:: (see below)
 
 paul@961    187 
 
 paul@961    188 
Define how incoming event messages are delivered to recipients:
 
 paul@961    189 
 
 paul@961    190 
{{{#!table
 
 paul@961    191 
`message-only`
 
 paul@961    192 
|| deliver only the incoming message as it was received
 
 paul@961    193 
==
 
 paul@961    194 
`message-then-summary`
 
 paul@961    195 
|| deliver the message first followed by a summary message
 
 paul@961    196 
==
 
 paul@961    197 
`summary-then-message`
 
 paul@961    198 
|| deliver a summary first followed by the message
 
 paul@961    199 
==
 
 paul@961    200 
`summary-only`
 
 paul@961    201 
|| deliver only a summary of the message
 
 paul@961    202 
==
 
 paul@961    203 
`summary-wraps-message`
 
 paul@961    204 
|| deliver a summary that includes the original message as an attachment
 
 paul@961    205 
}}}
 
 paul@961    206 
 
 paul@961    207 
=== organiser_replacement ===
 
 paul@961    208 
 
 paul@961    209 
 Default:: `attendee`
 
 paul@961    210 
 Alternatives:: (see below)
 
 paul@961    211 
 
 paul@961    212 
Indicate whether the organiser of an event can be replaced and the nature of
 
 paul@961    213 
any replacement:
 
 paul@961    214 
 
 paul@961    215 
{{{#!table
 
 paul@961    216 
`any` || any identity, regardless of whether it is already present or even
 
 paul@961    217 
      .. previously unknown, may become the organiser
 
 paul@961    218 
==
 
 paul@961    219 
`attendee` || any new organiser must be a previously-recognised attendee
 
 paul@961    220 
==
 
 paul@961    221 
`never` || forbid the replacement of an event's organiser
 
 paul@961    222 
}}}
 
 paul@961    223 
 
 paul@961    224 
=== participating ===
 
 paul@961    225 
 
 paul@961    226 
 Default:: `participate`
 
 paul@961    227 
 Alternative:: `no`
 
 paul@961    228 
 
 paul@961    229 
Indicate whether a recipient participates in the calendar system. Note that
 
 paul@961    230 
participation by default occurs because the handler programs will be defined
 
 paul@961    231 
in the mail system for recipients fulfilling certain criteria; other
 
 paul@961    232 
recipients will be handled in other ways. Thus, initial non-participation must
 
 paul@961    233 
be defined by initialising this setting to "no" for all eligible users, if
 
 paul@961    234 
this is the general policy on initial calendar system participation.
 
 paul@961    235 
 
 paul@961    236 
=== permitted_times ===
 
 paul@961    237 
 
 paul@961    238 
 Default:: (none)
 
 paul@961    239 
 Alternatives:: (see below)
 
 paul@961    240 
 
 paul@961    241 
Define the time values at which events can be scheduled. In its simplest form,
 
 paul@961    242 
this indicates the resolution of a calendar for a participant supporting this
 
 paul@961    243 
setting, with the given minute values being those allowed for the start and
 
 paul@961    244 
end of an event. This setting requires a value of one of the following forms:
 
 paul@961    245 
 
 paul@961    246 
{{{
 
 paul@961    247 
<minute values>
 
 paul@961    248 
<hour values>:<minute values>
 
 paul@961    249 
<hour values>:<minute values>:<second values>
 
 paul@961    250 
}}}
 
 paul@961    251 
 
 paul@961    252 
Each list of values is a comma-separated collection of permissible values for
 
 paul@961    253 
the unit of time being constrained. Any unspecified list is taken to permit
 
 paul@961    254 
all normally permissible values for that unit of time. For example:
 
 paul@961    255 
 
 paul@961    256 
{{{#!table
 
 paul@961    257 
`0,15,30,45`          || every 15 minutes from the start of each hour
 
 paul@961    258 
==
 
 paul@961    259 
`10,12,14,16:0,20,40` || every 20 minutes from 10:00 until 16:40 inclusive
 
 paul@961    260 
==
 
 paul@961    261 
`12::0,30`            ||  every 30 seconds from the start of each minute
 
 paul@961    262 
                      .. during the period from 12:00:00 until 12:59:30
 
 paul@961    263 
                      .. inclusive
 
 paul@961    264 
}}}
 
 paul@961    265 
 
 paul@961    266 
The purpose of this setting is not necessarily to impose availability
 
 paul@961    267 
constraints but instead to impose a "grid" to which event start and end points
 
 paul@961    268 
shall be "locked".
 
 paul@961    269 
 
 paul@961    270 
The values are interpreted in the local time of the participant. Thus, a time
 
 paul@961    271 
represented in UTC may have apparently inappropriate hour (and for some zones)
 
 paul@961    272 
minute values that correspond to permitted values in this participant's own
 
 paul@961    273 
time zone.
 
 paul@961    274 
 
 paul@961    275 
=== scheduling_function ===
 
 paul@961    276 
 
 paul@961    277 
 Default:: `schedule_in_freebusy`
 
 paul@961    278 
 Alternatives:: (see below)
 
 paul@961    279 
 
 paul@1032    280 
Indicates the scheduling functions used by [[../Resources|resources]] to find
 
 paul@1032    281 
an appropriate period for an event, with each function to be applied to a
 
 paul@1032    282 
scheduling request appearing on a separate line, optionally accompanied by
 
 paul@1032    283 
arguments controlling the behaviour of the function.
 
 paul@1025    284 
 
 paul@1039    285 
The `imiptools.handlers.scheduling` module contains the built-in scheduling
 
 paul@1025    286 
functions which include the following:
 
 paul@961    287 
 
 paul@961    288 
{{{#!table
 
 paul@1032    289 
`access_control_list`  || use an access control list provided by a file whose
 
 paul@1032    290 
                       .. name is given as an argument, accepting or declining
 
 paul@1032    291 
                       .. the invitation according to the indicated rules
 
 paul@1032    292 
                       .. (described in the [[../Resources|resources guide]])
 
 paul@1032    293 
==
 
 paul@1039    294 
`check_quota`          || accept an invitation only if the organiser does not
 
 paul@1042    295 
                       .. exceed their quota allowance for bookings for the
 
 paul@1042    296 
                       .. indicated quota group
 
 paul@1042    297 
                       .. (described in the [[../Resources|resources guide]])
 
 paul@1042    298 
==
 
 paul@1180    299 
`same_domain_only`     || accept an invitation only if the organiser employs an
 
 paul@1180    300 
                       .. address in the same domain as the resource
 
 paul@1180    301 
==
 
 paul@1042    302 
`schedule_across_quota`|| accept an invitation only if the organiser has not
 
 paul@1042    303 
                       .. reserved a resource for a conflicting period in any
 
 paul@1042    304 
                       .. other resource belonging to the indicated quota group
 
 paul@1039    305 
                       .. (described in the [[../Resources|resources guide]])
 
 paul@1039    306 
==
 
 paul@1180    307 
`schedule_for_delegate`|| accept an invitation only if the organiser can
 
 paul@1180    308 
                       .. reserve the resource according to the common quota
 
 paul@1180    309 
                       .. schedule, delegating to any other available resource
 
 paul@1180    310 
                       .. defined as a potential delegate, declining if no
 
 paul@1180    311 
                       .. resource is available
 
 paul@1180    312 
                       .. (described in the [[../Resources|resources guide]])
 
 paul@1030    313 
==
 
 paul@961    314 
`schedule_in_freebusy` || accept an invitation if the event periods are free
 
 paul@961    315 
                       .. according to the free/busy records for the resource;
 
 paul@961    316 
                       .. decline otherwise
 
 paul@961    317 
==
 
 paul@961    318 
`schedule_corrected_in_freebusy` || correct periods in an event according to
 
 paul@961    319 
                                 .. the permitted_times setting (see above),
 
 paul@961    320 
                       .. then attempt to schedule the event according to the
 
 paul@961    321 
                       .. free/busy records for the resource
 
 paul@961    322 
==
 
 paul@961    323 
`schedule_next_available_in_freebusy` || correct periods in an event according
 
 paul@961    324 
                                      .. to the permitted_times setting (see
 
 paul@961    325 
                       .. above), if configured, and attempt to schedule the
 
 paul@961    326 
                       .. event according to the free/busy records for the
 
 paul@961    327 
                       .. resource and for any attendees for whom records are
 
 paul@961    328 
                       .. available, seeking the next available free period for
 
 paul@961    329 
                       .. each period that conflicts with an existing event
 
 paul@961    330 
}}}
 
 paul@961    331 
 
 paul@961    332 
The scheduling mechanism can be extended by implementing additional scheduling
 
 paul@961    333 
functions or by extending the handler framework directly.