mirror of
https://github.com/samsonjs/vdirsyncer.git
synced 2026-03-25 08:55:50 +00:00
63 lines
2 KiB
ReStructuredText
63 lines
2 KiB
ReStructuredText
=======================
|
|
The vdir Storage Format
|
|
=======================
|
|
|
|
This document describes a standard for storing calendars and contacts on a
|
|
filesystem, with the main goal of being easy to implement.
|
|
|
|
Basic Structure
|
|
===============
|
|
|
|
The main folder (root) contains an arbitrary number of subfolders
|
|
(collections), which contain only files (items). Synonyms for "collection" may
|
|
be "addressbook" or "calendar".
|
|
|
|
An item is:
|
|
|
|
- A vCard_ file, in which case the file extension *must* be `.vcf`, *or*
|
|
- An iCalendar_ file, in which case the file extension *must* be `.ics`.
|
|
|
|
An item *should* contain a ``UID`` property as described by the vCard and
|
|
iCalendar standards.
|
|
|
|
The filename *must* consist of the ``ident``, followed by the file extension.
|
|
The ``ident`` is either the ``UID``, if the item has one, else a string with
|
|
similar properties as the ``UID``:
|
|
|
|
Type name: UID
|
|
|
|
Type purpose: To specify a value that represents a globally unique
|
|
identifier corresponding to the individual or resource associated
|
|
with the vCard.
|
|
|
|
-- The vCard_ RFC
|
|
|
|
One reason this format was chosen is due to its compatibility with the CardDAV_
|
|
and CalDAV_ standards.
|
|
|
|
.. _vCard: https://tools.ietf.org/html/rfc6350
|
|
.. _iCalendar: https://tools.ietf.org/html/rfc5545
|
|
.. _CardDAV: http://tools.ietf.org/html/rfc6352
|
|
.. _CalDAV: http://tools.ietf.org/search/rfc4791
|
|
|
|
Writing to vdirs
|
|
================
|
|
|
|
Creating and modifying items *should* happen atomically_.
|
|
|
|
Writing to a temporary file on the same physical device, and then moving it to
|
|
the appropriate location is usually a very effective solution. For this
|
|
purpose, files with the extension ``.tmp`` may be created inside collections.
|
|
|
|
When changing an item, the original filename *must* be used.
|
|
|
|
.. _atomically: https://en.wikipedia.org/wiki/Atomicity_%28programming%29
|
|
|
|
Reading from vdirs
|
|
==================
|
|
|
|
- Any file ending with the ``.tmp`` or no file extension *must not* be treated
|
|
as an item.
|
|
|
|
- The ``ident`` part of the filename *should not* be parsed to improve the
|
|
speed of item lookup.
|