diff options
Diffstat (limited to 'include/contacts_search.h')
| -rwxr-xr-x | include/contacts_search.h | 238 |
1 files changed, 198 insertions, 40 deletions
diff --git a/include/contacts_search.h b/include/contacts_search.h index d3fd03e..24d9708 100755 --- a/include/contacts_search.h +++ b/include/contacts_search.h @@ -45,8 +45,8 @@ extern "C" * @pre This function requires an open connection to contacts service by contacts_connect(). * @post This function invokes contact_foreach_query_name_cb(). * - * @see 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); @@ -64,6 +64,7 @@ int contact_foreach_contact_from_db(contact_foreach_query_name_cb callback, void * @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); @@ -82,16 +83,15 @@ int contact_foreach_favorite_contact_from_db(contact_foreach_query_favorites_cb * @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() - * @see contacts_connect() */ 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 @@ -103,6 +103,7 @@ int contact_foreach_frequent_contact_from_db(contact_foreach_query_name_cb callb * * @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() * @@ -110,29 +111,10 @@ int contact_foreach_frequent_contact_from_db(contact_foreach_query_name_cb callb 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 group contacts database ID. - * - * @param[in] callback The callback function to invoke - * @param[out] group_db_id The group contacts 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_group(contact_foreach_query_name_cb callback, int group_db_id, void *user_data); - -/** * @brief Retrieves all contacts with the given address book database ID. * * @param[in] callback The callback function to invoke - * @param[out] address_book_db_id The address book database ID to filter + * @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. @@ -162,6 +144,7 @@ int contact_query_contact_by_address_book(contact_foreach_query_name_cb callback * * @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() * @@ -182,6 +165,7 @@ int contact_query_contact_by_number(contact_foreach_query_number_cb callback, co * * @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() */ @@ -194,7 +178,7 @@ int contact_query_contact_by_email(contact_foreach_query_email_cb callback, cons * * @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 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. @@ -232,10 +216,65 @@ int contact_query_contact_by_version(contact_foreach_query_version_cb callback, int contact_query_contact_not_related_to_group(contact_foreach_query_name_cb callback, int address_book_db_id, void *user_data); /** - * @brief Retrieves all contacts from all of address books with array + * @brief Frees contact array + * + * @param[out] contact_array The contact array * - * @remarks @a contact_array must be released with contact_query_name_array_free() by you. + * @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 * @@ -247,31 +286,41 @@ int contact_query_contact_not_related_to_group(contact_foreach_query_name_cb cal * * @pre This function requires an open connection to contacts service by contacts_connect(). * - * @see contact_query_name_array_free() * @see contacts_connect() + * @see contact_free_query_name_array() */ -int contact_get_all_contact_from_db(contact_query_name_array *contact_array, int *length); +int contact_search_contact_by_address_book(int address_book_db_id, pcontact_query_name_s **contact_array, int *length); /** - * @brief Frees contact array + * @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 * - * @see contact_get_all_contact_from_db() + * @pre This function requires an open connection to contacts service by contacts_connect(). + * + * @see contacts_connect() + * @see contact_free_query_number_array() */ -int contact_query_name_array_free(contact_query_name_array contact_array, int length); +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 number contacts from all of address books with array + * @brief Retrieves all phone numbers as array from all address books * - * @remarks @a contact_number_array must be released with contact_query_number_array_free() by you. + * @remarks @a contact_number_array must be released with contact_free_query_number_array() by you. * - * @param[out] contact_number_array The contact array + * @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. @@ -282,24 +331,133 @@ int contact_query_name_array_free(contact_query_name_array contact_array, int le * * @pre This function requires an open connection to contacts service by contacts_connect(). * - * @see contact_query_number_array_free() * @see contacts_connect() + * @see contact_free_query_number_array() */ -int contact_get_number_contact_from_db(contact_query_number_array *contact_number_array, int *length); +int contact_get_all_phone_number(pcontact_query_number_s **phone_number_array, int *length); /** - * @brief Frees contact number array + * @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 + * @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 contact_get_number_contact_from_db() + * @see contacts_connect() + * @see contact_free_query_version_array() */ -int contact_query_number_array_free(contact_query_number_array contact_number_array, int length); +int contact_search_contact_by_version(int address_book_db_id, int contacts_db_version, pcontact_query_version_s **contact_version_array, int *length); /** * @} |