Akonadi Contacts

contactsearchjob.h
1 /*
2  This file is part of Akonadi Contact.
3 
4  SPDX-FileCopyrightText: 2009 Tobias Koenig <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #pragma once
10 
11 #include "akonadi-contact_export.h"
12 
13 #include <itemsearchjob.h>
14 #include <kcontacts/addressee.h>
15 
16 namespace Akonadi
17 {
18 /**
19  * @short Job that searches for contacts in the Akonadi storage.
20  *
21  * This job searches for contacts that match given search criteria and returns
22  * the list of contacts.
23  *
24  * Examples:
25  *
26  * @code
27  *
28  * // Search all contacts with email address [email protected]
29  * Akonadi::ContactSearchJob *job = new Akonadi::ContactSearchJob();
30  * job->setQuery( Akonadi::ContactSearchJob::Email, "[email protected]" );
31  * connect( job, SIGNAL(result(KJob*)), this, SLOT(searchResult(KJob*)) );
32  *
33  * ...
34  *
35  * MyClass::searchResult( KJob *job )
36  * {
37  * Akonadi::ContactSearchJob *searchJob = qobject_cast<Akonadi::ContactSearchJob*>( job );
38  * const KContacts::Addressee::List contacts = searchJob->contacts();
39  * // do something with the contacts
40  * }
41  *
42  * @endcode
43  *
44  * @code
45  *
46  * // Search for all existing contacts
47  * Akonadi::ContactSearchJob *job = new Akonadi::ContactSearchJob();
48  * connect( job, SIGNAL(result(KJob*)), this, SLOT(searchResult(KJob*)) );
49  *
50  * ...
51  *
52  * MyClass::searchResult( KJob *job )
53  * {
54  * Akonadi::ContactSearchJob *searchJob = qobject_cast<Akonadi::ContactSearchJob*>( job );
55  * const KContacts::Addressee::List contacts = searchJob->contacts();
56  * // do something with the contacts
57  * }
58  *
59  * @endcode
60  *
61  * @author Tobias Koenig <[email protected]>
62  * @since 4.4
63  */
64 class AKONADI_CONTACT_EXPORT ContactSearchJob : public ItemSearchJob
65 {
66  Q_OBJECT
67 
68 public:
69  /**
70  * Creates a new contact search job.
71  *
72  * @param parent The parent object.
73  */
74  explicit ContactSearchJob(QObject *parent = nullptr);
75 
76  /**
77  * Destroys the contact search job.
78  */
80 
81  /**
82  * Describes the criteria that can be searched for.
83  */
84  enum Criterion {
85  Name, ///< The name of the contact.
86  Email, ///< The email address of the contact.
87  NickName, ///< The nickname of the contact.
88  NameOrEmail, ///< The name or email address of the contact. @since 4.5
89  ContactUid ///< The global unique identifier of the contact. @since 4.5
90  };
91 
92  /**
93  * Describes the type of pattern matching that shall be used.
94  *
95  * @since 4.5
96  */
97  enum Match {
98  ExactMatch, ///< The result must match exactly the pattern (case sensitive).
99  StartsWithMatch, ///< The result must start with the pattern (case insensitive).
100  ContainsMatch, ///< The result must contain the pattern (case insensitive).
101  ContainsWordBoundaryMatch ///< The result must contain a word starting with the pattern (case insensitive).
102  };
103 
104  /**
105  * Sets the @p criterion and @p value for the search with @p match.
106  * @param criterion the query criterion to compare with
107  * @param value the value to match against
108  * @param match how to match the given value
109  * @since 4.5
110  */
111  void setQuery(Criterion criterion, const QString &value, Match match = ExactMatch);
112 
113  /**
114  * Sets a @p limit on how many results will be returned by this search job.
115  *
116  * This is useful in situation where for example only the first search result is needed anyway,
117  * setting a limit of 1 here will greatly reduce the resource usage during the
118  * search.
119  * This needs to be called before calling setQuery() to have an effect.
120  * By default, the number of results is unlimited.
121  * @param limit the upper limit for number of search results
122  */
123  void setLimit(int limit);
124 
125  /**
126  * Returns the contacts that matched the search criteria.
127  */
128  Q_REQUIRED_RESULT KContacts::Addressee::List contacts() const;
129 
130 private:
131  //@cond PRIVATE
132  class Private;
133  Private *const d;
134  //@endcond
135 };
136 }
137 
Match
Describes the type of pattern matching that shall be used.
The result must contain the pattern (case insensitive).
The nickname of the contact.
The name or email address of the contact.
The result must start with the pattern (case insensitive).
Job that searches for contacts in the Akonadi storage.
The email address of the contact.
AddresseeList List
Criterion
Describes the criteria that can be searched for.
The name of the contact.
The result must match exactly the pattern (case sensitive).
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Jun 22 2021 23:08:52 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.