gecko-dev/mailnews/addrbook/public/nsIAbDirectoryQuery.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is
 * Sun Microsystems, Inc.
 * Portions created by the Initial Developer are Copyright (C) 2001
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Created by: Paul Sandoz   <paul.sandoz@sun.com>
 *   Dan Mosedale <dan.mosedale@oracle.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either of the GNU General Public License Version 2 or later (the "GPL"),
 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */


#include "nsISupports.idl"
#include "nsISupportsArray.idl"
#include "nsIAbBooleanExpression.idl"

/**
 * The arguments for a query.
 *
 * Contains an expression for perform matches
 * and an array of properties which should be
 * returned if a match is found from the expression
 *
 */
[scriptable, uuid(c2d83a31-eba6-4053-9273-c7a006a94311)]
interface nsIAbDirectoryQueryArguments : nsISupports
{
    /**
     * Defines the boolean expression for
     * the matching of cards
     *
     */
    attribute nsISupports expression;

    /**
     * Defines if sub directories should be
     * queried 
     *
     */
    attribute boolean querySubDirectories;

    /**
     * The list of properties which should
     * be returned if a match occurs on a card
     *
     */
    void setReturnProperties (in unsigned long returnPropertiesSize,
        [array, size_is(returnPropertiesSize)]
        in string returnPropertiesArray);
    void getReturnProperties (out unsigned long returnPropertiesSize,
        [retval, array, size_is(returnPropertiesSize)]
        out string returnPropertiesArray);

    /** 
     * A parameter which can be used to pass in data specific to a particular
     * type of addressbook.  
     */
    attribute nsISupports typeSpecificArg;
};


[scriptable, uuid(3A6E0C0C-1DD2-11B2-B23D-EA3A8CCB333C)]
interface nsIAbDirectoryQueryPropertyValue : nsISupports
{
    /**
     * The property which should be matched
     *
     * For example 'primaryEmail' or 'homePhone'
     * for card properties.
     *
     * Two further properties are defined that 
     * do not exist as properties on a card.
     *
     * 'card:nsIAbCard' which represents the interface
     * of a card component
     *
     */
    readonly attribute string name;

    /**
     * The value of the property
     *
     */
    readonly attribute wstring value;
    
    /**
     * The value of the property
     * as an interface
     *
     * Only valid if the corresponding
     * property name is related to an
     * interface instead of a wstring
     *
     */
    readonly attribute nsISupports valueISupports;
};

[scriptable, uuid(42E600BA-1DD2-11B2-BC39-C363AC0C93E3)]
interface nsIAbDirectoryQueryResult : nsISupports
{
    /**
     * The context ID of the query
     *
     */
    readonly attribute long contextID;

    /**
     * The context of the query which
     * corresponds to the arguments that
     * define the query
     *
     */
    readonly attribute nsIAbDirectoryQueryArguments contextArgs;

    /**
     * List of defined query results
     *
     */
    const long queryResultMatch     = 0;
    const long queryResultComplete     = 1;
    const long queryResultStopped     = 2;
    const long queryResultError     = 3;

    /**
     * The type of result
     *
     * Identifies a query entry, the query has finished
     * or that an error has occured
     */
    readonly attribute long type;

    /**
     * The result of a singular match for a card
     *
     * Only valid when the attribute type is
     * of 'query match'
     *
     * nsISupportsArray<nsIAbDirectoryQueryPropertyValue>
     *        Multiple entries corresponding to card
     *        properties
     * nsISupportsArray<nsIAbCard>
     *        Only one entry makese sense
     * 
     */
    readonly attribute nsISupportsArray result;

    /**
     * result attribute defined explicitly as an
     * array of nsISupport interfaces
     *
     */
    void agetResult (out unsigned long aResultSize,
        [retval, array, size_is(aResultSize)]
        out nsISupports aResultArray);
};

[scriptable, uuid(4290E508-1DD2-11B2-AC3E-9597BBCB25D7)]
interface nsIAbDirectoryQueryResultListener : nsISupports
{
    /**
     * Called when a match is found. May be
     * called from a different thread to the
     * one that initiates the query
     *
     * @param result
     *        A individual result associated returned
     *        from a query
     */
    void onQueryItem (in nsIAbDirectoryQueryResult result);
};

[scriptable, uuid(4241C46E-1DD2-11B2-978D-A2FBD0A72AC2)]
interface nsIAbDirectoryQuery : nsISupports
{
    /**
     * Initiates a query on a directory and 
     * sub-directories for properties on cards
     *
     * @param arguments
     *        The properties and values to match
     *        Value could of type nsIAbDirectoryQueryMatchItem
     *        for matches other than ?contains?
     * @param listener
     *        The listener which will obtain individual
     *        query results
     * @param resultLimit
     *        Limits the results returned to a specified
     *        maximum value
     * @return
     *        Unique number representing the context ID of
     *        the query
     *
     */
    long doQuery (in nsIAbDirectoryQueryArguments arguments,
        in nsIAbDirectoryQueryResultListener listener,
        in long resultLimit,
        in long timeOut);

    /**
     * Stops an existing query operation if
     * query operation is asynchronous
     *
     * The nsIAbDirectoryQueryResultListener will
     * be notified when query has stopped
     *
     * It is implementation specific if notification
     * synchronous or asynchronous
     *
     * @param contextID
     *        The unique number returned from
     *        the doQuery methods
     *
     */
    void stopQuery (in long contextID);
};