pjs/mailnews/addrbook/public/nsIAbDirectoryQuery.idl

246 строки
7.1 KiB
Plaintext

/* -*- 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);
};