Tizen Native API  3.0

The contacts database API provides the set of definitions and interfaces that enable application developers to handle contacts database.

Required Header

#include <contacts.h>

Functions

int contacts_db_insert_record (contacts_record_h record, int *id)
 Inserts a record to the contacts database.
int contacts_db_get_record (const char *view_uri, int record_id, contacts_record_h *record)
 Gets a record from the contacts database.
int contacts_db_update_record (contacts_record_h record)
 Updates a record in the contacts database.
int contacts_db_delete_record (const char *view_uri, int record_id)
 Deletes a record from the contacts database with related child records.
int contacts_db_replace_record (contacts_record_h record, int id)
 Replaces an id-identified record with the given record.
int contacts_db_get_all_records (const char *view_uri, int offset, int limit, contacts_list_h *record_list)
 Retrieves all records and returns the results list.
int contacts_db_get_records_with_query (contacts_query_h query, int offset, int limit, contacts_list_h *record_list)
 Uses a query to find records.
int contacts_db_insert_records (contacts_list_h record_list, int **ids, int *count)
 Inserts multiple records to the contacts database.
int contacts_db_update_records (contacts_list_h record_list)
 Updates multiple records in the contacts database.
int contacts_db_delete_records (const char *view_uri, int record_id_array[], int count)
 Deletes multiple records in the contacts database with related child records.
int contacts_db_replace_records (contacts_list_h list, int record_id_array[], int count)
 Replaces database records identified by given ids with a given record list.
int contacts_db_get_current_version (int *contacts_db_version)
 Gets the current contacts database version.
int contacts_db_add_changed_cb (const char *view_uri, contacts_db_changed_cb callback, void *user_data)
 Registers a callback function to be invoked when a record changes.
int contacts_db_remove_changed_cb (const char *view_uri, contacts_db_changed_cb callback, void *user_data)
 Unregisters a callback function.
int contacts_db_get_changes_by_version (const char *view_uri, int address_book_id, int contacts_db_version, contacts_list_h *change_record_list, int *current_contacts_db_version)
 Retrieves records changes since the given database version.
int contacts_db_search_records (const char *view_uri, const char *keyword, int offset, int limit, contacts_list_h *record_list)
 Finds records based on a given keyword.
int contacts_db_search_records_with_query (contacts_query_h query, const char *keyword, int offset, int limit, contacts_list_h *record_list)
 Finds records based on given query and keyword.
int contacts_db_search_records_with_range (const char *view_uri, const char *keyword, int offset, int limit, int range, contacts_list_h *record_list)
 Finds records based on a keyword and range.
int contacts_db_search_records_for_snippet (const char *view_uri, const char *keyword, int offset, int limit, const char *start_match, const char *end_match, int token_number, contacts_list_h *record_list)
 Finds records based on a given keyword for snippet.
int contacts_db_search_records_with_query_for_snippet (contacts_query_h query, const char *keyword, int offset, int limit, const char *start_match, const char *end_match, int token_number, contacts_list_h *record_list)
 Finds records based on given query and keyword for snippet.
int contacts_db_search_records_with_range_for_snippet (const char *view_uri, const char *keyword, int offset, int limit, int range, const char *start_match, const char *end_match, int token_number, contacts_list_h *record_list)
 Finds records based on a keyword and range for snippet.
int contacts_db_get_count (const char *view_uri, int *count)
 Gets the number of records in a specific view.
int contacts_db_get_count_with_query (contacts_query_h query, int *count)
 Gets the number of records matching a query.
int contacts_db_get_last_change_version (int *last_change_version)
 Gets the last successful changed contacts database version on the current connection.
int contacts_db_get_status (contacts_db_status_e *status)
 Gets the current status of server.
int contacts_db_add_status_changed_cb (contacts_db_status_changed_cb callback, void *user_data)
 Registers a callback function.
int contacts_db_remove_status_changed_cb (contacts_db_status_changed_cb callback, void *user_data)
 Unregisters a callback function.

