Class ContactsDatabase

Definition

Namespace:
Tizen.Pims.Contacts
Assembly:
Tizen.Pims.Contacts.dll
API Level:
4

The ContactsDatabase provides methods to manage contacts information from/to the database.

public class ContactsDatabase
Inheritance
Object
ContactsDatabase
Remarks

This class allows the user to access/create/update database operations for the contacts information.

Properties

View Source

LastChangeVersion

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

Declaration
public int LastChangeVersion { get; }
Property Value
Type Description
Int32

The last successful changed contacts database version on the current connection.
API Level: 4
View Source

Status

The contacts database status.

Declaration
public ContactsDatabase.DBStatus Status { get; }
Property Value
Type Description
ContactsDatabase.DBStatus

The contacts database status.
API Level: 4
View Source

Version

The current contacts database version.

Declaration
public int Version { get; }
Property Value
Type Description
Int32

The current contacts database version.
API Level: 4

Methods

View Source

AddDBChangedEventHandler(String, EventHandler<DBChangedEventArgs>)

Registers an EventHandler to be invoked when a record changes.

Declaration
public void AddDBChangedEventHandler(string viewUri, EventHandler<DBChangedEventArgs> DBChanged)
Parameters
Type Name Description
String viewUri

The view URI of records whose changes are monitored.
EventHandler<DBChangedEventArgs> DBChanged

The EventHandler to register.
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.readhttp://tizen.org/privilege/callhistory.read
Feature: http://tizen.org/feature/contact
View Source

Delete(String, Int32)

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

Declaration
public void Delete(string viewUri, int recordId)
Parameters
Type Name Description
String viewUri

The view URI of a record.
Int32 recordId

The record ID to delete.
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.writehttp://tizen.org/privilege/callhistory.write
Feature: http://tizen.org/feature/contact
View Source

Delete(String, Int32[])

Deletes multiple records with the related child records from the contacts database as a batch operation.

Declaration
public void Delete(string viewUri, int[] idArray)
Parameters
Type Name Description
String viewUri

The view URI of the records to delete.
Int32[] idArray

The record IDs to delete.
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.writehttp://tizen.org/privilege/callhistory.write
Feature: http://tizen.org/feature/contact
View Source

Get(String, Int32)

Gets a record from the contacts database.

Declaration
public ContactsRecord Get(string viewUri, int recordId)
Parameters
Type Name Description
String viewUri

The view URI of a record.
Int32 recordId

The record ID.
Returns
Type Description
ContactsRecord

The record associated with the record ID
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.readhttp://tizen.org/privilege/callhistory.read
Feature: http://tizen.org/feature/contact
View Source

GetAll(String, Int32, Int32)

Retrieves all the records as a list.

Declaration
public ContactsList GetAll(string viewUri, int offset, int limit)
Parameters
Type Name Description
String viewUri

The view URI to get records.
Int32 offset

The index from which results.
Int32 limit

The number to limit results (value 0 is used for get all records).
Returns
Type Description
ContactsList

The record list.
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.readhttp://tizen.org/privilege/callhistory.read
Feature: http://tizen.org/feature/contact
View Source

GetChangesByVersion(String, Int32, Int32, out Int32)

Retrieves the records changes since the given database version.

Declaration
public ContactsList GetChangesByVersion(string viewUri, int addressBookId, int contactsDBVersion, out int currentDBVersion)
Parameters
Type Name Description
String viewUri

The view URI to get records.
Int32 addressBookId

The address book ID to filter.
Int32 contactsDBVersion

The contacts database version.
Int32 currentDBVersion

The current contacts database version.
Returns
Type Description
ContactsList

The record list.
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.read
Feature: http://tizen.org/feature/contact
View Source

GetCount(String)

Gets the number of records in a specific view.

Declaration
public int GetCount(string viewUri)
Parameters
Type Name Description
String viewUri

The view URI.
Returns
Type Description
Int32

The count of records.
API Level: 4
View Source

GetCount(ContactsQuery)

Gets the number of records matching a query.

Declaration
public int GetCount(ContactsQuery query)
Parameters
Type Name Description
ContactsQuery query

The query used for filtering the results.
Returns
Type Description
Int32

The count of records.
API Level: 4
View Source

GetRecordsWithQuery(ContactsQuery, Int32, Int32)

Retrieves the records using a query.

Declaration
public ContactsList GetRecordsWithQuery(ContactsQuery query, int offset, int limit)
Parameters
Type Name Description
ContactsQuery query

The query to filter the results.
Int32 offset

The index from which to get results.
Int32 limit

The number to limit results (value 0 is used for get all records).
Returns
Type Description
ContactsList

