/* * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved * * Licensed under the Apache License, Version 2.0 (the License); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an AS IS BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #ifndef __TIZEN_SOCIAL_CONTACTS_SEARCH_H__ #define __TIZEN_SOCIAL_CONTACTS_SEARCH_H__ #include #ifdef __cplusplus extern "C" { #endif /** * @addtogroup CAPI_SOCIAL_CONTACTS_CONTACT_MODULE * @{ */ /** * @brief Retrieves all contacts from all of address books by invoking the given callback function * * @param[in] callback The callback function to invoke * @param[in] user_data The user data to be passed to the callback function * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * @post This function invokes contact_foreach_query_name_cb(). * * @see contacts_connect() * @see contact_foreach_query_name_cb() */ int contact_foreach_contact_from_db(contact_foreach_query_name_cb callback, void *user_data); /** * @brief Retrieves all favorite contacts by invoking the given callback function * * @param[in] callback The callback function to invoke * @param[in] user_data The user data to be passed to the callback function * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * @post This function invokes contact_foreach_query_favorites_cb(). * * @see contacts_connect() * @see contact_foreach_query_favorites_cb() */ int contact_foreach_favorite_contact_from_db(contact_foreach_query_favorites_cb callback, void *user_data); /** * @brief Retrieves most frequent contacts by invoking the given callback function * * @param[in] callback The callback function to invoke * @param[in] user_data The user data to be passed to the callback function * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * @post This function invokes contact_foreach_query_name_cb(). * * @see contacts_connect() * @see contact_foreach_query_name_cb() * @see contact_unset_frequent_contact() */ int contact_foreach_frequent_contact_from_db(contact_foreach_query_name_cb callback, void *user_data); /** * @brief Retrieves all contacts with the given name. * * @param[in] callback The callback function to invoke * @param[in] name_to_find The name for search * @param[in] user_data The user data to be passed to the callback function * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * @post This function invokes contact_foreach_query_name_cb(). * * @see contacts_connect() * @see contact_foreach_query_name_cb() * */ int contact_query_contact_by_name(contact_foreach_query_name_cb callback, const char *name_to_find, void *user_data); /** * @brief Retrieves all contacts with the given address book database ID. * * @param[in] callback The callback function to invoke * @param[in] address_book_db_id The address book database ID to filter * @param[in] user_data The user data to be passed to the callback function * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * @pre This function requires an open connection to contacts service by contacts_connect(). * @post This function invokes contact_foreach_query_name_cb(). * * @see contacts_connect() * @see contact_foreach_query_name_cb() */ int contact_query_contact_by_address_book(contact_foreach_query_name_cb callback, int address_book_db_id, void *user_data); /** * @brief Retrieves all contacts with the given number. * * * @param[in] callback The callback function to invoke * @param[in] number_to_find The number to filter * @param[in] user_data The user data to be passed to the callback function * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * @post This function invokes contact_foreach_query_number_cb(). * * @see contacts_connect() * @see contact_foreach_query_number_cb() * */ int contact_query_contact_by_number(contact_foreach_query_number_cb callback, const char *number_to_find, void *user_data); /** * @brief Retrieves all contacts with the given email address. * * @param[in] callback The callback function to invoke * @param[in] email_to_find The email address to filter * @param[in] user_data The user data to be passed to the callback function * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to Contacts Service by contacts_connect() * @post This function invokes contact_foreach_query_email_cb(). * * @see contacts_connect() * @see contact_foreach_query_email_cb() */ int contact_query_contact_by_email(contact_foreach_query_email_cb callback, const char *email_to_find, void *user_data); /** * @brief Retrieves all contacts with the contacts database version. * * @details This function will find all changed contacts since the given @a contacts_db_version * * @param[in] callback The callback function to invoke * @param[in] address_book_db_id The address book database ID to filter * @param[in] contacts_db_version The contacts database version * @param[in] user_data The user data to be passed to the callback function * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * @post This function invokes contact_foreach_query_version_cb() * * @see contacts_connect() * @see contact_foreach_query_version_cb() * @see contacts_get_db_version() */ int contact_query_contact_by_version(contact_foreach_query_version_cb callback, int address_book_db_id, int contacts_db_version, void *user_data); /** * @brief Retrieves all contacts which are not related to any group in the given address book database ID * * @param[in] callback The callback function to invoke * @param[in] address_book_db_id The address book database ID to filter * @param[in] user_data The user data to be passed to the callback function * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to Contacts Service by contacts_connect() * @post This function invokes contact_foreach_query_name_cb(). * * @see contacts_connect() * @see contact_foreach_query_name_cb() */ int contact_query_contact_not_related_to_group(contact_foreach_query_name_cb callback, int address_book_db_id, void *user_data); /** * @brief Frees contact array * * @param[out] contact_array The contact array * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * * @see contact_search_contact_by_address_book() */ int contact_free_query_name_array(pcontact_query_name_s* contact_array); /** * @brief Frees contact number array * * @param[out] contact_number_array The contact array * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * * @see contact_search_contact_has_number() */ int contact_free_query_number_array(pcontact_query_number_s *contact_number_array); /** * @brief Frees contact email array * * @param[out] contact_email_array The contact array * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * * @see contact_search_contact_by_email() */ int contact_free_query_email_array(pcontact_query_email_s *contact_email_array); /** * @brief Frees contact version array * * @param[out] contact_version_array The contact array * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * * @see contact_search_contact_by_version() */ int contact_free_query_version_array(pcontact_query_version_s *contact_version_array); /** * @brief Retrieves all contacts as array from address book * * @remarks @a contact_array must be released with contact_free_query_name_array() by you. * * @param[in] address_book_db_id The address book database ID to filter \n * #DEFAULT_ADDRESS_BOOK_DB_ID means the default address book on the device \n * #ADDRESS_BOOK_FILTER_ALL means all address books on the device * @param[out] contact_array The contact array * @param[out] length The length of the contact array * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * * @see contacts_connect() * @see contact_free_query_name_array() */ int contact_search_contact_by_address_book(int address_book_db_id, pcontact_query_name_s **contact_array, int *length); /** * @brief Retrieves all contacts with default phone number as array from address book * * @remarks @a contact_array must be released with contact_free_query_name_array() by you. * * @param[in] address_book_db_id The address book database ID to filter \n * #DEFAULT_ADDRESS_BOOK_DB_ID means the default address book on the device \n * #ADDRESS_BOOK_FILTER_ALL means all address books on the device * @param[out] contact_array The contact array * @param[out] length The length of the contact array * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * * @see contacts_connect() * @see contact_free_query_number_array() */ int contact_search_contact_with_default_number_by_address_book(int address_book_db_id, pcontact_query_number_s **contact_array, int *length); /** * @brief Retrieves all phone numbers as array from all address books * * @remarks @a contact_number_array must be released with contact_free_query_number_array() by you. * * @param[out] phone_number_array The contact array * @param[out] length The length of the contact array * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * * @see contacts_connect() * @see contact_free_query_number_array() */ int contact_get_all_phone_number(pcontact_query_number_s **phone_number_array, int *length); /** * @brief Retrieves all contacts as array with the given email address. * * @remarks @a contact_email_array must be released with contact_free_query_email_array() by you. * * @param[in] address_book_db_id The address book database ID to filter \n * #DEFAULT_ADDRESS_BOOK_DB_ID means the default address book on the device \n * #ADDRESS_BOOK_FILTER_ALL means all address books on the device * @param[in] email_to_find The email address to filter * @param[out] contact_email_array The contact array * @param[out] length The length of the contact array * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * * @see contacts_connect() * @see contact_free_query_email_array() */ int contact_search_contact_by_email(int address_book_db_id, const char *email_to_find, pcontact_query_email_s **contact_email_array, int *length); /** * @brief Retrieves all contacts as array with the given number. * * @remarks @a contact_number_array must be released with contact_free_query_number_array() by you. * * @param[in] address_book_db_id The address book database ID to filter \n * #DEFAULT_ADDRESS_BOOK_DB_ID means the default address book on the device \n * #ADDRESS_BOOK_FILTER_ALL means all address books on the device * @param[in] number_to_find The number to filter * @param[out] contact_number_array The contact array * @param[out] length The length of the contact array * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * * @see contacts_connect() * @see contact_free_query_number_array() */ int contact_search_contact_by_number(int address_book_db_id, const char *number_to_find, pcontact_query_number_s **contact_number_array, int *length); /** * @brief Retrieves all contacts as array with the given name. * * @remarks @a contact_name_array must be released with contact_free_query_name_array() by you. * * @param[in] address_book_db_id The address book database ID to filter \n * #DEFAULT_ADDRESS_BOOK_DB_ID means the default address book on the device \n * #ADDRESS_BOOK_FILTER_ALL means all address books on the device * @param[in] name_to_find The name to filter * @param[out] contact_name_array The contact array * @param[out] length The length of the contact array * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * * @see contacts_connect() * @see contact_free_query_name_array() */ int contact_search_contact_by_name(int address_book_db_id, const char *name_to_find, pcontact_query_name_s **contact_name_array, int *length); /** * @brief Retrieves all contacts as array with the given group database ID. * * @remarks @a contact_name_array must be released with contact_free_query_name_array() by you. * * @param[in] group_db_id The group contacts database ID to filter * @param[out] contact_name_array The contact array * @param[out] length The length of the contact array * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * * @see contacts_connect() * @see contact_free_query_name_array() */ int contact_search_contact_by_group(int group_db_id, pcontact_query_name_s **contact_name_array, int *length); /** * @brief Retrieves all contacts as array with the contacts database version. * * @details This function will find all changed contacts since the given @a contacts_db_version * @remarks @a contact_version_array must be released with contact_free_query_version_array() by you. * * @param[in] address_book_db_id The address book database ID to filter \n * #DEFAULT_ADDRESS_BOOK_DB_ID means the default address book on the device \n * #ADDRESS_BOOK_FILTER_ALL means all address books on the device * @param[in] contacts_db_version The contacts database version * @param[out] contact_version_array The contact array * @param[out] length The length of the contact array * * @return 0 on success, otherwise a negative error value. * @retval #CONTACTS_ERROR_NONE Successful * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter * @retval #CONTACTS_ERROR_DB_FAILED Database operation failure * * @pre This function requires an open connection to contacts service by contacts_connect(). * * @see contacts_connect() * @see contact_free_query_version_array() */ int contact_search_contact_by_version(int address_book_db_id, int contacts_db_version, pcontact_query_version_s **contact_version_array, int *length); /** * @} */ #ifdef __cplusplus } #endif #endif /* __TIZEN_SOCIAL_CONTACTS_SEARCH_H__ */