Typedefs

typedef void(* contacts_db_changed_cb )(const char *view_uri, void *user_data)
 Called when the designated view changes.
typedef void(* contacts_db_status_changed_cb )(contacts_db_status_e status, void *user_data)
 Called when contacts-service server status changes.

Typedef Documentation

typedef void(* contacts_db_changed_cb)(const char *view_uri, void *user_data)

Called when the designated view changes.

Since :
3.0
Parameters:
[in]view_uriThe view URI
[in]user_dataThe user data passed from the callback registration function
Precondition:
The callback must be registered using contacts_db_add_changed_cb.
See also:
contacts_db_add_changed_cb()
typedef void(* contacts_db_status_changed_cb)(contacts_db_status_e status, void *user_data)

Called when contacts-service server status changes.

Since :
3.0
Parameters:
[in]statusThe current status of server
[in]user_dataThe user data passed from the callback registration function
Precondition:
This function requires an open connection to contacts service by contacts_connect().
See also:
contacts_db_add_status_changed_cb()

Enumeration Type Documentation

Enumeration for contact change state.

Since :
3.0
Enumerator:
CONTACTS_CHANGE_INSERTED 

Inserted

CONTACTS_CHANGE_UPDATED 

Updated

CONTACTS_CHANGE_DELETED 

Deleted

Enumeration for contact DB status.

Since :
3.0
Enumerator:
CONTACTS_DB_STATUS_NORMAL 

Normal

CONTACTS_DB_STATUS_CHANGING_COLLATION 

DB status is Changing collation


Function Documentation

int contacts_db_add_changed_cb ( const char *  view_uri,
contacts_db_changed_cb  callback,
void *  user_data 
)

Registers a callback function to be invoked when a record changes.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Privilege:
http://tizen.org/privilege/callhistory.read
Remarks:
http://tizen.org/privilege/contact.read is needed for record which is related to _contacts_address_book view, _contacts_person view,
_contacts_contact view, _contacts_simple_contact view, _contacts_group view, _contacts_my_profile view,
_contacts_name view, _contacts_number view, _contacts_email view, _contacts_address view,
_contacts_note view, _contacts_url view, _contacts_event view, _contacts_image view,
_contacts_company view, _contacts_nickname view, _contacts_messenger view, _contacts_extension view,
_contacts_profile view, _contacts_relationship view, _contacts_activity view, _contacts_activity_photo view,
_contacts_speeddial view, _contacts_sdn view, _contacts_group_relation view.
http://tizen.org/privilege/callhistory.read is needed for record which is related to _contacts_phone_log view. If successive change notification produced on the view_uri are identical, then they are coalesced into a single notification if the older notification has not yet been called because default main loop is doing something. But, it means that a callback function is not called to reliably count of change.
Parameters:
[in]view_uriThe view URI of records whose changes are monitored
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_SYSTEMSystem error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
Postcondition:
contacts_db_changed_cb() will be invoked when the designated view changes.
See also:
contacts_connect()
contacts_db_changed_cb()
contacts_db_remove_changed_cb()
int contacts_db_add_status_changed_cb ( contacts_db_status_changed_cb  callback,
void *  user_data 
)

Registers a callback function.

Since :
3.0
Parameters:
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
This function requires an open connection to the contacts service by contacts_connect().
See also:
contacts_connect()
contacts_db_remove_status_changed_cb()
int contacts_db_delete_record ( const char *  view_uri,
int  record_id 
)

