*
*/
-
+
#ifndef __TIZEN_SOCIAL_CONTACTS_DOC_H__
#define __TIZEN_SOCIAL_CONTACTS_DOC_H__
*
* Sample code: Insert a contact record
* @code
- * // Create contact record
+ * // create contact record
* contacts_record_h contact = NULL;
* contacts_record_create(_contacts_contact._uri, &contact);
*
- * // Add name
+ * // add name
* contacts_record_h name = NULL;
* contacts_record_create(_contacts_name._uri, &name);
* contacts_record_set_str(name, _contacts_name.first, “test”);
* contacts_record_add_child_record(contact, _contacts_contact.name, name);
*
- * // Add number
+ * // add number
* contacts_record_h number = NULL;
* contacts_record_create(_contacts_number._uri, &number);
* contacts_record_set_str(number, _contacts_number.number, “1234”);
* contacts_record_add_child_record(contact, _contacts_contact.number, number);
*
- * // Insert to database
+ * // insert to database
* int contact_id = 0;
* contacts_db_insert_record(contact, &contact_id);
*
- * // Destroy record
+ * // destroy record
* contacts_record_destroy(contact, true);
* @endcode
*
*
* Sample code: Link contact
* @code
- * int person_id1 = ... // Acquire ID of Person1 record
- * int person_id2 = ... // Acquire ID of Person2 record
+ * int person_id1 = ... // acquire ID of Person1 record
+ * int person_id2 = ... // acquire ID of Person2 record
*
* contacts_person_link_person(person_id1, person_id2);
* @endcode
*
* Sample code: Unlink contact
* @code
- * int person_id1 = ... // Acquire ID of Person1 record
- * int contact_id3 = ... // Acquire ID of Contact3 record
+ * int person_id1 = ... // acquire ID of Person1 record
+ * int contact_id3 = ... // acquire ID of Contact3 record
*
* contacts_person_unlink_contact(person_id1, contact_id3);
* @endcode
* contacts_record_h contact = NULL;
* contacts_record_create(_contacts_contact._uri, &contact);
*
- * // Set image to _contacts_contact view
+ * // set image to _contacts_contact view.
* contacts_record_h image = NULL;
* contacts_record_create(_contacts_image._uri, &image);
*
* free(resource_path);
* contacts_record_set_str(image, _contacts_image.path, caller_id_path);
*
- * // Add image record to contact
+ * // add image record to contact
* contacts_record_add_child_record(contact, _contacts_contact.image, image);
* @endcode
*
* <table class="note">
- * <tr>
- * <th class="note">Note</th>
- * </tr>
- * <tr>
- * <td class="note">For an application to insert private images in contacts, it needs to follow below conditions:<br/>
+ * <tr>
+ * <th class="note">Note</th>
+ * </tr>
+ * <tr>
+ * <td class="note">For an application to insert private images in contacts, it needs to follow below conditions:<br/>
* 1. Application must have privilege of http://tizen.org/privilege/contact.write to use APIs such as contacts_db_insert_record().<br/>
* 2. Application's private directory and files must have 'read' permission of others, '644' for example. SMACK protects read permission from the other applications.<br/>
* 3. Application may erase the image after destroying the contact record (contacts_record_destroy).<br/>
- * </td>
- * </tr>
+ * </td>
+ * </tr>
* </table>
* @section CAPI_SOCIAL_CONTACTS_SVC_MODULE_RECORDS Records
* In contacts-service, one of the basic concept is a record.
*
* APIs which needs _uri
* @code
- * int contacts_record_create(const char* view_uri, ...)
- * int contacts_filter_create(const char* view_uri, ...)
- * int contacts_query_create(const char* view_uri, ...)
- * int contacts_db_get_record(const char* view_uri, ...)
- * int contacts_db_delete_record(const char* view_uri, ...)
- * int contacts_db_get_all_records(const char* view_uri, ...)
- * int contacts_db_delete_records(const char* view_uri, ...)
- * int contacts_db_add_changed_cb(const char* view_uri, ...)
- * int contacts_db_remove_changed_cb(const char* view_uri, ...)
- * int contacts_db_get_changes_by_version(const char* view_uri, ...)
- * int contacts_db_search_records(const char* view_uri, ...)
- * int contacts_db_search_records_with_range(const char* view_uri, ...)
- * int contacts_db_get_count(const char* view_uri, ...)
+ * API int contacts_record_create(const char* view_uri, ...)
+ * API int contacts_filter_create(const char* view_uri, ...)
+ * API int contacts_query_create(const char* view_uri, ...)
+ * API int contacts_db_get_record(const char* view_uri, ...)
+ * API int contacts_db_delete_record(const char* view_uri, ...)
+ * API int contacts_db_get_all_records(const char* view_uri, ...)
+ * API int contacts_db_delete_records(const char* view_uri, ...)
+ * API int contacts_db_add_changed_cb(const char* view_uri, ...)
+ * API int contacts_db_remove_changed_cb(const char* view_uri, ...)
+ * API int contacts_db_get_changes_by_version(const char* view_uri, ...)
+ * API int contacts_db_search_records(const char* view_uri, ...)
+ * API int contacts_db_search_records_with_range(const char* view_uri, ...)
+ * API int contacts_db_get_count(const char* view_uri, ...)
* @endcode
*
* @subsection CAPI_SOCIAL_CONTACTS_SVC_MODULE_RECORDS_HANDLE Record handle
* contacts_record_create(_contacts_contact._uri, &contact);
* @endcode
*
- * Sample code: Gets a contact record with ID
+ * Sample code: Gets a contact record with id
* @code
* contacts_record_h contact = NULL;
* contacts_db_get_record(_contacts_contact._uri, id, &contact);
* contacts_record_h image = NULL;
* int contact_id = 0;
*
- * // Image, address record can be child record of contact record
+ * // image, address record can be child record of contact record
* contacts_record_create(_contacts_contact._uri, &contact);
*
* contacts_record_create(_contacts_image._uri, &image);
* contacts_record_set_str(address, _contacts_address.country, "Korea");
* contacts_record_add_child_record(contact, _contacts_contact.address, address);
*
- * // Insert contact to DBs
+ * // insert contact to DBs
* contacts_db_insert_record(contact, &contact_id);
* contacts_record_destroy(contact, true);
* @endcode
* ID is unique number which can identify a record Therefore, if you know the ID of a record, you can directly handle the record.
* The ID is read-only property, which is available after the record has been inserted into the database.
*
- * Sample code: Gets a contact record with ID
+ * Sample code: Gets a contact record with id
* @code
* contacts_record_h contact = NULL;
* contacts_record_create(_contacts_contact._uri, &contact);
*
* Sample code: Insert a address record with contact_id
* @code
- * int contact_id = ... // Acquire ID of created contact
+ * int contact_id = ... // acquire id of created contact
* int address_id = 0;
* contacts_record_create(_contacts_address._uri, &address);
* contacts_record_set_int(address, _contacts_address.contact_id, contact_id);
- * // Set other address properties
- *
+ * // set other address properties
+ * // ...
* contacts_db_insert_record(address, &address_id);
* @endcode
* Having a record handle, you can access all records of a specific type related to the given record.
*
* Sample code: Gets a contact record
* @code
- * int contact_id = ... // Acquire ID of created contact
+ * int contact_id = ... // acquire id of created contact
* int address_num = 0;
* int i = 0;
* contacts_db_get_record(_contacts_contact._uri, contact_id, &contact);
* contacts_record_get_child_record_count(contact, _contacts_contact.address, &address_num);
* for (i = 0; i < address_num; i++) {
- * contacts_record_h address = NULL;
- * contacts_record_get_child_record_at_p(contact, _contacts_contact.address, i, &address);
- * contacts_record_set_str(address, _contacts_address.country, "Korea");
+ * contacts_record_h address = NULL;
+ * contacts_record_get_child_record_at_p(contact, _contacts_contact.address, i, &address);
+ * contacts_record_set_str(address, _contacts_address.country, "Korea");
* }
* contacts_db_update_record(contact);
* contacts_record_destroy(contact, true);
* To operate a list, you must obtain its handle. The handle is provided during creation of the list. List handle must destroy after use.
*
* @code
- * int contacts_list_create(contacts_list_h* contacts_list);
- * int contacts_list_destroy(contacts_list_h contacts_list, bool delete_child);
+ * API int contacts_list_create(contacts_list_h* contacts_list);
+ * API int contacts_list_destroy(contacts_list_h contacts_list, bool delete_child);
* @endcode
*
* If ‘delete_child’ parameter is the true, child resources will destroy automatically.
*
* Sample code: Create a list handle
* @code
- * // Get list handle with query
+ * // get list handle with query
* contacts_list_h list = NULL;
* contacts_list_create(&list);
*
- * // Use list
+ * // use list
+ * // ...
*
* contacts_list_destroy(list, true);
* @endcode
*
* Sample code: Gets person list handle from database.
* @code
- * // Get list handle with query
+ * // get list handle with query
* contacts_list_h list = NULL;
* contacts_db_get_all_records(_contacts_person._uri, 0, 0, &list);
*
- * // Use list
+ * // use list
+ * // ...
*
* contacts_list_destroy(list, true);
* @endcode
* The list can be traversed by using cursor.
*
* @code
- * int contacts_list_first(contacts_list_h contacts_list);
- * int contacts_list_last(contacts_list_h contacts_list);
- * int contacts_list_next(contacts_list_h contacts_list);
- * int contacts_list_prev(contacts_list_h contacts_list);
+ * API int contacts_list_first(contacts_list_h contacts_list);
+ * API int contacts_list_last(contacts_list_h contacts_list);
+ * API int contacts_list_next(contacts_list_h contacts_list);
+ * API int contacts_list_prev(contacts_list_h contacts_list);
* @endcode
*
* You can get a record of current cursor.
*
* @code
- * int contacts_list_get_current_record_p(contacts_list_h contacts_list, contacts_record_h* record);
+ * API int contacts_list_get_current_record_p(contacts_list_h contacts_list, contacts_record_h* record);
* @endcode
*
* Sample code: Loop list
* contacts_record_h record = NULL;
* contacts_db_get_all_records(_contacts_person._uri, 0, 0, &list);
* do {
- * contacts_list_get_current_record_p(list, &record);
- * if (NULL == record)
- * break;
- * char *name = NULL;
- * contacts_record_get_str_p(record, _contacts_person.display_name, &name);
- * printf(“name=%s\n”, name);
+ * contacts_list_get_current_record_p(list, &record);
+ * if (NULL == record)
+ * break;
+ * char *name = NULL;
+ * contacts_record_get_str_p(record, _contacts_person.display_name, &name);
+ * printf(“name=%s\n”, name);
* } while (CONTACTS_ERROR_NONE == contacts_list_next(list));
- * contacts_list_destroy(list, true); // Destroy child records automatically
+ * contacts_list_destroy(list, true); // destroy child records automatically
* @endcode
*
* @subsection CAPI_SOCIAL_CONTACTS_SVC_MODULE_LISTS_ADD_REMOVE Add / Remove
* The contacts-service provides functions for adding/removing child record on list.
* @code
- * int contacts_list_add(contacts_list_h contacts_list, contacts_record_h record);
- * int contacts_list_remove(contacts_list_h contacts_list, contacts_record_h record);
+ * API int contacts_list_add(contacts_list_h contacts_list, contacts_record_h record);
+ * API int contacts_list_remove(contacts_list_h contacts_list, contacts_record_h record);
* @endcode
*
* Sample code: Adds records to the list
* Bulk APIs provide to insert/update/delete multiple records. There is no limit of record count on bulk API, but it causes a process to hang during the time the API is operated. Bulk APIs guarantee atomicity. That is, the API operating either all, or nothing.
*
* @code
- * int contacts_db_insert_records(contacts_list_h record_list, int **ids, int *count);
- * int contacts_db_update_records(contacts_list_h record_list);
- * int contacts_db_delete_records(const char* view_uri, int record_id_array[], int count);
- * int contacts_db_replace_records(contacts_list_h list, int record_id_array[], int count);
+ * API int contacts_db_insert_records(contacts_list_h record_list, int **ids, int *count);
+ * API int contacts_db_update_records(contacts_list_h record_list);
+ * API int contacts_db_delete_records(const char* view_uri, int record_id_array[], int count);
+ * API int contacts_db_replace_records(contacts_list_h list, int record_id_array[], int count);
* @endcode
*
* Sample code: Insert two contact records using bulk API.
* contacts_record_h contact1;
* contacts_record_create(_contacts_contact.uri, &contact1);
*
- * // Fill contact record
+ * // fill contact record
+ * // ...
*
* contacts_record_h contact2;
* contacts_record_create(_contacts_contact._uri, &contact2);
*
- * // Fill contact record
+ * // fill contact record
+ * // ...
*
* contacts_list_h list = NULL;
* contacts_list_create(&list);
* // Insert contact records using bulk API
* contacts_db_insert_records(list, &ids, &count);
*
- * // Use IDs
+ * // use ids
+ * // ...
*
* contacts_list_destroy(list, true);
* free(ids);
* When creating a filter, you need to specify what type of filter you want to create using _uri property. Filter handle must destroy after use.
*
* @code
- * int contacts_filter_create(const char* view_uri, contacts_filter_h* filter);
- * int contacts_filter_destroy(contacts_filter_h filter);
+ * API int contacts_filter_create(const char* view_uri, contacts_filter_h* filter);
+ * API int contacts_filter_destroy(contacts_filter_h filter);
* @endcode
*
* Sample code: Set filter condition to contain a given substring.
* </tr>
* </table>
*
- * Sample code: Create a filter which will accept addresses with their contacts ID equal to a given ID (integer filter), or their country property equal to "Korea" (string filter). Create a query and add the filter to it. Results are received in a list.
+ * Sample code: Create a filter which will accept addresses with their contact's id equal to a given id (integer filter), or their country property equal to "Korea" (string filter). Create a query and add the filter to it. Results are received in a list.
* @code
* contacts_filter_h filter = NULL;
* contacts_list_h list = NULL;
* contacts_filter_destroy(filter);
* contacts_query_destroy(query);
*
- * // Use the list
+ * // use the list
+ * // ...
*
* contacts_list_destroy(list, true);
*
* Query results list can sort by property id.
*
* @code
- * int contacts_query_set_sort(contacts_query_h query, unsigned int property_id, bool is_ascending);
+ * API int contacts_query_set_sort(contacts_query_h query, unsigned int property_id, bool is_ascending);
* @endcode
*
* Sample code: Sort to query result by person id
* Projection allows you to query the Data for just those specific properties of a record that you actually need, at lower latency and cost than retrieving the entire properties.
*
* @code
- * int contacts_query_set_projection(contacts_query_h query, unsigned int property_ids[], int count)
+ * API int contacts_query_set_projection(contacts_query_h query, unsigned int property_ids[], int count)
* @endcode
*
* Sample code: Creates a filter which will get only person id, display name, image thumbnail path from the person record with its vibration path has “test” (string filter). Create a query and add the filter to it. Results are received in a list.
* contacts_filter_add_str(filter, _contacts_person.vibration, CONTACTS_MATCH_CONTAINS, "test");
* contacts_query_set_filter(query, filter);
*
- * // Set projections to get
+ * //set projections to get
* unsigned int person_projection[] = {
- * _contacts_person.id,
- * _contacts_person.display_name,
- * _contacts_person.image_thumbnail_path,
+ * _contacts_person.id,
+ * _contacts_person.display_name,
+ * _contacts_person.image_thumbnail_path,
* };
* contacts_query_set_projection(query, person_projection, sizeof(person_projection)/sizeof(int));
*
* contacts_db_get_records_with_query(query, 0, 0, &person_list);
*
- * // Use list
+ * // use list
+ * // ...
*
* contacts_query_destroy(query);
* contacts_filter_destroy(filter);
* If you query to some read-only view with set projection, result list can contain duplicates. You can remove duplicates using _contacts_query_set_distinct.
*
* @code
- * int contacts_query_set_distinct(contacts_query_h query, bool set)
+ * API int contacts_query_set_distinct(contacts_query_h query, bool set)
* endcode
*
* Sample code: Remove duplicates
* @code
* unsigned int projection[] = {
- * _contacts_person_number.person_id,
- * _contacts_person_number.display_name,
+ * _contacts_person_number.person_id,
+ * _contacts_person_number.display_name,
* };
* contacts_filter_create(_contacts_person_number._uri, &filter);
* contacts_filter_add_bool(filter, _contacts_person_number.has_phonenumber, true);
* contacts_query_set_projection(query, projection, sizeof(projection)/sizeof(int));
* contacts_query_set_filter(query, filter);
*
- * // Set distinct (remove duplicates)
+ * // set distinct (remove duplicates)
* contacts_query_set_distinct(query, true);
*
* contacts_db_get_records_with_query(query, 0, 0, &list);
*
- * // Use list
+ * // use list
+ * // ...
*
* contacts_list_destroy(list, true);
* contacts_query_destroy(query);
*
* Sample code: Register person changes notification callback
* @code
- * // Callback function
- * static void
- * __person_changed_cb(const char *view_uri, void *user_data)
+ * // callback function
+ * static void __person_changed_cb(const char *view_uri, void *user_data)
* {
- * // Jobs for callback
+ * // jobs for callback
* }
- * // Add changed noti callback
- * contacts_db_add_changed_cb(_contacts_person._uri, __person_changed_cb, NULL);
+ * // add changed noti callback
+ * contacts_db_add_changed_cb(_contacts_person._uri, __person_changed_cb, NULL);
* @endcode
*
* @section CAPI_SOCIAL_CONTACTS_SVC_MODULE_VCARD vCard
*
* Sample code: Parsing vCard from stream then insert to database.
* @code
- * // Make contact record list from vcard stream
+ * // make contact record list from vcard stream
* contacts_list_h list = NULL;
* contacts_vcard_parse_to_contacts(vcard_stream, &list);
*
* int count = 0;
* contacts_db_insert_records(list, &ids, &count);
*
- * // Use IDs, count
+ * // use ids, count
+ * // ...
*
* free(ids);
* contacts_list_destroy(list, true);
*
* Sample code: Parsing vCard from file then insert to database
* @code
- * // Called to get a record handle of _contacts_contact view
- * static bool
- * __vcard_parse_cb(contacts_record_h record, void *user_data)
+ * // called to get a record handle of _contacts_contact view
+ * static bool __vcard_parse_cb(contacts_record_h record, void *user_data)
* {
- * int id = 0;
- * contacts_db_insert_record(record, &id);
+ * int id = 0;
+ * contacts_db_insert_record(record, &id);
*
- * // Return false to break out of the loop
- * // Return true to continue with the next iteration of the loop
- * return true;
+ * // return false to break out of the loop
+ * // return true to continue with the next iteration of the loop
+ * return true;
* }
*
- * // Parse vCard from file
+ * // parse vCard from file
* char *resource_path = app_get_resource_path();
* char vcard_path[1024] = {0};
* snprintf(vcard_path, sizeof(vcard_path), "%s/vcard.vcf", resource_path);
* contacts_db_get_record(_contacts_contact._uri, contact_id, &contact);
* contacts_vcard_make_from_contact(contact, &vcard_stream);
*
- * // Use the vcard stream
+ * // use the vcard stream
+ * // ...
*
* free(vcard_stream);
* contacts_record_destroy(contact, true);
* @endcode
*/
-
+
#endif /* __TIZEN_SOCIAL_CONTACTS_DOC_H__ */
projects / platform / core / pim / contacts-service.git / commitdiff