2 * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the License);
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an AS IS BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 using System.Collections.Generic;
19 using System.Diagnostics.CodeAnalysis;
20 using System.Runtime.InteropServices;
22 namespace Tizen.Pims.Contacts
25 /// Delegate for detecting the contacts database changes
27 /// <param name="uri">The contacts view URI</param>
29 /// The delegate must be registered using AddDBChangedDelegate.
30 /// It's invoked when the designated view changes.
32 public delegate void ContactsDBChanged(string uri);
35 /// ContactsDatabase provides methods to manage contacts information from/to the database.
38 /// This class allows user to access/create/update db operations for contacts information.
40 public class ContactsDatabase
42 private Object thisLock = new Object();
43 private Interop.Database.ContactsDBStatusChangedCallback _contactsDBStatusChangedCallback;
44 private EventHandler<DBStatusChangedEventArgs> _dbStatusChanged;
45 private Dictionary<string, ContactsDBChanged> _delegateMap = new Dictionary<string, ContactsDBChanged>();
46 private Dictionary<string, Interop.Database.ContactsDBChangedCallback> _callbackMap = new Dictionary<string, Interop.Database.ContactsDBChangedCallback>();
47 private Interop.Database.ContactsDBChangedCallback _dbChangedDelegate;
49 internal ContactsDatabase()
51 /*To be created in ContactsManager only.*/
55 /// Enumeration for contacts database status.
64 /// Changing collation.
70 /// Enumeration for Contacts search range.
73 public enum SearchRanges
80 /// Search record from name
84 /// Search record from number
88 /// Search record from data
92 /// Search record from email. Now, support only PersonEmail view
98 /// Occurs when contacts database status is changed.
100 public event EventHandler<DBStatusChangedEventArgs> DBStatusChanged
106 if (_contactsDBStatusChangedCallback == null)
108 _contactsDBStatusChangedCallback = (DBStatus status, IntPtr userData) =>
110 DBStatusChangedEventArgs args = new DBStatusChangedEventArgs(status);
111 _dbStatusChanged?.Invoke(this, args);
115 if (_dbStatusChanged == null)
117 int error = Interop.Database.AddStatusChangedCb(_contactsDBStatusChangedCallback, IntPtr.Zero);
118 if ((int)ContactsError.None != error)
120 Log.Error(Globals.LogTag, "Add StatusChanged Failed with error " + error);
124 _dbStatusChanged += value;
133 _dbStatusChanged -= value;
135 if (_dbStatusChanged == null)
137 int error = Interop.Database.RemoveStatusChangedCb(_contactsDBStatusChangedCallback, IntPtr.Zero);
138 if ((int)ContactsError.None != error)
140 Log.Error(Globals.LogTag, "Remove StatusChanged Failed with error " + error);
149 /// The current contacts database version.
151 /// <value>The current contacts database version.</value>
152 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
158 int error = Interop.Database.GetVersion(out version);
159 if ((int)ContactsError.None != error)
161 Log.Error(Globals.LogTag, "Version Failed with error " + error);
168 /// The last successful changed contacts database version on the current connection.
170 /// <value>The last successful changed contacts database version on the current connection.</value>
171 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
172 public int LastChangeVersion
177 int error = Interop.Database.GetLastChangeVersion(out version);
178 if ((int)ContactsError.None != error)
180 Log.Error(Globals.LogTag, "LastChangeVersion Failed with error " + error);
187 /// The contacts database status.
189 /// <value>The contacts database status.</value>
190 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
191 public DBStatus Status
195 DBStatus status = DBStatus.Normal;
196 int error = Interop.Database.GetStatus(out status);
197 if ((int)ContactsError.None != error)
199 Log.Error(Globals.LogTag, "GetStatus Failed with error " + error);
206 /// Inserts a record into the contacts database.
208 /// <param name="record">The record to insert</param>
209 /// <returns>The ID of inserted record</returns>
210 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
211 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
212 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
213 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
214 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
215 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
216 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
217 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
218 public int Insert(ContactsRecord record)
221 int error = Interop.Database.Insert(record._recordHandle, out id);
222 if ((int)ContactsError.None != error)
224 Log.Error(Globals.LogTag, "Insert Failed with error " + error);
225 throw ContactsErrorFactory.CheckAndCreateException(error);
231 /// Inserts multiple records into the contacts database as a batch operation.
233 /// <param name="list">The record list</param>
234 /// <returns>The inserted record ID array</returns>
235 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
236 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
237 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
238 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
239 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
240 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
241 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
242 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
243 public int[] Insert(ContactsList list)
247 int error = Interop.Database.InsertRecords(list._listHandle, out ids, out count);
248 if ((int)ContactsError.None != error)
250 Log.Error(Globals.LogTag, "Insert Failed with error " + error);
251 throw ContactsErrorFactory.CheckAndCreateException(error);
254 int[] idArr = new int[count];
255 Marshal.Copy(ids, idArr, 0, count);
261 /// Gets a record from the contacts database.
263 /// <param name="viewUri">The view URI of a record</param>
264 /// <param name="recordId">The record ID</param>
265 /// <returns>The record associated with the record ID</returns>
266 /// <privilege>http://tizen.org/privilege/contact.read</privilege>
267 /// <privilege>http://tizen.org/privilege/callhistory.read</privilege>
268 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
269 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
270 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
271 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
272 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
273 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
274 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
275 public ContactsRecord Get(string viewUri, int recordId)
278 int error = Interop.Database.Get(viewUri, recordId, out handle);
279 if ((int)ContactsError.None != error)
281 Log.Error(Globals.LogTag, "Get Failed with error " + error);
282 throw ContactsErrorFactory.CheckAndCreateException(error);
284 return new ContactsRecord(handle);
288 /// Updates a record in the contacts database.
290 /// <param name="record">The record to update</param>
291 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
292 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
293 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
294 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
295 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
296 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
297 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
298 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
299 public void Update(ContactsRecord record)
301 int error = Interop.Database.Update(record._recordHandle);
302 if ((int)ContactsError.None != error)
304 Log.Error(Globals.LogTag, "Update Failed with error " + error);
305 throw ContactsErrorFactory.CheckAndCreateException(error);
310 /// Updates multiple records in the contacts database as a batch operation.
312 /// <param name="list">The record list</param>
313 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
314 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
315 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
316 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
317 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
318 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
319 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
320 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
321 public void Update(ContactsList list)
323 int error = Interop.Database.UpdateRecords(list._listHandle);
324 if ((int)ContactsError.None != error)
326 Log.Error(Globals.LogTag, "Update Failed with error " + error);
327 throw ContactsErrorFactory.CheckAndCreateException(error);
332 /// Deletes a record from the contacts database with related child records.
334 /// <param name="viewUri">The view URI of a record</param>
335 /// <param name="recordId">The record ID to delete</param>
336 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
337 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
338 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
339 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
340 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
341 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
342 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
343 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
344 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
345 public void Delete(string viewUri, int recordId)
347 int error = Interop.Database.Delete(viewUri, recordId);
348 if ((int)ContactsError.None != error)
350 Log.Error(Globals.LogTag, "Delete Failed with error " + error);
351 throw ContactsErrorFactory.CheckAndCreateException(error);
356 /// Deletes multiple records with related child records from the contacts database as a batch operation.
358 /// <param name="viewUri">The view URI of the records to delete</param>
359 /// <param name="idArray">The record IDs to delete</param>
360 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
361 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
362 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
363 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
364 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
365 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
366 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
367 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
368 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
369 public void Delete(string viewUri, int[] idArray)
371 int error = Interop.Database.DeleteRecords(viewUri, idArray, idArray.Length);
372 if ((int)ContactsError.None != error)
374 Log.Error(Globals.LogTag, "Delete Failed with error " + error);
375 throw ContactsErrorFactory.CheckAndCreateException(error);
380 /// Replaces a record in the contacts database.
382 /// <param name="record">The record to replace</param>
383 /// <param name="recordId">the record ID to be replaced</param>
384 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
385 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
386 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
387 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
388 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
389 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
390 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
391 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
392 public void Replace(ContactsRecord record, int recordId)
394 int error = Interop.Database.Replace(record._recordHandle, recordId);
395 if ((int)ContactsError.None != error)
397 Log.Error(Globals.LogTag, "Replace Failed with error " + error);
398 throw ContactsErrorFactory.CheckAndCreateException(error);
403 /// Replaces multiple records in the contacts database as a batch operation.
405 /// <param name="list">The record list to replace</param>
406 /// <param name="idArray">The record IDs to be replaced</param>
407 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
408 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
409 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
410 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
411 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
412 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
413 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
414 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
415 public void Replace(ContactsList list, int[] idArray)
417 int error = Interop.Database.ReplaceRecords(list._listHandle, idArray, idArray.Length);
418 if ((int)ContactsError.None != error)
420 Log.Error(Globals.LogTag, "Replace Failed with error " + error);
421 throw ContactsErrorFactory.CheckAndCreateException(error);
426 /// Retrieves all records as a list.
428 /// <param name="viewUri">The view URI to get records</param>
429 /// <param name="offset">The index from which results</param>
430 /// <param name="limit">The number to limit results(value 0 is used for all records)</param>
434 /// <privilege>http://tizen.org/privilege/contact.read</privilege>
435 /// <privilege>http://tizen.org/privilege/callhistory.read</privilege>
436 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
437 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
438 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
439 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
440 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
441 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
442 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
443 public ContactsList GetAll(string viewUri, int offset, int limit)
446 int error = Interop.Database.GetRecords(viewUri, offset, limit, out handle);
447 if ((int)ContactsError.None != error)
449 Log.Error(Globals.LogTag, "GetAll Failed with error " + error);
450 throw ContactsErrorFactory.CheckAndCreateException(error);
452 return new ContactsList(handle);
456 /// Retrieves records using a query.
458 /// <param name="query">The query to filter the results</param>
459 /// <param name="offset">The index from which to get results</param>
460 /// <param name="limit">The number to limit results(value 0 is used for get all records)</param>
464 /// <privilege>http://tizen.org/privilege/contact.read</privilege>
465 /// <privilege>http://tizen.org/privilege/callhistory.read</privilege>
466 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
467 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
468 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
469 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
470 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
471 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
472 public ContactsList GetRecordsWithQuery(ContactsQuery query, int offset, int limit)
475 int error = Interop.Database.GetRecords(query._queryHandle, offset, limit, out handle);
476 if ((int)ContactsError.None != error)
478 Log.Error(Globals.LogTag, "GetAllWithQuery Failed with error " + error);
479 throw ContactsErrorFactory.CheckAndCreateException(error);
481 return new ContactsList(handle);
485 /// Retrieves records changes since the given database version.
487 /// <param name="viewUri">The view URI to get records</param>
488 /// <param name="addressBookId">The address book ID to filter</param>
489 /// <param name="contactsDBVersion">The contacts database version</param>
490 /// <param name="currentDBVersion">The current contacts database version</param>
494 /// <privilege>http://tizen.org/privilege/contact.read</privilege>
495 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
496 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
497 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
498 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
499 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
500 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
501 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
502 public ContactsList GetChangesByVersion(string viewUri, int addressBookId, int contactsDBVersion, out int currentDBVersion)
505 int error = Interop.Database.GetChangesByVersion(viewUri, addressBookId, contactsDBVersion, out recordList,out currentDBVersion);
506 if ((int)ContactsError.None != error)
508 Log.Error(Globals.LogTag, "GetChangesByVersion Failed with error " + error);
509 throw ContactsErrorFactory.CheckAndCreateException(error);
511 return new ContactsList(recordList);
515 /// Finds records based on a given keyword.
518 /// This API works only for the Views below.
519 /// Person, PersonContact, PersonGroupRelation, PersonGroupAssigned and PersonGroupNotAssigned.
521 /// <param name="viewUri">The view URI to find records</param>
522 /// <param name="keyword">The keyword</param>
523 /// <param name="offset">The index from which to get results</param>
524 /// <param name="limit">The number to limit results(value 0 is used for get all records)</param>
525 /// <returns>The record list</returns>
526 /// <privilege>http://tizen.org/privilege/contact.read</privilege>
527 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
528 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
529 public ContactsList Search(string viewUri, string keyword, int offset, int limit)
532 int error = Interop.Database.Search(viewUri, keyword, offset, limit, out recordList);
533 if ((int)ContactsError.None != error)
535 Log.Error(Globals.LogTag, "Search Failed with error " + error);
536 throw ContactsErrorFactory.CheckAndCreateException(error);
538 return new ContactsList(recordList);
542 /// Finds records based on given query and keyword.
545 /// This API works only for the Views below.
546 /// Person, PersonContact, PersonGroupRelation, PersonGroupAssigned and PersonGroupNotAssigned.
548 /// <param name="query">The query to filter</param>
549 /// <param name="keyword">The keyword</param>
550 /// <param name="offset">The index from which to get results</param>
551 /// <param name="limit">The number to limit results(value 0 used for get all records)</param>
552 /// <returns>The record list</returns>
553 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
554 public ContactsList Search(ContactsQuery query, string keyword, int offset, int limit)
557 int error = Interop.Database.Search(query._queryHandle, keyword, offset, limit, out recordList);
558 if ((int)ContactsError.None != error)
560 Log.Error(Globals.LogTag, "Search Failed with error " + error);
561 throw ContactsErrorFactory.CheckAndCreateException(error);
563 return new ContactsList(recordList);
567 /// Finds records based on a keyword and range.
570 /// This API works only for the Views below.
571 /// Person, PersonContact, PersonGroupRelation, PersonGroupAssigned, PersonGroupNotAssigned, PersonNumber and PersonEmail
573 /// <param name="viewUri">The view URI</param>
574 /// <param name="keyword">The keyword</param>
575 /// <param name="offset">The index from which to get results</param>
576 /// <param name="limit">The number to limit results(value 0 is used for get all records)</param>
577 /// <param name="range">The search range, it should be a element of SearchRange or bitwise OR operation of them</param>
578 /// <returns>The record list</returns>
579 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
580 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
581 public ContactsList Search(string viewUri, string keyword, int offset, int limit, int range)
584 int error = Interop.Database.Search(viewUri, keyword, offset, limit, range, out recordList);
585 if ((int)ContactsError.None != error)
587 Log.Error(Globals.LogTag, "Search Failed with error " + error);
588 throw ContactsErrorFactory.CheckAndCreateException(error);
590 return new ContactsList(recordList);
594 /// Finds records based on a given keyword for snippet
597 /// This API works only for the Views below.
598 /// Person, PersonContact, PersonGroupRelation, PersonGroupAssigned and PersonGroupNotAssigned.
599 /// Because start match and end match are needed to be composed with keyword, this API performance is lower than Search(string viewUri, string keyword, int offset, int limit).
601 /// <param name="viewUri">The view URI to find records</param>
602 /// <param name="keyword">The keyword</param>
603 /// <param name="offset">The index from which to get results</param>
604 /// <param name="limit">The number to limit results(value 0 used for get all records)</param>
605 /// <param name="startMatch">The text which is inserted into the fragment before the keyword(If NULL, default is "[")</param>
606 /// <param name="endMatch">The text which is inserted into the fragment after the keyword(If NULL, default is "]")</param>
607 /// <param name="tokenNumber">The one side extra number of tokens near keyword(If negative value, full sentence is printed. e.g. if token number is 3 with 'abc' keyword, "my name is [abc]de and my home")</param>
608 /// <returns>The record list</returns>
609 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
610 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
611 public ContactsList Search(string viewUri, string keyword, int offset, int limit, string startMatch, string endMatch, int tokenNumber)
614 int error = Interop.Database.Search(viewUri, keyword, offset, limit, startMatch, endMatch, tokenNumber, out recordList);
615 if ((int)ContactsError.None != error)
617 Log.Error(Globals.LogTag, "Search Failed with error " + error);
618 throw ContactsErrorFactory.CheckAndCreateException(error);
620 return new ContactsList(recordList);
624 /// Finds records based on given query and keyword for snippet.
627 /// This API works only for the Views below.
628 /// Person, PersonContact, PersonGroupRelation, PersonGroupAssigned and PersonGroupNotAssigned.
629 /// Because start match and end match are needed to be composed with keyword, this API performance is lower than Search(ContactsQuery query, string keyword, int offset, int limit).
631 /// <param name="query">The query to filter</param>
632 /// <param name="keyword">The keyword</param>
633 /// <param name="offset">The index from which to get results</param>
634 /// <param name="limit">The number to limit results(value 0 used for get all records)</param>
635 /// <param name="startMatch">The text which is inserted into the fragment before the keyword(If NULL, default is "[")</param>
636 /// <param name="endMatch">The text which is inserted into the fragment after the keyword(If NULL, default is "]")</param>
637 /// <param name="tokenNumber">The one side extra number of tokens near keyword(If negative value, full sentence is printed. e.g. if token number is 3 with 'abc' keyword, "my name is [abc]de and my home")</param>
638 /// <returns>The record list</returns>
639 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
640 public ContactsList Search(ContactsQuery query, string keyword, int offset, int limit, string startMatch, string endMatch, int tokenNumber)
643 int error = Interop.Database.Search(query._queryHandle, keyword, offset, limit, startMatch, endMatch, tokenNumber, out recordList);
644 if ((int)ContactsError.None != error)
646 Log.Error(Globals.LogTag, "Search Failed with error " + error);
647 throw ContactsErrorFactory.CheckAndCreateException(error);
649 return new ContactsList(recordList);
653 /// Finds records based on a keyword and range for snippet.
656 /// This API works only for the Views below.
657 /// Person, PersonContact, PersonGroupRelation, PersonGroupAssigned, PersonGroupNotAssigned, PersonNumber and PersonEmail
658 /// Because start match and end match are needed to be composed with keyword, this API performance is lower than Search(string viewUri, string keyword, int offset, int limit, int range).
660 /// <param name="viewUri">The view URI</param>
661 /// <param name="keyword">The keyword</param>
662 /// <param name="offset">The index from which to get results</param>
663 /// <param name="limit">The number to limit results(value 0 is used for get all records)</param>
664 /// <param name="range">The search range, it should be a element of SearchRange or bitwise OR operation of them</param>
665 /// <param name="startMatch">The text which is inserted into the fragment before the keyword(If NULL, default is "[")</param>
666 /// <param name="endMatch">The text which is inserted into the fragment after the keyword(If NULL, default is "]")</param>
667 /// <param name="tokenNumber">The one side extra number of tokens near keyword(If negative value, full sentence is printed. e.g. if token number is 3 with 'abc' keyword, "my name is [abc]de and my home")</param>
668 /// <returns>The record list</returns>
669 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
670 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
671 public ContactsList Search(string viewUri, string keyword, int offset, int limit, int range, string startMatch, string endMatch, int tokenNumber)
674 int error = Interop.Database.Search(viewUri, keyword, offset, limit, range, startMatch, endMatch, tokenNumber, out recordList);
675 if ((int)ContactsError.None != error)
677 Log.Error(Globals.LogTag, "Search Failed with error " + error);
678 throw ContactsErrorFactory.CheckAndCreateException(error);
680 return new ContactsList(recordList);
684 /// Gets the number of records in a specific view
686 /// <param name="viewUri">The view URI</param>
687 /// <returns>The count of records</returns>
688 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
689 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
690 public int GetCount(string viewUri)
693 int error = Interop.Database.GetCount(viewUri, out count);
694 if ((int)ContactsError.None != error)
696 Log.Error(Globals.LogTag, "GetCount Failed with error " + error);
697 throw ContactsErrorFactory.CheckAndCreateException(error);
703 /// Gets the number of records matching a query.
705 /// <param name="query">The query used for filtering the results</param>
706 /// <returns>The count of records</returns>
707 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
708 public int GetCount(ContactsQuery query)
711 int error = Interop.Database.GetCount(query._queryHandle, out count);
712 if ((int)ContactsError.None != error)
714 Log.Error(Globals.LogTag, "GetCount Failed with error " + error);
715 throw ContactsErrorFactory.CheckAndCreateException(error);
721 /// Registers a callback function to be invoked when a record changes.
723 /// <param name="viewUri">The view URI of records whose changes are monitored</param>
724 /// <param name="callback">The callback function to register</param>
725 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
726 public void AddDBChangedDelegate(string viewUri, ContactsDBChanged callback)
728 if (_callbackMap[viewUri] == null)
730 _callbackMap[viewUri] = (string uri, IntPtr userData) =>
732 _delegateMap[uri](uri);
735 int error = Interop.Database.AddChangedCb(viewUri, _callbackMap[viewUri], IntPtr.Zero);
736 if ((int)ContactsError.None != error)
738 Log.Error(Globals.LogTag, "AddDBChangedDelegate Failed with error " + error);
739 throw ContactsErrorFactory.CheckAndCreateException(error);
743 _delegateMap[viewUri] += callback;
747 /// Deregisters a callback function.
749 /// <param name="viewUri">The view URI of records whose changes are monitored</param>
750 /// <param name="callback">The callback function to register</param>
751 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
752 public void RemoveDBChangedDelegate(string viewUri, ContactsDBChanged callback)
754 _delegateMap[viewUri] -= callback;
756 if (_delegateMap[viewUri] == null)
758 int error = Interop.Database.RemoveChangedCb(viewUri, _callbackMap[viewUri], IntPtr.Zero);
759 if ((int)ContactsError.None != error)
761 Log.Error(Globals.LogTag, "RemoveDBChangedDelegate Failed with error " + error);
762 throw ContactsErrorFactory.CheckAndCreateException(error);
764 _callbackMap.Remove(viewUri);