Deletes a record from the contacts database with related child records.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.write
Privilege:
http://tizen.org/privilege/callhistory.write
Remarks:
http://tizen.org/privilege/contact.write is needed for record which is related to _contacts_address_book view, _contacts_contact view,
_contacts_group view, _contacts_my_profile view, _contacts_name view, _contacts_number view,
_contacts_email view, _contacts_address view, _contacts_note view, _contacts_url view,
_contacts_event view, _contacts_image view, _contacts_company view, _contacts_nickname view,
_contacts_messenger view, _contacts_extension view, _contacts_profile view, _contacts_relationship view,
_contacts_activity view, _contacts_activity_photo view, _contacts_speeddial view.
http://tizen.org/privilege/callhistory.write is needed for record which is related to _contacts_phone_log view.
Parameters:
[in]view_uriThe view URI of a record
[in]record_idThe record ID to delete
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
Postcondition:
contacts_db_changed_cb() callback wil be called upon success.
See also:
contacts_connect()
contacts_db_insert_record()
int contacts_db_delete_records ( const char *  view_uri,
int  record_id_array[],
int  count 
)

Deletes multiple records in the contacts database with related child records.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.write
Privilege:
http://tizen.org/privilege/callhistory.write
Remarks:
http://tizen.org/privilege/contact.write is needed for record which is related to _contacts_address_book view, _contacts_contact view,
_contacts_group view, _contacts_my_profile view, _contacts_name view, _contacts_number view,
_contacts_email view, _contacts_address view, _contacts_note view, _contacts_url view,
_contacts_event view, _contacts_image view, _contacts_company view, _contacts_nickname view,
_contacts_messenger view, _contacts_extension view, _contacts_profile view, _contacts_relationship view,
_contacts_activity view, _contacts_activity_photo view, _contacts_speeddial view.
http://tizen.org/privilege/callhistory.write is needed for record which is related to _contacts_phone_log view.
Parameters:
[in]view_uriThe view URI of records
[in]record_id_arrayThe record IDs to delete
[in]countThe size of record ID array
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
Postcondition:
contacts_db_changed_cb() callback wil be called upon success.
See also:
contacts_connect()
contacts_db_insert_records()
contacts_db_update_records()
int contacts_db_get_all_records ( const char *  view_uri,
int  offset,
int  limit,
contacts_list_h *  record_list 
)

Retrieves all records and returns the results list.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Privilege:
http://tizen.org/privilege/callhistory.read
Remarks:
You must release record_list using contacts_list_destroy().
http://tizen.org/privilege/contact.read is needed for record which is related to _contacts_address_book view, _contacts_person view,
_contacts_contact view, _contacts_simple_contact view, _contacts_group view, _contacts_my_profile view,
_contacts_name view, _contacts_number view, _contacts_email view, _contacts_address view,
_contacts_note view, _contacts_url view, _contacts_event view, _contacts_image view,
_contacts_company view, _contacts_nickname view, _contacts_messenger view, _contacts_extension view,
_contacts_profile view, _contacts_relationship view, _contacts_activity view, _contacts_activity_photo view,
_contacts_speeddial view, _contacts_sdn view and all read-only views except views which are related to phone log.
http://tizen.org/privilege/callhistory.read is needed for record which is related to _contacts_phone_log view, _contacts_phone_log_stat view (read only).
_contacts_person_phone_log view (read only) view is needed both privileges.
Parameters:
[in]view_uriThe view URI to get records
[in]offsetThe index from which to get results
[in]limitThe number to limit results(value 0 is used for all records)
[out]record_listThe record list
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_list_destroy()
int contacts_db_get_changes_by_version ( const char *  view_uri,
int  address_book_id,
int  contacts_db_version,
contacts_list_h *  change_record_list,
int *  current_contacts_db_version 
)

Retrieves records changes since the given database version.

This function will find all changed records since the given contacts_db_version.
Now, support _contacts_contact_updated_info view (read only), _contacts_group_updated_info view (read only)
_contacts_my_profile_updated_info view (read only) and _contacts_grouprel_updated_info view (read only).

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Remarks:
You must release record_list using contacts_list_destroy().
Parameters:
[in]view_uriThe view URI to get records
[in]address_book_idThe address book ID to filter
[in]contacts_db_versionThe contacts database version
[out]change_record_listThe record list
[out]current_contacts_db_versionThe current contacts database version
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_list_destroy()
int contacts_db_get_count ( const char *  view_uri,
int *  count 
)

