1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is mozilla.org code.
16 *
17 * The Initial Developer of the Original Code is
18 * Sun Microsystems, Inc.
19 * Portions created by the Initial Developer are Copyright (C) 2001
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 * Created by: Paul Sandoz <paul.sandoz@sun.com>
24 * Dan Mosedale <dan.mosedale@oracle.com>
25 *
26 * Alternatively, the contents of this file may be used under the terms of
27 * either of the GNU General Public License Version 2 or later (the "GPL"),
28 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
29 * in which case the provisions of the GPL or the LGPL are applicable instead
30 * of those above. If you wish to allow use of your version of this file only
31 * under the terms of either the GPL or the LGPL, and not to allow others to
32 * use your version of this file under the terms of the MPL, indicate your
33 * decision by deleting the provisions above and replace them with the notice
34 * and other provisions required by the GPL or the LGPL. If you do not delete
35 * the provisions above, a recipient may use your version of this file under
36 * the terms of any one of the MPL, the GPL or the LGPL.
37 *
38 * ***** END LICENSE BLOCK ***** */
39
40
41 #include "nsISupports.idl"
42
43 interface nsIAbDirSearchListener;
44 interface nsIAbCard;
45 interface nsIAbDirectory;
46
47 /**
48 * The arguments for a query.
49 *
50 * Contains an expression for perform matches
51 * and an array of properties which should be
52 * returned if a match is found from the expression
53 *
54 */
55 [scriptable, uuid(c2d83a31-eba6-4053-9273-c7a006a94311)]
56 interface nsIAbDirectoryQueryArguments : nsISupports
57 {
58 /**
59 * Defines the boolean expression for
60 * the matching of cards
61 *
62 */
63 attribute nsISupports expression;
64
65 /**
66 * Defines if sub directories should be
67 * queried
68 *
69 */
70 attribute boolean querySubDirectories;
71
72 /**
73 * A parameter which can be used to pass in data specific to a particular
74 * type of addressbook.
75 */
76 attribute nsISupports typeSpecificArg;
77 };
78
79
80 [scriptable, uuid(3A6E0C0C-1DD2-11B2-B23D-EA3A8CCB333C)]
81 interface nsIAbDirectoryQueryPropertyValue : nsISupports
82 {
83 /**
84 * The property which should be matched
85 *
86 * For example 'primaryEmail' or 'homePhone'
87 * for card properties.
88 *
89 * Two further properties are defined that
90 * do not exist as properties on a card.
91 *
92 * 'card:nsIAbCard' which represents the interface
93 * of a card component
94 *
95 */
96 readonly attribute string name;
97
98 /**
99 * The value of the property
100 *
101 */
102 readonly attribute wstring value;
103
104 /**
105 * The value of the property
106 * as an interface
107 *
108 * Only valid if the corresponding
109 * property name is related to an
110 * interface instead of a wstring
111 *
112 */
113 readonly attribute nsISupports valueISupports;
114 };
115
116 [scriptable, uuid(516e7ffa-69bc-41db-a493-dfb4895832f3)]
117 interface nsIAbDirectoryQueryResultListener : nsISupports
118 {
119 /**
120 * Called when a match is found. May be called from a different thread to
121 * the one that initiates the query.
122 *
123 * @param aCard An individual result associated returned from a query
124 */
125 void onQueryFoundCard(in nsIAbCard aCard);
126
127 /**
128 * List of defined query results
129 *
130 */
131 const long queryResultMatch = 0;
132 const long queryResultComplete = 1;
133 const long queryResultStopped = 2;
134 const long queryResultError = 3;
135
136 /**
137 * Called when a query has finished. May be called from a different thread
138 * to the one that initiates the query.
139 *
140 * @param aResult A result code from the list above.
141 *
142 * @param aErrorCode An error code specific to the type of query.
143 */
144 void onQueryResult(in long aResult, in long aErrorCode);
145 };
146
147 [scriptable, uuid(60b5961c-ce61-47b3-aa99-6d865f734dee)]
148 interface nsIAbDirectoryQuery : nsISupports
149 {
150 /**
151 * Initiates a query on a directory and sub-directories for properties
152 * on cards
153 *
154 * @param aDirectory A directory that the query may get extra details
155 * from.
156 *
157 * @param aArguments The properties and values to match value could of
158 * type nsIAbDirectoryQueryMatchItem for matches other
159 * than ?contains?
160 *
161 * @param aListener The listener which will obtain individual query
162 * results.
163 *
164 * @param aResultLimit Limits the number of results returned to a maximum
165 * value.
166 *
167 * @param aTimeOut The maximum length of time for the query
168 *
169 * @return A context id for the query
170 */
171 long doQuery(in nsIAbDirectory aDirectory,
172 in nsIAbDirectoryQueryArguments aArguments,
173 in nsIAbDirSearchListener aListener,
174 in long aResultLimit,
175 in long aTimeOut);
176
177 /**
178 * Stops an existing query operation if
179 * query operation is asynchronous
180 *
181 * The nsIAbDirectoryQueryResultListener will
182 * be notified when query has stopped
183 *
184 * It is implementation specific if notification
185 * synchronous or asynchronous
186 *
187 * @param contextID
188 * The unique number returned from
189 * the doQuery methods
190 *
191 */
192 void stopQuery (in long contextID);
193 };