ContactSearchFilters

#include <bb/pim/contacts/ContactSearchFilters>

To link against this class, add the following line to your .pro file: LIBS += -lbbpim

The ContactSearchFilters class represents a set of filters that are used to search for specific contacts.

You can use this class to search for Contact objects. This class is designed to work with the various search functions in ContactService, such as ContactService::searchContacts(), ContactService::searchContactsByPhoneNumber(), and so on. You can specify search parameters such as sub-kind, attribute, and specific search fields, and you can sort the search results in different ways (for example, by column values, ascending, descending, and so on).

See:

ContactService

Since:

BlackBerry 10.0.0

Public Functions Index

ContactSearchFilters ()
~ContactSearchFilters ()
ContactSearchFilters (const ContactSearchFilters &copy)
ContactSearchFilters &operator= (const ContactSearchFilters &operand)
ContactSearchFilters &setLimit (int limit)
ContactSearchFilters &setOffset (int offset)
ContactSearchFilters &setHasKindSubkind (const KindSubKindSpecifier present)
ContactSearchFilters &setHasKindSubkind (const QSet< KindSubKindSpecifier > &present)
ContactSearchFilters &setIsFavourite (bool value)
boolisVideoChatContact () const
ContactSearchFilters &setIsVideoChatContact (bool isVideoChatContact)
ContactSearchFilters &setHasAttribute (AttributeKind::Type present)
ContactSearchFilters &setHasAttribute (const QSet< AttributeKind::Type > &present)
ContactSearchFilters &setAnchorId (ContactId contactId, bool inclusive=false)
ContactSearchFilters &setSortBy (SortColumn::Type column, SortOrder::Type order)
ContactSearchFilters &setSortBy (const SortSpecifier &sort)
ContactSearchFilters &setSortBy (const QList< SortSpecifier > &sorts)
ContactSearchFilters &setSortAndAnchorBy (const AnchorValueSpecifier &anchorValue)
ContactSearchFilters &setSortAndAnchorBy (const QList< AnchorValueSpecifier > &anchorValues)
ContactSearchFilters &setHasAccount (AccountId accountId)
ContactSearchFilters &setHasAccounts (const QList< AccountId > &accountId)
ContactSearchFilters &setExcludeAccount (AccountId accountId)
ContactSearchFilters &setExcludeAccounts (const QList< AccountId > &accountId)
ContactSearchFilters &setExcludeAccount (AccountId accountId, bool includeMergedContacts)
ContactSearchFilters &setExcludeAccounts (const QList< AccountId > &accountId, bool includeMergedContacts)
ContactSearchFilters &setIncludePhotos (bool value)
ContactSearchFilters &setIncludeAttribute (AttributeKind::Type kind)
ContactSearchFilters &setIncludeAttributes (QList< AttributeKind::Type > kinds)
ContactSearchFilters &setSearchValue (const QString &value)
ContactSearchFilters &setShowAttributes (bool value)
ContactSearchFilters &setShowSources (bool value)
ContactSearchFilters &setSearchFields (const QList< SearchField::Type > &fields)

Public Functions

ContactSearchFilters ()

Constructs a new ContactSearchFilters.

Since:

BlackBerry 10.0.0

~ContactSearchFilters ()

Destructor.

Since:

BlackBerry 10.0.0