Gets the number of records in a specific view.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Privilege:
http://tizen.org/privilege/callhistory.read
Remarks:
http://tizen.org/privilege/contact.read is needed for record which is related to _contacts_address_book view, _contacts_person view,
_contacts_contact view, _contacts_simple_contact view, _contacts_group view, _contacts_my_profile view,
_contacts_name view, _contacts_number view, _contacts_email view, _contacts_address view,
_contacts_note view, _contacts_url view, _contacts_event view, _contacts_image view,
_contacts_company view, _contacts_nickname view, _contacts_messenger view, _contacts_extension view,
_contacts_profile view, _contacts_relationship view, _contacts_activity view, _contacts_activity_photo view,
_contacts_speeddial view, _contacts_sdn view and all read-only views except views which is related to phone log.
http://tizen.org/privilege/callhistory.read is needed for record which is related to _contacts_phone_log view, _contacts_phone_log_stat view (read only).
_contacts_person_phone_log view (read only) view is needed both privilege.
Parameters:
[in]view_uriThe view URI
[out]countThe count of records
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
int contacts_db_get_count_with_query ( contacts_query_h  query,
int *  count 
)

Gets the number of records matching a query.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Privilege:
http://tizen.org/privilege/callhistory.read
Remarks:
http://tizen.org/privilege/contact.read is needed for record which is related to _contacts_address_book view, _contacts_person view,
_contacts_contact view, _contacts_simple_contact view, _contacts_group view, _contacts_my_profile view,
_contacts_name view, _contacts_number view, _contacts_email view, _contacts_address view,
_contacts_note view, _contacts_url view, _contacts_event view, _contacts_image view,
_contacts_company view, _contacts_nickname view, _contacts_messenger view, _contacts_extension view,
_contacts_profile view, _contacts_relationship view, _contacts_activity view, _contacts_activity_photo view,
_contacts_speeddial view, _contacts_sdn view and all read-only views except views which is related to phone log.
http://tizen.org/privilege/callhistory.read is needed for record which is related to _contacts_phone_log view, _contacts_phone_log_stat view (read only).
_contacts_person_phone_log view (read only) view is needed both privilege.
Parameters:
[in]queryThe query handle
[out]countThe count of records
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
int contacts_db_get_current_version ( int *  contacts_db_version)

Gets the current contacts database version.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Privilege:
http://tizen.org/privilege/callhistory.read
Parameters:
[out]contacts_db_versionThe contacts database version
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_db_get_changes_by_version()
int contacts_db_get_last_change_version ( int *  last_change_version)

Gets the last successful changed contacts database version on the current connection.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Privilege:
http://tizen.org/privilege/callhistory.read
Parameters:
[out]last_change_versionThe database version
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_db_get_current_version()
int contacts_db_get_record ( const char *  view_uri,
int  record_id,
contacts_record_h *  record 
)

Gets a record from the contacts database.

This function creates a new contact handle from the contacts database by the given record_id.
record will be created, which is filled with contact information.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Privilege:
http://tizen.org/privilege/callhistory.read
Remarks:
http://tizen.org/privilege/contact.read is needed for record which is related to _contacts_address_book view, _contacts_person view,
_contacts_contact view, _contacts_simple_contact view, _contacts_group view, _contacts_my_profile view,
_contacts_name view, _contacts_number view, _contacts_email view, _contacts_address view,
_contacts_note view, _contacts_url view, _contacts_event view, _contacts_image view,
_contacts_company view, _contacts_nickname view, _contacts_messenger view, _contacts_extension view,
_contacts_profile view, _contacts_relationship view, _contacts_activity view, _contacts_activity_photo view,
_contacts_speeddial view, _contacts_sdn view.
http://tizen.org/privilege/callhistory.read is needed for record which is related to _contacts_phone_log view.
You must release record using contacts_record_destroy().
Parameters:
[in]view_uriThe view URI of a record
[in]record_idThe record ID to get from database
[out]recordThe record handle associated with the record ID
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_record_destroy()
int contacts_db_get_records_with_query ( contacts_query_h  query,
int  offset,
int  limit,
contacts_list_h *  record_list 
)

