package cal

import "time"

// A Backend supplies a calendar's events and, where the protocol allows
// it, accepts changes back.
//
// Everything above this line -- the tree, recurrence expansion, ctl,
// query, alarm, changed, the 9p service -- is the same whether the
// events arrived as a published .ics, over CalDAV or over JMAP. Only
// fetching and writing differ, so only fetching and writing live here.
type Backend interface {
	// Name of the calendar, as it appears in ctl.
	Name() string

	// Caps says what this backend can do, so that a tool can report
	// "read only" rather than trying and failing. The vocabulary is
	// read, write, rsvp, schedule; see pim/doc/design.md.
	Caps() string

	// Refresh is how often to poll. Zero means never.
	Refresh() time.Duration

	// Status reports when the backend last synced and the error, if
	// any, from that attempt.
	Status() (time.Time, string)

	// Sync brings the backend up to date and reports whether anything
	// actually changed. A backend that cannot tell should say true --
	// the cost is a needless rebuild, not a wrong answer.
	Sync() (bool, error)

	// Events returns the calendar as it now stands.
	Events() ([]*Event, error)
}

// Describer is implemented by backends with more to say in ctl: the
// source directory, the url, whatever identifies where events came from.
type Describer interface {
	Describe() string
}