The record list
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.readhttp://tizen.org/privilege/callhistory.read
Feature: http://tizen.org/feature/contact
View Source

Insert(ContactsList)

Inserts multiple records into the contacts database as a batch operation.

Declaration
public int[] Insert(ContactsList list)
Parameters
Type Name Description
ContactsList list

The record list.
Returns
Type Description
Int32[]

The inserted record ID array.
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.writehttp://tizen.org/privilege/callhistory.write
Feature: http://tizen.org/feature/contact
View Source

Insert(ContactsRecord)

Inserts a record into the contacts database.

Declaration
public int Insert(ContactsRecord record)
Parameters
Type Name Description
ContactsRecord record

The record to insert.
Returns
Type Description
Int32

The ID of inserted record.
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.writehttp://tizen.org/privilege/callhistory.write
Feature: http://tizen.org/feature/contact
View Source

RemoveDBChangedEventHandler(String, EventHandler<DBChangedEventArgs>)

Deregisters an EventHandler.

Declaration
public void RemoveDBChangedEventHandler(string viewUri, EventHandler<DBChangedEventArgs> DBChanged)
Parameters
Type Name Description
String viewUri

The view URI of records whose changes are monitored.
EventHandler<DBChangedEventArgs> DBChanged

The EventHandler to deregister.
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
API Level: 4
Feature: http://tizen.org/feature/contact
View Source

Replace(ContactsList, Int32[])

Replaces multiple records in the contacts database as a batch operation.

Declaration
public void Replace(ContactsList list, int[] idArray)
Parameters
Type Name Description
ContactsList list

The record list to replace.
Int32[] idArray

The record IDs to be replaced.
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.writehttp://tizen.org/privilege/callhistory.write
Feature: http://tizen.org/feature/contact
View Source

Replace(ContactsRecord, Int32)

Replaces a record in the contacts database.

Declaration
public void Replace(ContactsRecord record, int recordId)
Parameters
Type Name Description
ContactsRecord record

The record to replace.
Int32 recordId

The record ID to be replaced.
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.writehttp://tizen.org/privilege/callhistory.write
Feature: http://tizen.org/feature/contact
View Source

Search(String, String, Int32, Int32)

Finds the records based on a given keyword.

Declaration
public ContactsList Search(string viewUri, string keyword, int offset, int limit)
Parameters
Type Name Description
String viewUri

The view URI to find records.
String keyword

The keyword.
Int32 offset

The index from which to get results.
Int32 limit

The number to limit results (value 0 is used for get all records).
Returns
Type Description
ContactsList

The record list
Remarks

This API works only for the views below: Person, PersonContact, PersonGroupRelation, PersonGroupAssigned, and PersonGroupNotAssigned.

Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.read
Feature: http://tizen.org/feature/contact
View Source

Search(String, String, Int32, Int32, Int32)

Finds the records based on a keyword and range.

Declaration
public ContactsList Search(string viewUri, string keyword, int offset, int limit, int range)
Parameters
Type Name Description
String viewUri

The view URI.
String keyword

The keyword.
Int32 offset

The index from which to get results.
Int32 limit

The number to limit results (value 0 is used for get all records).
Int32 range

The search range should be an element of the SearchRange or bitwise OR operation of them.
Returns
Type Description
ContactsList

The record list.
Remarks

This API works only for the views below: Person, PersonContact, PersonGroupRelation, PersonGroupAssigned, PersonGroupNotAssigned, PersonNumber, and PersonEmail.

Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.read
Feature: http://tizen.org/feature/contact
View Source

Search(String, String, Int32, Int32, Int32, String, String, Int32)

Finds the records based on a keyword and range for the snippet.

Declaration
public ContactsList Search(string viewUri, string keyword, int offset, int limit, int range, string startMatch, string endMatch, int tokenNumber)
Parameters
Type Name Description
String viewUri

The view URI.
String keyword

The keyword.
Int32 offset

The index from which to get results.
Int32 limit

The number to limit results (value 0 is used for get all records).
Int32 range

The search range should be an element of the SearchRange or bitwise OR operation of them.
String startMatch

The text, which is inserted into the fragment before a keyword (If NULL, default is "[").
String endMatch

The text, which is inserted into the fragment after a keyword (If NULL, default is "]").
Int32 tokenNumber

The one side extra number of tokens near a keyword (If negative value, full sentence is printed. For example, if a token number is 3 with 'abc' keyword, snippet string will be like "my name is [abc]de and my home").
Returns
Type Description
ContactsList

The record list.
Remarks

