Akonadi Contacts

contactgroupsearchjob.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/Item>
14 #include <Akonadi/ItemSearchJob>
15 #include <KContacts/ContactGroup>
16 
17 #include <memory>
18 
19 namespace Akonadi
20 {
21 class ContactGroupSearchJobPrivate;
22 
23 /**
24  * @short Job that searches for contact groups in the Akonadi storage.
25  *
26  * This job searches for contact groups that match given search criteria and returns
27  * the list of contact groups.
28  *
29  * @code
30  *
31  * Akonadi::ContactGroupSearchJob *job = new Akonadi::ContactGroupSearchJob();
32  * job->setQuery( Akonadi::ContactGroupSearchJob::Name, "Family Members" );
33  * connect( job, SIGNAL(result(KJob*)), this, SLOT(searchResult(KJob*)) );
34  *
35  * ...
36  *
37  * MyClass::searchResult( KJob *job )
38  * {
39  * Akonadi::ContactGroupSearchJob *searchJob = qobject_cast<Akonadi::ContactGroupSearchJob*>( job );
40  * const KContacts::ContactGroup::List contactGroups = searchJob->contactGroups();
41  * // do something with the contact groups
42  * }
43  *
44  * @endcode
45  *
46  * @author Tobias Koenig <[email protected]>
47  * @since 4.4
48  */
49 class AKONADI_CONTACT_EXPORT ContactGroupSearchJob : public ItemSearchJob
50 {
51  Q_OBJECT
52 
53 public:
54  /**
55  * Creates a new contact group search job.
56  *
57  * @param parent The parent object.
58  */
59  explicit ContactGroupSearchJob(QObject *parent = nullptr);
60 
61  /**
62  * Destroys the contact group search job.
63  */
64  ~ContactGroupSearchJob() override;
65 
66  /**
67  * Describes the criteria that can be searched for.
68  */
69  enum Criterion {
70  Name ///< The name of the contact group.
71  };
72 
73  /**
74  * Describes the type of pattern matching that shall be used.
75  *
76  * @since 4.5
77  */
78  enum Match {
79  ExactMatch, ///< The result must match exactly the pattern (case sensitive).
80  StartsWithMatch, ///< The result must start with the pattern (case insensitive).
81  ContainsMatch ///< The result must contain the pattern (case insensitive).
82  };
83 
84  /**
85  * Sets the @p criterion and @p value for the search.
86  */
87  void setQuery(Criterion criterion, const QString &value);
88 
89  /**
90  * Sets the @p criterion and @p value for the search with @p match.
91  * @param criterion the query criterion to compare with
92  * @param value the value to match against
93  * @param match how to match the given value
94  * @since 4.5
95  */
96  void setQuery(Criterion criterion, const QString &value, Match match);
97 
98  /**
99  * Sets a @p limit on how many results will be returned by this search job.
100  * This is useful in situation where for example only the first search result is needed anyway,
101  * setting a limit of 1 here will greatly reduce the resource usage during the
102  * search.
103  * @param limit the limit to set
104  * @note this needs to be called before calling setQuery() to have an effect.
105  * By default, the number of results is unlimited.
106  *
107  * @since 4.4.3
108  */
109  void setLimit(int limit);
110 
111  /**
112  * Returns the contact groups that matched the search criteria.
113  */
114  Q_REQUIRED_RESULT KContacts::ContactGroup::List contactGroups() const;
115 
116 private:
117  //@cond PRIVATE
118  std::unique_ptr<ContactGroupSearchJobPrivate> const d;
119  //@endcond
120 };
121 }
Match
Describes the type of pattern matching that shall be used.
@ StartsWithMatch
The result must start with the pattern (case insensitive).
@ ExactMatch
The result must match exactly the pattern (case sensitive).
Job that searches for contact groups in the Akonadi storage.
Criterion
Describes the criteria that can be searched for.
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.