Uses a query to find records.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Privilege:
http://tizen.org/privilege/callhistory.read
Remarks:
You must release record_list using contacts_list_destroy().
http://tizen.org/privilege/contact.read is needed for record which is related to _contacts_address_book view, _contacts_person view,
_contacts_contact view, _contacts_simple_contact view, _contacts_group view, _contacts_my_profile view,
_contacts_name view, _contacts_number view, _contacts_email view, _contacts_address view,
_contacts_note view, _contacts_url view, _contacts_event view, _contacts_image view,
_contacts_company view, _contacts_nickname view, _contacts_messenger view, _contacts_extension view,
_contacts_profile view, _contacts_relationship view, _contacts_activity view, _contacts_activity_photo view,
_contacts_speeddial view, _contacts_sdn view and all read-only views except views which are related to phone log.
http://tizen.org/privilege/callhistory.read is needed for record which is related to _contacts_phone_log view, _contacts_phone_log_stat view (read only).
_contacts_person_phone_log view (read only) view is needed both privileges.
Parameters:
[in]queryThe query to filter the results
[in]offsetThe index from which to get results
[in]limitThe number to limit results(value 0 is used for get all records)
[out]record_listThe record list
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_list_destroy()

Gets the current status of server.

Since :
3.0
Parameters:
[in]statusThe current status of server
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
This function requires an open connection to the contacts service by contacts_connect().
See also:
contacts_connect()
int contacts_db_insert_record ( contacts_record_h  record,
int *  id 
)

Inserts a record to the contacts database.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.write
Privilege:
http://tizen.org/privilege/callhistory.write
Remarks:
http://tizen.org/privilege/contact.write is needed for record which is created with _contacts_address_book view, _contacts_contact view,
_contacts_group view, _contacts_my_profile view, _contacts_name view, _contacts_number view,
_contacts_email view, _contacts_address view, _contacts_note view, _contacts_url view,
_contacts_event view, _contacts_image view, _contacts_company view, _contacts_nickname view,
_contacts_messenger view, _contacts_extension view, _contacts_profile view, _contacts_relationship view,
_contacts_activity view, _contacts_activity_photo view, _contacts_speeddial view.
http://tizen.org/privilege/callhistory.write is needed for record which is created with _contacts_phone_log view.
Parameters:
[in]recordThe record handle
[out]idThe ID of inserted record
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
Postcondition:
contacts_db_changed_cb() callback wil be called upon success.
See also:
contacts_connect()
contacts_db_update_record()
contacts_db_delete_record()
contacts_db_get_record()
int contacts_db_insert_records ( contacts_list_h  record_list,
int **  ids,
int *  count 
)

Inserts multiple records to the contacts database.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.write
Privilege:
http://tizen.org/privilege/callhistory.write
Remarks:
http://tizen.org/privilege/contact.write is needed for record which is related to _contacts_address_book view, _contacts_contact view,
_contacts_group view, _contacts_my_profile view, _contacts_name view, _contacts_number view,
_contacts_email view, _contacts_address view, _contacts_note view, _contacts_url view,
_contacts_event view, _contacts_image view, _contacts_company view, _contacts_nickname view,
_contacts_messenger view, _contacts_extension view, _contacts_profile view, _contacts_relationship view,
_contacts_activity view, _contacts_activity_photo view, _contacts_speeddial view.
http://tizen.org/privilege/callhistory.write is needed for record which is related to _contacts_phone_log view.
Parameters:
[in]record_listThe record list handle
[out]idsThe IDs of inserted records
[out]countThe number of IDs
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
Postcondition:
contacts_db_changed_cb() callback wil be called upon success.
See also:
contacts_connect()
contacts_db_update_records()
contacts_db_delete_records()
int contacts_db_remove_changed_cb ( const char *  view_uri,
contacts_db_changed_cb  callback,
void *  user_data 
)