This API works only for the views below: Person, PersonContact, PersonGroupRelation, PersonGroupAssigned, PersonGroupNotAssigned, PersonNumber, and PersonEmail, Because the start match and end match are needed to be composed with a keyword, this API performance is lower than Search (string viewUri, string keyword, int offset, int limit, int range).

Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.read
Feature: http://tizen.org/feature/contact
View Source

Search(String, String, Int32, Int32, String, String, Int32)

Finds the records based on a given keyword for the snippet.

Declaration
public ContactsList Search(string viewUri, string keyword, int offset, int limit, string startMatch, string endMatch, int tokenNumber)
Parameters
Type Name Description
String viewUri

The view URI to find records.
String keyword

The keyword.
Int32 offset

The index from which to get results.
Int32 limit

The number to limit results (value 0 is used for get all records).
String startMatch

The text, which is inserted into the fragment before the keyword (If NULL, default is "[".)
String endMatch

The text, which is inserted into the fragment after the keyword (If NULL, default is "]")
Int32 tokenNumber

The one side extra number of tokens near keyword (If negative value, full sentence is printed. For example, if the token number is 3 with 'abc' keyword, snippet string will be like "my name is [abc]de and my home").
Returns
Type Description
ContactsList

The record list
Remarks

This API works only for the views below: Person, PersonContact, PersonGroupRelation, PersonGroupAssigned, and PersonGroupNotAssigned. Because the start match and end match are needed to be composed with a keyword, this API performance is lower than Search (string viewUri, string keyword, int offset, int limit).

Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.read
Feature: http://tizen.org/feature/contact
View Source

Search(ContactsQuery, String, Int32, Int32)

Finds the records based on a given query and keyword.

Declaration
public ContactsList Search(ContactsQuery query, string keyword, int offset, int limit)
Parameters
Type Name Description
ContactsQuery query

The query to filter.
String keyword

The keyword.
Int32 offset

The index from which to get results.
Int32 limit

The number to limit results (value 0 is used for get all records).
Returns
Type Description
ContactsList

The record list.
Remarks

This API works only for the views below: Person, PersonContact, PersonGroupRelation, PersonGroupAssigned, and PersonGroupNotAssigned.

Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.read
Feature: http://tizen.org/feature/contact
View Source

Search(ContactsQuery, String, Int32, Int32, String, String, Int32)

Finds the records based on a given query and keyword for the snippet.

Declaration
public ContactsList Search(ContactsQuery query, string keyword, int offset, int limit, string startMatch, string endMatch, int tokenNumber)
Parameters
Type Name Description
ContactsQuery query

The query to filter.
String keyword

The keyword.
Int32 offset

The index from which to get results.
Int32 limit

The number to limit results (value 0 is used for get all records).
String startMatch

The text, which is inserted into the fragment before a keyword (If NULL, default is "[").
String endMatch

The text, which is inserted into the fragment after a keyword (If NULL, default is "]".)
Int32 tokenNumber

The one side extra number of tokens near a keyword (If negative value, full sentence is printed. For example, if the token number is 3 with 'abc' keyword, snippet string will be like "my name is [abc]de and my home").
Returns
Type Description
ContactsList

The record list.
Remarks

This API works only for the views below: Person, PersonContact, PersonGroupRelation, PersonGroupAssigned, and PersonGroupNotAssigned. Because the start match and end match are needed to be composed with a keyword, this API performance is lower than Search (ContactsQuery query, string keyword, int offset, int limit).

Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.read
Feature: http://tizen.org/feature/contact
View Source

Update(ContactsList)

Updates multiple records in the contacts database as a batch operation.

Declaration
public void Update(ContactsList list)
Parameters
Type Name Description
ContactsList list

The record list.
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.writehttp://tizen.org/privilege/callhistory.write
Feature: http://tizen.org/feature/contact
View Source

Update(ContactsRecord)

Updates a record in the contacts database.

Declaration
public void Update(ContactsRecord record)
Parameters
Type Name Description
ContactsRecord record

The record to update.
Exceptions
Type Condition
InvalidOperationException

Thrown when the method failed due to an invalid operation.
NotSupportedException

Thrown when the feature is not supported.
ArgumentException

Thrown when one of the arguments provided to a method is not valid.
OutOfMemoryException

Thrown when failed due to out of memory.
UnauthorizedAccessException

Thrown when the application does not have proper privileges.
API Level: 4
Privilege Level: public
Privilege: http://tizen.org/privilege/contact.writehttp://tizen.org/privilege/callhistory.write
Feature: http://tizen.org/feature/contact

Events

View Source

DBStatusChanged

Occurs when the contacts database status is changed.

Declaration
public event EventHandler<DBStatusChangedEventArgs> DBStatusChanged
Event Type
Type Description
EventHandler<DBStatusChangedEventArgs>
API Level: 4