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

KDE's Doxygen guidelines are available online.