Unregisters a callback function.

Since :
3.0
Parameters:
[in]view_uriThe view URI of records whose changes are monitored
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_SYSTEMSystem error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_db_changed_cb()
contacts_db_add_changed_cb()
int contacts_db_remove_status_changed_cb ( contacts_db_status_changed_cb  callback,
void *  user_data 
)

Unregisters a callback function.

Since :
3.0
Parameters:
[in]callbackThe callback function to register
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
This function requires an open connection to the contacts service by contacts_connect().
See also:
contacts_connect()
contacts_db_add_status_changed_cb()
int contacts_db_replace_record ( contacts_record_h  record,
int  id 
)

Replaces an id-identified record with the given record.

Now, this API supports only _contacts_contact view_uri.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.write
Remarks:
The write-once value of record is not replaced.
This API works only for _contacts_contact view.
Parameters:
[in]recordThe new record handle to replace
[in]idThe DB record ID to be replaced
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
Postcondition:
contacts_db_changed_cb() callback wil be called upon success.
See also:
contacts_connect()
contacts_db_update_record()
contacts_db_delete_record()
contacts_db_get_record()
int contacts_db_replace_records ( contacts_list_h  list,
int  record_id_array[],
int  count 
)

Replaces database records identified by given ids with a given record list.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.write
Remarks:
The write-once value of record is not replaced.
This API works only for _contacts_contact view.
Parameters:
[in]listThe new record list handle to replace
[in]record_id_arrayThe record IDs to replace
[in]countThe size of record ID array
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
Postcondition:
contacts_db_changed_cb() callback wil be called upon success.
See also:
contacts_connect()
contacts_db_update_record()
contacts_db_delete_record()
contacts_db_get_record()
int contacts_db_search_records ( const char *  view_uri,
const char *  keyword,
int  offset,
int  limit,
contacts_list_h *  record_list 
)

Finds records based on a given keyword.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Remarks:
You must release record_list using contacts_list_destroy().
This API works only for _contacts_person view, _contacts_person_contact view (read only),
_contacts_person_grouprel view (read only), _contacts_person_group_assigned view (read only)
and _contacts_person_group_not_assigned view (read only).
Parameters:
[in]view_uriThe view URI to get records
[in]keywordThe keyword
[in]offsetThe index from which to get results
[in]limitThe number to limit results(value 0 is used for get all records)
[out]record_listThe record list
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_list_destroy()
int contacts_db_search_records_for_snippet ( const char *  view_uri,
const char *  keyword,
int  offset,
int  limit,
const char *  start_match,
const char *  end_match,
int  token_number,
contacts_list_h *  record_list 
)

Finds records based on a given keyword for snippet.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Remarks:
You must release record_list using contacts_list_destroy().
This API works only for _contacts_person view, _contacts_person_contact view (read only),
_contacts_person_grouprel view (read only), _contacts_person_group_assigned view (read only)
and _contacts_person_group_not_assigned view (read only).
Because start match and end match is needed to be composed with keyword, this API performance is lower than contacts_db_search_records().
Parameters:
[in]view_uriThe view URI to get records
[in]keywordThe keyword
[in]offsetThe index from which to get results
[in]limitThe number to limit results(value 0 used for get all records)
[in]start_matchThe text which is inserted into the fragment before the keyword(If NULL, default is "[")
[in]end_matchThe text which is inserted into the fragment after the keyword(If NULL, default is "]")
[in]token_numberThe one side extra number of tokens near keyword(If negative value, full sentence is printed. e.g. if token number is 3 with 'abc' keyword, "my name is [abc]de and my home")
[out]record_listThe record list
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_list_destroy()
int contacts_db_search_records_with_query ( contacts_query_h  query,
const char *  keyword,
int  offset,
int  limit,
contacts_list_h *  record_list 
)

