The contacts Filter API provides the set of definitions and interfaces that enable application developers to make filters to set query.

Required Header

#include <contacts.h>

Functions
int	contacts_filter_create (const char view_uri, contacts_filter_h filter)
	Creates a filter.
int	contacts_filter_destroy (contacts_filter_h filter)
	Destroys a filter.
int	contacts_filter_add_str (contacts_filter_h filter, unsigned int property_id, contacts_match_str_flag_e match, const char *match_value)
	Adds a condition for a string type property.
int	contacts_filter_add_int (contacts_filter_h filter, unsigned int property_id, contacts_match_int_flag_e match, int match_value)
	Adds a condition for an integer type property.
int	contacts_filter_add_lli (contacts_filter_h filter, unsigned int property_id, contacts_match_int_flag_e match, long long int match_value)
	Adds a condition for a long int type property.
int	contacts_filter_add_double (contacts_filter_h filter, unsigned int property_id, contacts_match_int_flag_e match, double match_value)
	Adds a condition for a double type property.
int	contacts_filter_add_bool (contacts_filter_h filter, unsigned int property_id, bool match_value)
	Adds a condition for a boolean type property.
int	contacts_filter_add_operator (contacts_filter_h filter, contacts_filter_operator_e operator_type)
	Adds an operator between conditions.
int	contacts_filter_add_filter (contacts_filter_h parent_filter, contacts_filter_h child_filter)
	Adds a filter to a given filter.

Enumeration Type Documentation

enum contacts_filter_operator_e

Enumeration for Contacts filter operators.

Since :: 2.3

Enumerator:

CONTACTS_FILTER_OPERATOR_AND	AND
CONTACTS_FILTER_OPERATOR_OR	OR

enum contacts_match_int_flag_e

Enumeration for Contacts match int flags.

Since :: 2.3

Enumerator:

CONTACTS_MATCH_EQUAL	'='
CONTACTS_MATCH_GREATER_THAN	'>'
CONTACTS_MATCH_GREATER_THAN_OR_EQUAL	'>='
CONTACTS_MATCH_LESS_THAN	'<'
CONTACTS_MATCH_LESS_THAN_OR_EQUAL	'<='
CONTACTS_MATCH_NOT_EQUAL	'<>', this flag can yield poor performance
CONTACTS_MATCH_NONE	IS NULL

enum contacts_match_str_flag_e

Enumeration for Contacts match string flags.

Since :: 2.3

Enumerator:

CONTACTS_MATCH_EXACTLY	Full string, case-sensitive
CONTACTS_MATCH_FULLSTRING	Full string, case-insensitive
CONTACTS_MATCH_CONTAINS	Sub string, case-insensitive
CONTACTS_MATCH_STARTSWITH	Start with, case-insensitive
CONTACTS_MATCH_ENDSWITH	End with, case-insensitive
CONTACTS_MATCH_EXISTS	IS NOT NULL

Function Documentation

int contacts_filter_add_bool	(	contacts_filter_h	filter,
		unsigned int	property_id,
		bool	match_value
	)

Adds a condition for a boolean type property.

Since :: 2.3

Parameters:

[in]	filter	The filter handle
[in]	property_id	The property ID to add a condition
[in]	match_value	The match value

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_INVALID_PARAMETER	Invalid parameter
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	Internal system module error

See also:: contacts_filter_add_operator()

int contacts_filter_add_double	(	contacts_filter_h	filter,
		unsigned int	property_id,
		contacts_match_int_flag_e	match,
		double	match_value
	)

Adds a condition for a double type property.

Since :: 2.3

Parameters:

[in]	filter	The filter handle
[in]	property_id	The property ID to add a condition
[in]	match	The match flag
[in]	match_value	The match value

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_INVALID_PARAMETER	Invalid parameter
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	Internal system module error

See also:: contacts_filter_add_operator()

int contacts_filter_add_filter	(	contacts_filter_h	parent_filter,
		contacts_filter_h	child_filter
	)

Adds a filter to a given filter.

Since :: 2.3

Parameters:

[in]	parent_filter	The parent filter handle
[in]	child_filter	The child filter handle

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_INVALID_PARAMETER	Invalid parameter
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	Internal system module error

See also:: contacts_filter_add_operator()

int contacts_filter_add_int	(	contacts_filter_h	filter,
		unsigned int	property_id,
		contacts_match_int_flag_e	match,
		int	match_value
	)

Adds a condition for an integer type property.

Since :: 2.3

Parameters:

[in]	filter	The filter handle
[in]	property_id	The property ID to add a condition
[in]	match	The match flag
[in]	match_value	The match value

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_INVALID_PARAMETER	Invalid parameter
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	Internal system module error

See also:: contacts_filter_add_operator()

int contacts_filter_add_lli	(	contacts_filter_h	filter,
		unsigned int	property_id,
		contacts_match_int_flag_e	match,
		long long int	match_value
	)

Adds a condition for a long int type property.

Since :: 2.3

Parameters:

[in]	filter	The filter handle
[in]	property_id	The property ID to add a condition
[in]	match	The match flag
[in]	match_value	The match value

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_INVALID_PARAMETER	Invalid parameter
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	Internal system module error

See also:: contacts_filter_add_operator()

int contacts_filter_add_operator	(	contacts_filter_h	filter,
		contacts_filter_operator_e	operator_type
	)

Adds an operator between conditions.

Since :: 2.3

Parameters:

[in]	filter	The filter handle
[in]	operator_type	The operator type

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_INVALID_PARAMETER	Invalid parameter
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	Internal system module error

See also:: contacts_filter_add_str(); contacts_filter_add_int(); contacts_filter_add_bool()

int contacts_filter_add_str	(	contacts_filter_h	filter,
		unsigned int	property_id,
		contacts_match_str_flag_e	match,
		const char *	match_value
	)

Adds a condition for a string type property.

Since :: 2.3

Parameters:

[in]	filter	The filter handle
[in]	property_id	The property ID to add a condition
[in]	match	The match flag
[in]	match_value	The match value

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_INVALID_PARAMETER	Invalid parameter
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	Internal system module error

See also:: contacts_filter_add_operator()

int contacts_filter_create	(	const char *	view_uri,
		contacts_filter_h *	filter
	)

Creates a filter.

Since :: 2.3

Remarks:: You must release filter using contacts_filter_destroy().

Parameters:

[in]	view_uri	The view URI of a filter
[out]	filter	The filter handle

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_INVALID_PARAMETER	Invalid parameter
CONTACTS_ERROR_OUT_OF_MEMORY	Out of memory
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	Internal system module error

Precondition:: contacts_connect() should be called to initialize

See also:: contacts_filter_destroy()

int contacts_filter_destroy ( contacts_filter_h filter )

Destroys a filter.

Since :: 2.3

Parameters:

[in] filter The filter handle

Returns:: 0 on success, otherwise a negative error value

Return values:

CONTACTS_ERROR_NONE	Successful
CONTACTS_ERROR_INVALID_PARAMETER	Invalid parameter
CONTACTS_ERROR_NOT_SUPPORTED	Not supported
CONTACTS_ERROR_SYSTEM	Internal system module error

See also:: contacts_filter_create()

Required Header

Functions

Enumeration Type Documentation

Function Documentation