ContactSearchFilters (

Copy constructor.

This function constructs a ContactSearchFilters containing exactly the same values as the provided ContactSearchFilters.

Parameters
copy

The ContactSearchFilters to be copied.
Since:

BlackBerry 10.0.0

ContactSearchFilters & operator= (

Assignment operator.

This operator copies all values from the provided ContactSearchFilters into this ContactSearchFilters.

Parameters
operand

The ContactSearchFilters from which to copy all values.
Return:

A ContactSearchFilters with all copied data

Since:

BlackBerry 10.0.0

ContactSearchFilters & setLimit (
  • intlimit)

Sets the result limit of this ContactSearchFilters.

This value represents the maximum number of results that are returned from the search.

Parameters
limit

The maximum number of results that are returned.
Return:

A ContactSearchFilters with the provided result limit.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setOffset (
  • intoffset)

Set offset to start query of this ContactListFilters.

@ details This value represents the place to start query from

Parameters
offset

The offset number to start searching from
Return:

A ContactListFilters with the provided offset

Since:

BlackBerry 10.0.0

ContactSearchFilters & setHasKindSubkind (

Filters the search results to contain only contacts with the provided kind/sub-kind combination.

Parameters
present

The kind/sub-kind combination to filter based on.
Return:

A ContactSearchFilters with the provided kind/sub-kind combination filter.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setHasKindSubkind (

Filters the search results to contain only contacts with the provided set of kind/sub-kind combinations.

Parameters
present

The set of kind/sub-kind combinations to filter based on.
Return:

A ContactSearchFilters with the provided kind/sub-kind combination filter.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setIsFavourite (
  • boolvalue)

Sets whether only favorite contacts are returned when using this ContactSearchFilters.

Parameters
value

If true only favorite contacts are returned, if false all contacts are returned.
Return:

A ContactSearchFilters with the provided indication of whether favorite contacts are returned.

Since:

BlackBerry 10.0.0

bool isVideoChatContact ()

Indicates whether only video chat contacts are returned when using this ContactListFilters.

Return:

true if only video chat contacts are returned, false otherwise.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setIsVideoChatContact (
  • boolisVideoChatContact)

Sets whether only video chat contacts are returned when using this ContactListFilters.

Parameters
isVideoChatContact

If true only video chat contacts are returned, if false all contacts are returned.
Return:

A ContactListFilters with the provided indication of whether video chat contacts are returned.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setHasAttribute (

Filters the search results to contain only contacts with the provided attribute kind.

Parameters
present

The attribute kind to filter based on.
Return:

A ContactSearchFilters with the provided attribute kind filter.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setHasAttribute (

Filters the search results to contain only contacts with the provided set of attribute kinds.

Parameters
present

The set of attribute kinds to filter based on.
Return:

A ContactSearchFilters with the provided attribute kind filter.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setAnchorId (
  • ContactIdcontactId,
  • boolinclusive )

Sets the anchor ID and indicates how paging works in the search results.

This function sets the anchor ID to the provided contact ID. If paging is set to inclusive (that is, the inclusive parameter is true), the contact with the specified contact ID is returned as the first contact. Otherwise, the first contact that's returned is the next logical contact in the results.

Parameters
contactId

The contact ID to set as the anchor ID.

inclusive

If true the contact with the specified contact ID is returned as the first contact in the results, if false the contact after the one with the specified contact ID is returned as the first contact.
Return:

A ContactSearchFilters with the provided anchor ID and paging behavior.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setSortBy (

Sets the sort column and sort order of this ContactSearchFilters.

The default sort column is FirstName and the default sort order is ascending.

Parameters
column

The sort column to set.

order

The sort order to set.
Return:

A ContactSearchFilters with the provided sort column and sort order.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setSortBy (

Sets the sort column and sort order of this ContactSearchFilters using a SortSpecifier.

The default sort column is FirstName and the default sort order is ascending.

Parameters
sort

The sort column and sort order pair to set, represented by a SortSpecifier.
Return:

A ContactSearchFilters with the provided sort column and sort order.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setSortBy (

Sets the sort columns and sort orders of this ContactSearchFilters using a list of SortSpecifier objects.

The default sort column is FirstName and the default sort order is ascending. The search results are first sorted according to the first SortSpecifier in the provided list, then by the second SortSpecifier in the list, and so on.

Parameters
sorts

The set of sort column and sort order pairs to set, represented by SortSpecifier objects.
Return:

A ContactSearchFilters with the provided sort columns and sort orders.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setSortAndAnchorBy (

Sets the sort column, sort order, and anchor value of this ContactSearchFilters using an AnchorValueSpecifier.

This function specifies a sort column and order, and offsets the response by a certain anchor value. When anchoring by value, contacts matching the values are included in the response.

Parameters
anchorValue

The sort column, sort order, and anchor value to set, represented by a AnchorValueSpecifier object.
Return:

A ContactSearchFilters with the provided sort column, sort order, and anchor value.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setSortAndAnchorBy (

Sets the sort columns, sort orders, and anchor values of this ContactSearchFilters using a list of AnchorValueSpecifier objects.

This function specifies a set of sort columns and orders, and offsets the response by anchor values. When anchoring by value, contacts matching the values are included in the response.

Parameters
anchorValues

The set of sort columns, sort orders, and anchor values to set, represented by AnchorValueSpecifier objects.
Return:

A ContactSearchFilters with the provided sort columns, sort orders, and anchor values.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setHasAccount (
  • AccountIdaccountId)

Filters the search results to contain only contacts where the source of the contact comes from the provided account ID.

Parameters
accountId

The account ID to filter based on.
Return:

A ContactSearchFilters with the provided account ID filter.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setHasAccounts (
  • const QList< AccountId > &accountId)

Filters the search results to contain only contacts where the sources of the contact come from any of the provided account IDs.

Parameters
accountId

The set of account IDs to filter based on.
Return:

A ContactSearchFilters with the provided account ID filter.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setExcludeAccount (
  • AccountIdaccountId)

Filters the search results to contain only contacts where the source of the contact doesn't come from the provided account ID.

Parameters
accountId

The account ID to filter based on.
Return:

A ContactSearchFilters with the provided account ID filter.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setExcludeAccounts (
  • const QList< AccountId > &accountId)

Filters the search results to contain only contacts where the sources of the contact don't come from any of the provided account IDs.

Parameters
accountId

The set of account IDs to filter based on.
Return:

A ContactSearchFilters with the provided account ID filter.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setExcludeAccount (
  • AccountIdaccountId,
  • boolincludeMergedContacts )

Filters the search results to contain only contacts where the source of the contact doesn't come from the provided account ID.

Parameters
accountId

The set of account ID to filter based on.

includeMergedContacts

determines whether contacts that belong to more than one account should be included in the result if one of the source accounts is not excluded.
Return:

A ContactSearchFilters with the provided account ID filter.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setExcludeAccounts (
  • const QList< AccountId > &accountId,
  • boolincludeMergedContacts )

Filters the search results to contain only contacts where the sources of the contact don't come from any of the provided account IDs.

Parameters
accountId

The set of account IDs to filter based on.

includeMergedContacts

determines whether contacts that belong to more than one account should be included in the result if one of the source accounts is not excluded.
Return:

A ContactSearchFilters with the provided account ID filter.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setIncludePhotos (
  • boolvalue)

Sets whether to include photos in the search results.

If set to true, the primary photos that are associated with the contacts are returned. The default value is false.

Parameters
value

If true photos are included in the search results, if false photos are not included in the search results.
Return:

A ContactSearchFilters with the provided indication of whether to include photos in the search results.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setIncludeAttribute (

Filters the search results to contain only contacts with the provided attribute kind.

This function is mutually exclusive with setIncludeAttributes().

Parameters
kind

The attribute kind to filter based on.
Return:

A ContactSearchFilters with the provided attribute kind filter.

See:

setIncludeAttributes()

Since:

BlackBerry 10.0.0

ContactSearchFilters & setIncludeAttributes (

Filters the search results to contain only contacts with the provided attribute kinds.

This function is mutually exclusive with setIncludeAttribute().

Parameters
kinds

The set of attribute kinds to filter based on.
Return:

A ContactSearchFilter with the provided attribute kinds filter.

See:

setIncludeAttribute()

Since:

BlackBerry 10.0.0

ContactSearchFilters & setSearchValue (

Sets the search value of this ContactSearchFilters.

This value represents the string to search for in the list of contacts. This is a required field.

Parameters
value

The search value to set.
Return:

A ContactSearchFilters with the provided search value.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setShowAttributes (
  • boolvalue)

Sets whether to include attributes in the search results.

If set to true, attributes are returned in the search results. If set to true along with along with setHasAttribute, then only the matching attributes are returned. You should use this function with care, because retrieving a large amount of data in any response will be slow.

Parameters
value

If true attributes are included in the search results, if false attributes are not included in the search results.
Return:

A ContactSearchFilters with the provided indication of whether to include attributes in the search results.

Since:

BlackBerry 10.0.0

ContactSearchFilters & setShowSources (
  • boolvalue)

Sets whether to include account IDs for content sources in the search results.

If set to true, contacts that are returned include a list of account IDs that are the sources of content for the contacts.

Parameters
value

If true account IDs are included in the search results, if false account IDs are not included in the search results.
Return:

A ContactSearchFilters with the the provided indication of whether to include source accounts list

Since:

BlackBerry 10.0.0

ContactSearchFilters & setSearchFields (

Sets the search fields of this ContactSearchFilters.

This function sets the search fields that the search applies to. These fields are searched for the value that's set using setSearchValue().

The default search fields are first name, last name, company name, phone, and email.

Parameters
fields

The search fields to set.
Return:

A ContactSearchFilters with the specified search fields.

Since:

BlackBerry 10.0.0