/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "calICalendar.idl"

interface calIGenericOperationListener;
interface calIOperation;

/**
 * Interface for managing offline flags in offline storage
 * (calStorageCalendar), in particular from calICachedCalendar.
 */
[scriptable, uuid(36dc2c93-5851-40d2-9ba9-b1f6e682c75c)]
interface calIOfflineStorage : calICalendar {
    /**
     * Mark the item of which the id is passed as parameter as new.
     *
     * @param aItem       the item to add
     *
     * @return {Promise<void>}
     */
    Promise addOfflineItem(in calIItemBase aItem);

    /**
     * Mark the item of which the id is passed as parameter as modified.
     *
     * @param aItem       the item to modify
     *
     * @return {Promise<void>}
     */
    Promise modifyOfflineItem(in calIItemBase aItem);

    /**
     * Mark the item of which the id is passed as parameter as deleted.
     *
     * @param aItem       the item to delete
     * @return {Promise<void>}
     */
    Promise deleteOfflineItem(in calIItemBase aItem);

    /**
     * Retrieves the offline flag for the given item.
     *
     * @param aItem       the item to reset
     * @return {Promise<number>}
     */
    Promise getItemOfflineFlag(in calIItemBase aItem);

    /**
     * Remove any offline flag from the item record.
     *
     * @param aItem       the item to reset
     * @return {Promise<void>}
     */
    Promise resetItemOfflineFlag(in calIItemBase aItem);
};

/**
 * Interface for synchronously working providers on storing items,
 * e.g. storage, memory. All modifying commands return after the
 * modification has been performed.
 *
 * @note
 *   This interface is used in conjunction with changelog-based synchronization
 *   and additionally offers storing meta-data for items for this purpose.
 *   The meta data is stored as long as the corresponding items persist in
 *   the calendar and automatically cleanup up once the item is deleted from
 *   the calendar, but is not altered when an item is modified (modifyItem).
 *   Meta data can be fetched/stored per (master) item, i.e. if you need to
 *   store meta data for individual overridden items, you need to store it
 *   along with the master item's meta data.
 *   Finally, keep in mind that the meta data is "calendar local" and not
 *   automatically transferred when storing the item on another calISyncWriteCalendar.
 */
[scriptable, uuid(651e137b-2f3a-4595-af89-da51b6a37f85)]
interface calISyncWriteCalendar : calICalendar {
    /**
     * Adds or replaces meta data of an item.
     *
     * @param id    an item id
     * @param value an arbitrary string
     */
    void setMetaData(in AUTF8String id,
                     in AUTF8String value);

    /**
     * Deletes meta data of an item.
     *
     * @param id    an item id
     */
    void deleteMetaData(in AUTF8String id);

    /**
     * Gets meta data of an item or null if there's none or the item id is invalid.
     *
     * @param id    an item id
     */
    AUTF8String getMetaData(in AUTF8String id);

    /**
     * Gets all meta data IDs.
     */
    Array<AString> getAllMetaDataIds();

    /**
     * Gets all meta data values.
     */
    Array<AString> getAllMetaDataValues();
};

/**
 * Calendar implementing this interface have improved means of replaying their
 * changelog data. This could for example mean, that the provider can retrieve
 * changes between now and the last sync.
 *
 * Not implementing this interface is perfectly valid for calendars, that need
 * to do a full sync each time anyway (i.e ics)
 */
[scriptable, uuid(0bf4c6a2-b4c7-4cae-993a-4408d8bded3e)]
interface calIChangeLog : nsISupports {

    // To denote no offline flag, use null
    const long OFFLINE_FLAG_CREATED_RECORD = 1;
    const long OFFLINE_FLAG_MODIFIED_RECORD = 2;
    const long OFFLINE_FLAG_DELETED_RECORD = 4;

    /**
     * Enable the changelog calendar to retrieve offline data right after instantiation.
     */
    attribute calISyncWriteCalendar offlineStorage;

    /**
     * Resets the changelog. This is used if the cache should be refreshed.
     */
    void resetLog();

    /**
     * Instructs the calendar to replay remote changes into the above offlineStorage
     * calendar. The calendar itself is responsible for storing anything needed
     * to keep track of what items need updating.
     *
     * TODO: We might reconsider to replay on calICalendar,
     *       but this complicates implementing this interface
     *       enormously for providers.
     *
     * @param aDestination      The calendar to sync changes into
     * @param aListener         The listener to notify when the operation completes.
     */
    calIOperation replayChangesOn(in calIGenericOperationListener aListener);
};