Finds records based on given query and keyword.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Remarks:
You must release record_list using contacts_list_destroy().
This API works only for _contacts_person view, _contacts_person_contact view (read only),
_contacts_person_grouprel view (read only), _contacts_person_group_assigned view (read only)
and _contacts_person_group_not_assigned view (read only).
Parameters:
[in]queryThe query handle to filter
[in]keywordThe keyword
[in]offsetThe index from which to get results
[in]limitThe number to limit results(value 0 used for get all records)
[out]record_listThe record list
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_list_destroy()
int contacts_db_search_records_with_query_for_snippet ( contacts_query_h  query,
const char *  keyword,
int  offset,
int  limit,
const char *  start_match,
const char *  end_match,
int  token_number,
contacts_list_h *  record_list 
)

Finds records based on given query and keyword for snippet.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Remarks:
You must release record_list using contacts_list_destroy().
This API works only for _contacts_person view, _contacts_person_contact view (read only),
_contacts_person_grouprel view (read only), _contacts_person_group_assigned view (read only)
and _contacts_person_group_not_assigned view (read only).
Because start match and end match is needed to be composed with keyword, this API performance is lower than contacts_db_search_records_with_query().
Parameters:
[in]queryThe query handle to filter
[in]keywordThe keyword
[in]offsetThe index from which to get results
[in]limitThe number to limit results(value 0 used for get all records)
[in]start_matchThe text which is inserted into the fragment before the keyword(If NULL, default is "[")
[in]end_matchThe text which is inserted into the fragment after the keyword(If NULL, default is "]")
[in]token_numberThe one side extra number of tokens near keyword(If negative value, full sentence is printed. e.g. if token number is 3 with 'abc' keyword, "my name is [abc]de and my home")
[out]record_listThe record list
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_list_destroy()
int contacts_db_search_records_with_range ( const char *  view_uri,
const char *  keyword,
int  offset,
int  limit,
int  range,
contacts_list_h *  record_list 
)

Finds records based on a keyword and range.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Remarks:
You must release record_list using contacts_list_destroy().
This API works only for _contacts_person view, _contacts_person_contact view (read only),
_contacts_person_grouprel view (read only), _contacts_person_group_assigned view (read only),
_contacts_person_group_not_assigned view (read only). These views can search records with range CONTACTS_SEARCH_RANGE_NAME, CONTACTS_SEARCH_RANGE_NUMBER, CONTACTS_SEARCH_RANGE_DATA.
_contacts_person_number view (read only) can search records with CONTACTS_SEARCH_RANGE_NAME and CONTACTS_SEARCH_RANGE_NUMBER.
_contacts_person_email view (read only) can search records with CONTACTS_SEARCH_RANGE_NAME and CONTACTS_SEARCH_RANGE_EMAIL.
Parameters:
[in]view_uriThe view URI
[in]keywordThe keyword
[in]offsetThe index from which to get results
[in]limitThe number to limit results(value 0 is used for get all records)
[in]rangeThe search range
[out]record_listThe record list
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_list_destroy()
int contacts_db_search_records_with_range_for_snippet ( const char *  view_uri,
const char *  keyword,
int  offset,
int  limit,
int  range,
const char *  start_match,
const char *  end_match,
int  token_number,
contacts_list_h *  record_list 
)

