Akonadi Contacts

contactsearchjob.h
1/*
2 This file is part of Akonadi Contact.
3
4 SPDX-FileCopyrightText: 2009 Tobias Koenig <tokoe@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#pragma once
10
11#include "akonadi-contact-core_export.h"
12
13#include <Akonadi/ItemSearchJob>
14#include <KContacts/Addressee>
15
16#include <memory>
17
18namespace Akonadi
19{
20class 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 tokoe@kde.org
33 * Akonadi::ContactSearchJob *job = new Akonadi::ContactSearchJob();
34 * job->setQuery( Akonadi::ContactSearchJob::Email, "tokoe@kde.org" );
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 <tokoe@kde.org>
66 * @since 4.4
67 */
68class AKONADI_CONTACT_CORE_EXPORT ContactSearchJob : public ItemSearchJob
69{
70 Q_OBJECT
71
72public:
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 */
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 [[nodiscard]] KContacts::Addressee::List contacts() const;
133
134private:
135 //@cond PRIVATE
136 std::unique_ptr<ContactSearchJobPrivate> const d;
137 //@endcond
138};
139}
Job that searches for contacts in the Akonadi storage.
Match
Describes the type of pattern matching that shall be used.
@ ExactMatch
The result must match exactly the pattern (case sensitive).
@ StartsWithMatch
The result must start with the pattern (case insensitive).
@ ContainsMatch
The result must contain the pattern (case insensitive).
Criterion
Describes the criteria that can be searched for.
@ Name
The name of the contact.
@ NameOrEmail
The name or email address of the contact.
@ Email
The email address of the contact.
@ NickName
The nickname of the contact.
~ContactSearchJob() override
Destroys the contact search job.
AddresseeList List
A widget for editing the display name of a contact.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:38:21 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.