Class ContactsDatabase

Definition

Namespace:

Tizen.Pims.Contacts

Assembly:

Tizen.Pims.Contacts.dll

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

LastChangeVersion

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

Declaration

public int LastChangeVersion { get; }

Property Value

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

Remarks

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

Status

The contacts database status.

Declaration

public ContactsDatabase.DBStatus Status { get; }

Property Value

Type	Description
ContactsDatabase.DBStatus	The contacts database status.

Remarks

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

Version

The current contacts database version.

Declaration

public int Version { get; }

Property Value

Type	Description
int	The current contacts database version.

Remarks

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

Methods

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.
System.EventHandler<TEventArgs><DBChangedEventArgs>	DBChanged	The EventHandler to register.

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

Delete(string, int)

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.
int	recordId	The record ID to delete.

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

Delete(string, int[])

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.
int[]	idArray	The record IDs to delete.

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

Get(string, int)

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.
int	recordId	The record ID.

Returns

Type	Description
ContactsRecord	The record associated with the record ID

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

GetAll(string, int, int)

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.
int	offset	The index from which results.
int	limit	The number to limit results (value 0 is used for get all records).

Returns

Type	Description
ContactsList	The record list.

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

GetChangesByVersion(string, int, int, out int)

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.
int	addressBookId	The address book ID to filter.
int	contactsDBVersion	The contacts database version.
int	currentDBVersion	The current contacts database version.

Returns

Type	Description
ContactsList	The record list.

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

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
int	The count of records.

Remarks

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

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
int	The count of records.

Remarks

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

GetRecordsWithQuery(ContactsQuery, int, int)

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.
int	offset	The index from which to get results.
int	limit	The number to limit results (value 0 is used for get all records).

Returns

Type	Description
ContactsList	The record list

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

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
int[]	The inserted record ID array.

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

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
int	The ID of inserted record.

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

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.
System.EventHandler<TEventArgs><DBChangedEventArgs>	DBChanged	The EventHandler to deregister.

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.

Replace(ContactsList, int[])

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.
int[]	idArray	The record IDs to be replaced.

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

Replace(ContactsRecord, int)

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.
int	recordId	The record ID to be replaced.

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

Search(string, string, int, int, int, string, string, int)

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.
int	offset	The index from which to get results.
int	limit	The number to limit results (value 0 is used for get all records).
int	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 "]").
int	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
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

Search(string, string, int, int, int)

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.
int	offset	The index from which to get results.
int	limit	The number to limit results (value 0 is used for get all records).
int	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
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

Search(string, string, int, int, string, string, int)

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.
int	offset	The index from which to get results.
int	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 "]")
int	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
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

Search(string, string, int, int)

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.
int	offset	The index from which to get results.
int	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
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

Search(ContactsQuery, string, int, int, string, string, int)

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.
int	offset	The index from which to get results.
int	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 "]".)
int	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
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

Search(ContactsQuery, string, int, int)

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.
int	offset	The index from which to get results.
int	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
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

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.

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

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.

Remarks

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

Exceptions

Type	Condition
System.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.
System.OutOfMemoryException	Thrown when failed due to out of memory.
System.UnauthorizedAccessException	Thrown when the application does not have proper privileges.

Events

DBStatusChanged

Occurs when the contacts database status is changed.

Declaration

public event EventHandler<DBStatusChangedEventArgs> DBStatusChanged

Event Type

Type	Description
System.EventHandler<TEventArgs><DBStatusChangedEventArgs>

Remarks

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