/* 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 "nsISupports.idl"

interface calIOperation;
interface calIGenericOperationListener;

[scriptable, uuid(306DA1C9-DB54-4ef3-B27E-FEA709F638FF)]
interface calICalendarSearchProvider : nsISupports
{
    /**
     * Specifies whether the search string should exactly match.
     */
    const unsigned long HINT_EXACT_MATCH = 1;

    /* ...possibly more to come... */

    /**
     * Searches for calendars matching the specified search string.
     * It's up to the search provider what properties of a calendar
     * it takes into account for the search. The passed hints serve
     * for optimization purposes. Callers need to keep in mind that
     * providers may not be able to implement all of the stated hints
     * passed, thus are required to filter further if necessary.
     * Results are notified to the passed listener interface.
     *
     * @param aString     search string to match
     * @param aHints      search hints
     * @param aMaxResults maximum number of results
     *                    (0 denotes provider specific maximum)
     * @param aListener   called with an array of calICalendar objects
     * @return            optional operation handle to track the operation
     */
    calIOperation searchForCalendars(in AUTF8String aString,
                                     in unsigned long aHints,
                                     in unsigned long aMaxResults,
                                     in calIGenericOperationListener aListener);
};

/**
 * This service acts as a central access point for calendar lookup.
 * A search request will be multiplexed to all added search providers.
 * Adding a search provider is transient.
 */
[scriptable, uuid(2F2055CA-F558-4dc8-A1D4-11384A00E85C)]
interface calICalendarSearchService : calICalendarSearchProvider
{
    /**
     * Gets the currently registered set of search providers.
     */
    void getProviders(out uint32_t aCount,
                      [array, size_is(aCount), retval] out calICalendarSearchProvider aProviders);

    /**
     * Adds a new search provider.
     */
    void addProvider(in calICalendarSearchProvider aProvider);

    /**
     * Removes a search provider.
     */
    void removeProvider(in calICalendarSearchProvider aProvider);
};
