Issue #1258 - Part 1: Import mailnews, ldap, and mork from comm-esr52.9.1

mailnews/addrbook/public/nsIAbDirectoryQuery.idl

@@ -0,0 +1,164 @@
+/* -*- 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"
+
+interface nsIAbDirSearchListener;
+interface nsIAbCard;
+interface nsIAbDirectory;
+
+/**
+ * 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(03af3018-2590-4f4c-a88c-1fff6595ef05)]
+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;
+
+    /** 
+     * A parameter which can be used to pass in data specific to a particular
+     * type of addressbook.  
+     */
+    attribute nsISupports typeSpecificArg;
+
+    /**
+     * A custom search filter which user wants to use in LDAP query.
+     */
+    attribute AUTF8String filter;
+};
+
+
+[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(516e7ffa-69bc-41db-a493-dfb4895832f3)]
+interface nsIAbDirectoryQueryResultListener : nsISupports
+{
+    /**
+     * Called when a match is found. May be called from a different thread to
+     * the one that initiates the query.
+     *
+     * @param aCard An individual result associated returned from a query
+     */
+    void onQueryFoundCard(in nsIAbCard aCard);
+
+    /**
+     * List of defined query results
+     *
+     */
+    const long queryResultMatch    = 0;
+    const long queryResultComplete = 1;
+    const long queryResultStopped  = 2;
+    const long queryResultError    = 3;
+
+    /**
+     * Called when a query has finished. May be called from a different thread
+     * to the one that initiates the query.
+     *
+     * @param aResult    A result code from the list above.
+     *
+     * @param aErrorCode An error code specific to the type of query.
+     */
+    void onQueryResult(in long aResult, in long aErrorCode);
+};
+
+[scriptable, uuid(60b5961c-ce61-47b3-aa99-6d865f734dee)]
+interface nsIAbDirectoryQuery : nsISupports
+{
+    /**
+     * Initiates a query on a directory and sub-directories for properties
+     * on cards
+     *
+     * @param aDirectory   A directory that the query may get extra details
+     *                     from.
+     *
+     * @param aArguments   The properties and values to match value could of
+     *                     type nsIAbDirectoryQueryMatchItem for matches other
+     *                     than ?contains?
+     *
+     * @param aListener    The listener which will obtain individual query
+     *                     results.
+     *
+     * @param aResultLimit Limits the number of results returned to a maximum
+     *                     value.
+     *
+     * @param aTimeOut     The maximum length of time for the query
+     *
+     * @return             A context id for the query
+     */
+    long doQuery(in nsIAbDirectory aDirectory,
+                 in nsIAbDirectoryQueryArguments aArguments,
+                 in nsIAbDirSearchListener aListener,
+                 in long aResultLimit,
+                 in long aTimeOut);
+
+    /**
+     * 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);
+};