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.


                C#
                
                    Copy
                    
                
            
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


                C#
                
                    Copy
                    
                
            
public int LastChangeVersion { get; }

Property Value

Type	Description
System.Int32	The last successful changed contacts database version on the current connection.

API Level: 4

View Source

Status

The contacts database status.

Declaration


                C#
                
                    Copy
                    
                
            
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


                C#
                
                    Copy
                    
                
            
public int Version { get; }

Property Value

Type	Description
System.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


                C#
                
                    Copy
                    
                
            
public void AddDBChangedEventHandler(string viewUri, EventHandler<DBChangedEventArgs> DBChanged)

Parameters

Type	Name	Description
System.String	viewUri	The view URI of records whose changes are monitored.
System.EventHandler<DBChangedEventArgs>	DBChanged	The EventHandler to register.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the method failed due to an invalid operation.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public void Delete(string viewUri, int recordId)

Parameters

Type	Name	Description
System.String	viewUri	The view URI of a record.
System.Int32	recordId	The record ID to delete.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the method failed due to an invalid operation.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public void Delete(string viewUri, int[] idArray)

Parameters

Type	Name	Description
System.String	viewUri	The view URI of the records to delete.
System.Int32[]	idArray	The record IDs to delete.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the method failed due to an invalid operation.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public ContactsRecord Get(string viewUri, int recordId)

Parameters

Type	Name	Description
System.String	viewUri	The view URI of a record.
System.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.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public ContactsList GetAll(string viewUri, int offset, int limit)

Parameters

Type	Name	Description
System.String	viewUri	The view URI to get records.
System.Int32	offset	The index from which results.
System.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.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public ContactsList GetChangesByVersion(string viewUri, int addressBookId, int contactsDBVersion, out int currentDBVersion)

Parameters

Type	Name	Description
System.String	viewUri	The view URI to get records.
System.Int32	addressBookId	The address book ID to filter.
System.Int32	contactsDBVersion	The contacts database version.
System.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.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public int GetCount(string viewUri)

Parameters

Type	Name	Description
System.String	viewUri	The view URI.

Returns

Type	Description
System.Int32	The count of records.

API Level: 4

View Source

GetCount(ContactsQuery)

Gets the number of records matching a query.

Declaration


                C#
                
                    Copy
                    
                
            
public int GetCount(ContactsQuery query)

Parameters

Type	Name	Description
ContactsQuery	query	The query used for filtering the results.

Returns

Type	Description
System.Int32	The count of records.

API Level: 4

View Source

GetRecordsWithQuery(ContactsQuery, Int32, Int32)

Retrieves the records using a query.

Declaration


                C#
                
                    Copy
                    
                
            
public ContactsList GetRecordsWithQuery(ContactsQuery query, int offset, int limit)

Parameters

Type	Name	Description
ContactsQuery	query	The query to filter the results.
System.Int32	offset	The index from which to get results.
System.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.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public int[] Insert(ContactsList list)

Parameters

Type	Name	Description
ContactsList	list	The record list.

Returns

Type	Description
System.Int32[]	The inserted record ID array.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the method failed due to an invalid operation.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public int Insert(ContactsRecord record)

Parameters

Type	Name	Description
ContactsRecord	record	The record to insert.

Returns

Type	Description
System.Int32	The ID of inserted record.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the method failed due to an invalid operation.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public void RemoveDBChangedEventHandler(string viewUri, EventHandler<DBChangedEventArgs> DBChanged)

Parameters

Type	Name	Description
System.String	viewUri	The view URI of records whose changes are monitored.
System.EventHandler<DBChangedEventArgs>	DBChanged	The EventHandler to deregister.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the method failed due to an invalid operation.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public void Replace(ContactsList list, int[] idArray)

Parameters

Type	Name	Description
ContactsList	list	The record list to replace.
System.Int32[]	idArray	The record IDs to be replaced.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the method failed due to an invalid operation.
System.NotSupportedException	Thrown when feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public void Replace(ContactsRecord record, int recordId)

Parameters

Type	Name	Description
ContactsRecord	record	The record to replace.
System.Int32	recordId	The record ID to be replaced.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the method failed due to an invalid operation.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public ContactsList Search(string viewUri, string keyword, int offset, int limit)

Parameters

Type	Name	Description
System.String	viewUri	The view URI to find records.
System.String	keyword	The keyword.
System.Int32	offset	The index from which to get results.
System.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.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public ContactsList Search(string viewUri, string keyword, int offset, int limit, int range)

Parameters

Type	Name	Description
System.String	viewUri	The view URI.
System.String	keyword	The keyword.
System.Int32	offset	The index from which to get results.
System.Int32	limit	The number to limit results (value 0 is used for get all records).
System.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.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public ContactsList Search(string viewUri, string keyword, int offset, int limit, int range, string startMatch, string endMatch, int tokenNumber)

Parameters

Type	Name	Description
System.String	viewUri	The view URI.
System.String	keyword	The keyword.
System.Int32	offset	The index from which to get results.
System.Int32	limit	The number to limit results (value 0 is used for get all records).
System.Int32	range	The search range should be an element of the SearchRange or bitwise OR operation of them.
System.String	startMatch	The text, which is inserted into the fragment before a keyword (If NULL, default is "[").
System.String	endMatch	The text, which is inserted into the fragment after a keyword (If NULL, default is "]").
System.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.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public ContactsList Search(string viewUri, string keyword, int offset, int limit, string startMatch, string endMatch, int tokenNumber)

Parameters

Type	Name	Description
System.String	viewUri	The view URI to find records.
System.String	keyword	The keyword.
System.Int32	offset	The index from which to get results.
System.Int32	limit	The number to limit results (value 0 is used for get all records).
System.String	startMatch	The text, which is inserted into the fragment before the keyword (If NULL, default is "[".)
System.String	endMatch	The text, which is inserted into the fragment after the keyword (If NULL, default is "]")
System.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.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public ContactsList Search(ContactsQuery query, string keyword, int offset, int limit)

Parameters

Type	Name	Description
ContactsQuery	query	The query to filter.
System.String	keyword	The keyword.
System.Int32	offset	The index from which to get results.
System.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.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
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.
System.String	keyword	The keyword.
System.Int32	offset	The index from which to get results.
System.Int32	limit	The number to limit results (value 0 is used for get all records).
System.String	startMatch	The text, which is inserted into the fragment before a keyword (If NULL, default is "[").
System.String	endMatch	The text, which is inserted into the fragment after a keyword (If NULL, default is "]".)
System.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.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
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.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
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.
System.NotSupportedException	Thrown when the feature is not supported.
System.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


                C#
                
                    Copy
                    
                
            
public event EventHandler<DBStatusChangedEventArgs> DBStatusChanged

Event Type

Type	Description
System.EventHandler<DBStatusChangedEventArgs>