Finds records based on a keyword and range for snippet.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.read
Remarks:
You must release record_list using contacts_list_destroy().
This API works only for _contacts_person view, _contacts_person_contact view (read only),
_contacts_person_grouprel view (read only), _contacts_person_group_assigned view (read only),
_contacts_person_group_not_assigned view (read only). These views can search records with range CONTACTS_SEARCH_RANGE_NAME, CONTACTS_SEARCH_RANGE_NUMBER, CONTACTS_SEARCH_RANGE_DATA.
_contacts_person_number view (read only) can search records with CONTACTS_SEARCH_RANGE_NAME and CONTACTS_SEARCH_RANGE_NUMBER.
_contacts_person_email view (read only) can search records with CONTACTS_SEARCH_RANGE_NAME and CONTACTS_SEARCH_RANGE_EMAIL.
Because start match and end match is needed to be composed with keyword, this API performance is lower than contacts_db_search_records_with_range().
Parameters:
[in]view_uriThe view URI
[in]keywordThe keyword
[in]offsetThe index from which to get results
[in]limitThe number to limit results(value 0 is used for get all records)
[in]rangeThe search range
[in]start_matchThe text which is inserted into the fragment before the keyword(If NULL, default is "[")
[in]end_matchThe text which is inserted into the fragment after the keyword(If NULL, default is "]")
[in]token_numberThe one side extra number of tokens near keyword(If negative value, full sentence is printed. e.g. if token number is 3 with 'abc' keyword, "my name is [abc]de and my home")
[out]record_listThe record list
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
See also:
contacts_connect()
contacts_list_destroy()
int contacts_db_update_record ( contacts_record_h  record)

Updates a record in the contacts database.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.write
Privilege:
http://tizen.org/privilege/callhistory.write
Remarks:
http://tizen.org/privilege/contact.write is needed for record which is related to _contacts_address_book view, _contacts_contact view,
_contacts_group view, _contacts_my_profile view, _contacts_name view, _contacts_number view,
_contacts_email view, _contacts_address view, _contacts_note view, _contacts_url view,
_contacts_event view, _contacts_image view, _contacts_company view, _contacts_nickname view,
_contacts_messenger view, _contacts_extension view, _contacts_profile view, _contacts_relationship view,
_contacts_activity view, _contacts_activity_photo view, _contacts_speeddial view.
http://tizen.org/privilege/callhistory.write is needed for record which is related to _contacts_phone_log view.
Parameters:
[in]recordThe record handle
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
Postcondition:
contacts_db_changed_cb() callback wil be called upon success.
See also:
contacts_connect()
contacts_db_insert_record()
contacts_db_delete_record()
contacts_db_get_record()
int contacts_db_update_records ( contacts_list_h  record_list)

Updates multiple records in the contacts database.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/contact.write
Privilege:
http://tizen.org/privilege/callhistory.write
Remarks:
http://tizen.org/privilege/contact.write is needed for record which is related to _contacts_address_book view, _contacts_contact view,
_contacts_group view, _contacts_my_profile view, _contacts_name view, _contacts_number view,
_contacts_email view, _contacts_address view, _contacts_note view, _contacts_url view,
_contacts_event view, _contacts_image view, _contacts_company view, _contacts_nickname view,
_contacts_messenger view, _contacts_extension view, _contacts_profile view, _contacts_relationship view,
_contacts_activity view, _contacts_activity_photo view, _contacts_speeddial view.
http://tizen.org/privilege/callhistory.write is needed for record which is related to _contacts_phone_log view.
Parameters:
[in]record_listThe record list handle
Returns:
0 on success, otherwise a negative error value
Return values:
CONTACTS_ERROR_NONESuccessful
CONTACTS_ERROR_OUT_OF_MEMORYOut of memory
CONTACTS_ERROR_INVALID_PARAMETERInvalid parameter
CONTACTS_ERROR_FILE_NO_SPACEFS Full
CONTACTS_ERROR_NO_DATARequested data does not exist
CONTACTS_ERROR_PERMISSION_DENIEDPermission denied. This application does not have the privilege to call this method
CONTACTS_ERROR_NOT_SUPPORTEDNot supported
CONTACTS_ERROR_DBDatabase operation failure
CONTACTS_ERROR_IPCIPC error
Precondition:
contacts_connect() should be called to open a connection to the contacts service.
Postcondition:
contacts_db_changed_cb() callback wil be called upon success.
See also:
contacts_connect()
contacts_db_insert_records()
contacts_db_delete_records()