/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* 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"

/**
 * Searching of cards on a directory.
 *
 * The search data is defined in the query
 * section of the directory URI, for example
 *
 * moz-abldapdirectory://ldap1.holland/dc=sun,dc=com?<query>
 *
 * If no search data is defined then the methods
 * will return immediately with no error. 
 */
[scriptable, uuid(ABF26047-37E3-44FD-A28A-6D37A1B9CCB3)]
interface nsIAbDirectorySearch : nsISupports
{
    /**
     * Starts a search on the directory.
     *
     * If a search is already being performed
     * it is stopped.
     *
     * The results from a search, cards, will
     * returned by informing the address book
     * session that a new card has been added
     * to the directory.
     *
     * The nsIAbDirectoryQuery implementation
     * of the directory component (or a proxy)
     * may be used as an implementation for
     * this specialization of query.
     *
     * This method is semantically equivalent
     * to the nsIAbDirectory.getChildCards
     * method when there is search criteria
     * defined in the directory uri.
     *
     */
    void startSearch ();

    /**
     * Stops a search on the directory.
     *
     */
    void stopSearch ();
};