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
26 /// ContactsDatabase provides methods to manage contacts information from/to the database.
29 /// This class allows user to access/create/update db operations for contacts information.
31 public class ContactsDatabase
33 private Object thisLock = new Object();
34 private Interop.Database.ContactsDBStatusChangedCallback _contactsDBStatusChangedCallback;
35 private EventHandler<DBStatusChangedEventArgs> _dbStatusChanged;
36 private Dictionary<string, EventHandler<DBChangedEventArgs>> _eventHandlerMap = new Dictionary<string, EventHandler<DBChangedEventArgs>>();
37 private Dictionary<string, Interop.Database.ContactsDBChangedCallback> _callbackMap = new Dictionary<string, Interop.Database.ContactsDBChangedCallback>();
39 internal ContactsDatabase()
41 /*To be created in ContactsManager only.*/
45 /// Enumeration for contacts database status.
54 /// Changing collation.
60 /// Enumeration for Contacts search range.
63 public enum SearchRanges
70 /// Search record from name
74 /// Search record from number
78 /// Search record from data
82 /// Search record from email. Now, support only PersonEmail view
88 /// Occurs when contacts database status is changed.
90 public event EventHandler<DBStatusChangedEventArgs> DBStatusChanged
96 if (_contactsDBStatusChangedCallback == null)
98 _contactsDBStatusChangedCallback = (DBStatus status, IntPtr userData) =>
100 DBStatusChangedEventArgs args = new DBStatusChangedEventArgs(status);
101 _dbStatusChanged?.Invoke(this, args);
105 if (_dbStatusChanged == null)
107 int error = Interop.Database.AddStatusChangedCb(_contactsDBStatusChangedCallback, IntPtr.Zero);
108 if ((int)ContactsError.None != error)
110 Log.Error(Globals.LogTag, "Add StatusChanged Failed with error " + error);
114 _dbStatusChanged += value;
123 _dbStatusChanged -= value;
125 if (_dbStatusChanged == null)
127 int error = Interop.Database.RemoveStatusChangedCb(_contactsDBStatusChangedCallback, IntPtr.Zero);
128 if ((int)ContactsError.None != error)
130 Log.Error(Globals.LogTag, "Remove StatusChanged Failed with error " + error);
139 /// The current contacts database version.
141 /// <value>The current contacts database version.</value>
142 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
148 int error = Interop.Database.GetVersion(out version);
149 if ((int)ContactsError.None != error)
151 Log.Error(Globals.LogTag, "Version Failed with error " + error);
158 /// The last successful changed contacts database version on the current connection.
160 /// <value>The last successful changed contacts database version on the current connection.</value>
161 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
162 public int LastChangeVersion
167 int error = Interop.Database.GetLastChangeVersion(out version);
168 if ((int)ContactsError.None != error)
170 Log.Error(Globals.LogTag, "LastChangeVersion Failed with error " + error);
177 /// The contacts database status.
179 /// <value>The contacts database status.</value>
180 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
181 public DBStatus Status
185 DBStatus status = DBStatus.Normal;
186 int error = Interop.Database.GetStatus(out status);
187 if ((int)ContactsError.None != error)
189 Log.Error(Globals.LogTag, "GetStatus Failed with error " + error);
196 /// Inserts a record into the contacts database.
198 /// <param name="record">The record to insert</param>
199 /// <returns>The ID of inserted record</returns>
200 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
201 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
202 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
203 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
204 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
205 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
206 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
207 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
208 public int Insert(ContactsRecord record)
211 int error = Interop.Database.Insert(record._recordHandle, out id);
212 if ((int)ContactsError.None != error)
214 Log.Error(Globals.LogTag, "Insert Failed with error " + error);
215 throw ContactsErrorFactory.CheckAndCreateException(error);
221 /// Inserts multiple records into the contacts database as a batch operation.
223 /// <param name="list">The record list</param>
224 /// <returns>The inserted record ID array</returns>
225 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
226 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
227 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
228 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
229 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
230 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
231 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
232 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
233 public int[] Insert(ContactsList list)
237 int error = Interop.Database.InsertRecords(list._listHandle, out ids, out count);
238 if ((int)ContactsError.None != error)
240 Log.Error(Globals.LogTag, "Insert Failed with error " + error);
241 throw ContactsErrorFactory.CheckAndCreateException(error);
244 int[] idArr = new int[count];
245 Marshal.Copy(ids, idArr, 0, count);
251 /// Gets a record from the contacts database.
253 /// <param name="viewUri">The view URI of a record</param>
254 /// <param name="recordId">The record ID</param>
255 /// <returns>The record associated with the record ID</returns>
256 /// <privilege>http://tizen.org/privilege/contact.read</privilege>
257 /// <privilege>http://tizen.org/privilege/callhistory.read</privilege>
258 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
259 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
260 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
261 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
262 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
263 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
264 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
265 public ContactsRecord Get(string viewUri, int recordId)
268 int error = Interop.Database.Get(viewUri, recordId, out handle);
269 if ((int)ContactsError.None != error)
271 Log.Error(Globals.LogTag, "Get Failed with error " + error);
272 throw ContactsErrorFactory.CheckAndCreateException(error);
274 return new ContactsRecord(handle);
278 /// Updates a record in the contacts database.
280 /// <param name="record">The record to update</param>
281 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
282 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
283 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
284 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
285 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
286 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
287 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
288 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
289 public void Update(ContactsRecord record)
291 int error = Interop.Database.Update(record._recordHandle);
292 if ((int)ContactsError.None != error)
294 Log.Error(Globals.LogTag, "Update Failed with error " + error);
295 throw ContactsErrorFactory.CheckAndCreateException(error);
300 /// Updates multiple records in the contacts database as a batch operation.
302 /// <param name="list">The record list</param>
303 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
304 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
305 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
306 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
307 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
308 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
309 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
310 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
311 public void Update(ContactsList list)
313 int error = Interop.Database.UpdateRecords(list._listHandle);
314 if ((int)ContactsError.None != error)
316 Log.Error(Globals.LogTag, "Update Failed with error " + error);
317 throw ContactsErrorFactory.CheckAndCreateException(error);
322 /// Deletes a record from the contacts database with related child records.
324 /// <param name="viewUri">The view URI of a record</param>
325 /// <param name="recordId">The record ID to delete</param>
326 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
327 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
328 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
329 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
330 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
331 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
332 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
333 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
334 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
335 public void Delete(string viewUri, int recordId)
337 int error = Interop.Database.Delete(viewUri, recordId);
338 if ((int)ContactsError.None != error)
340 Log.Error(Globals.LogTag, "Delete Failed with error " + error);
341 throw ContactsErrorFactory.CheckAndCreateException(error);
346 /// Deletes multiple records with related child records from the contacts database as a batch operation.
348 /// <param name="viewUri">The view URI of the records to delete</param>
349 /// <param name="idArray">The record IDs to delete</param>
350 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
351 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
352 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
353 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
354 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
355 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
356 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
357 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
358 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
359 public void Delete(string viewUri, int[] idArray)
361 int error = Interop.Database.DeleteRecords(viewUri, idArray, idArray.Length);
362 if ((int)ContactsError.None != error)
364 Log.Error(Globals.LogTag, "Delete Failed with error " + error);
365 throw ContactsErrorFactory.CheckAndCreateException(error);
370 /// Replaces a record in the contacts database.
372 /// <param name="record">The record to replace</param>
373 /// <param name="recordId">the record ID to be replaced</param>
374 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
375 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
376 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
377 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
378 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
379 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
380 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
381 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
382 public void Replace(ContactsRecord record, int recordId)
384 int error = Interop.Database.Replace(record._recordHandle, recordId);
385 if ((int)ContactsError.None != error)
387 Log.Error(Globals.LogTag, "Replace Failed with error " + error);
388 throw ContactsErrorFactory.CheckAndCreateException(error);
393 /// Replaces multiple records in the contacts database as a batch operation.
395 /// <param name="list">The record list to replace</param>
396 /// <param name="idArray">The record IDs to be replaced</param>
397 /// <privilege>http://tizen.org/privilege/contact.write</privilege>
398 /// <privilege>http://tizen.org/privilege/callhistory.write</privilege>
399 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
400 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
401 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
402 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
403 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
404 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
405 public void Replace(ContactsList list, int[] idArray)
407 int error = Interop.Database.ReplaceRecords(list._listHandle, idArray, idArray.Length);
408 if ((int)ContactsError.None != error)
410 Log.Error(Globals.LogTag, "Replace Failed with error " + error);
411 throw ContactsErrorFactory.CheckAndCreateException(error);
416 /// Retrieves all records as a list.
418 /// <param name="viewUri">The view URI to get records</param>
419 /// <param name="offset">The index from which results</param>
420 /// <param name="limit">The number to limit results(value 0 is used for all records)</param>
424 /// <privilege>http://tizen.org/privilege/contact.read</privilege>
425 /// <privilege>http://tizen.org/privilege/callhistory.read</privilege>
426 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
427 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
428 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
429 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
430 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
431 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
432 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
433 public ContactsList GetAll(string viewUri, int offset, int limit)
436 int error = Interop.Database.GetRecords(viewUri, offset, limit, out handle);
437 if ((int)ContactsError.None != error)
439 Log.Error(Globals.LogTag, "GetAll Failed with error " + error);
440 throw ContactsErrorFactory.CheckAndCreateException(error);
442 return new ContactsList(handle);
446 /// Retrieves records using a query.
448 /// <param name="query">The query to filter the results</param>
449 /// <param name="offset">The index from which to get results</param>
450 /// <param name="limit">The number to limit results(value 0 is used for get all records)</param>
454 /// <privilege>http://tizen.org/privilege/contact.read</privilege>
455 /// <privilege>http://tizen.org/privilege/callhistory.read</privilege>
456 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
457 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
458 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
459 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
460 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
461 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
462 public ContactsList GetRecordsWithQuery(ContactsQuery query, int offset, int limit)
465 int error = Interop.Database.GetRecords(query._queryHandle, offset, limit, out handle);
466 if ((int)ContactsError.None != error)
468 Log.Error(Globals.LogTag, "GetAllWithQuery Failed with error " + error);
469 throw ContactsErrorFactory.CheckAndCreateException(error);
471 return new ContactsList(handle);
475 /// Retrieves records changes since the given database version.
477 /// <param name="viewUri">The view URI to get records</param>
478 /// <param name="addressBookId">The address book ID to filter</param>
479 /// <param name="contactsDBVersion">The contacts database version</param>
480 /// <param name="currentDBVersion">The current contacts database version</param>
484 /// <privilege>http://tizen.org/privilege/contact.read</privilege>
485 /// <exception cref="InvalidOperationException">Thrown when method failed due to invalid operation</exception>
486 /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
487 /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
488 /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
489 /// <exception cref="UnauthorizedAccessException">Thrown when application does not have proper privileges</exception>
490 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
491 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
492 public ContactsList GetChangesByVersion(string viewUri, int addressBookId, int contactsDBVersion, out int currentDBVersion)
495 int error = Interop.Database.GetChangesByVersion(viewUri, addressBookId, contactsDBVersion, out recordList,out currentDBVersion);
496 if ((int)ContactsError.None != error)
498 Log.Error(Globals.LogTag, "GetChangesByVersion Failed with error " + error);
499 throw ContactsErrorFactory.CheckAndCreateException(error);
501 return new ContactsList(recordList);
505 /// Finds records based on a given keyword.
508 /// This API works only for the Views below.
509 /// Person, PersonContact, PersonGroupRelation, PersonGroupAssigned and PersonGroupNotAssigned.
511 /// <param name="viewUri">The view URI to find records</param>
512 /// <param name="keyword">The keyword</param>
513 /// <param name="offset">The index from which to get results</param>
514 /// <param name="limit">The number to limit results(value 0 is used for get all records)</param>
515 /// <returns>The record list</returns>
516 /// <privilege>http://tizen.org/privilege/contact.read</privilege>
517 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
518 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
519 public ContactsList Search(string viewUri, string keyword, int offset, int limit)
522 int error = Interop.Database.Search(viewUri, keyword, offset, limit, out recordList);
523 if ((int)ContactsError.None != error)
525 Log.Error(Globals.LogTag, "Search Failed with error " + error);
526 throw ContactsErrorFactory.CheckAndCreateException(error);
528 return new ContactsList(recordList);
532 /// Finds records based on given query and keyword.
535 /// This API works only for the Views below.
536 /// Person, PersonContact, PersonGroupRelation, PersonGroupAssigned and PersonGroupNotAssigned.
538 /// <param name="query">The query to filter</param>
539 /// <param name="keyword">The keyword</param>
540 /// <param name="offset">The index from which to get results</param>
541 /// <param name="limit">The number to limit results(value 0 used for get all records)</param>
542 /// <returns>The record list</returns>
543 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
544 public ContactsList Search(ContactsQuery query, string keyword, int offset, int limit)
547 int error = Interop.Database.Search(query._queryHandle, keyword, offset, limit, out recordList);
548 if ((int)ContactsError.None != error)
550 Log.Error(Globals.LogTag, "Search Failed with error " + error);
551 throw ContactsErrorFactory.CheckAndCreateException(error);
553 return new ContactsList(recordList);
557 /// Finds records based on a keyword and range.
560 /// This API works only for the Views below.
561 /// Person, PersonContact, PersonGroupRelation, PersonGroupAssigned, PersonGroupNotAssigned, PersonNumber and PersonEmail
563 /// <param name="viewUri">The view URI</param>
564 /// <param name="keyword">The keyword</param>
565 /// <param name="offset">The index from which to get results</param>
566 /// <param name="limit">The number to limit results(value 0 is used for get all records)</param>
567 /// <param name="range">The search range, it should be a element of SearchRange or bitwise OR operation of them</param>
568 /// <returns>The record list</returns>
569 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
570 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
571 public ContactsList Search(string viewUri, string keyword, int offset, int limit, int range)
574 int error = Interop.Database.Search(viewUri, keyword, offset, limit, range, out recordList);
575 if ((int)ContactsError.None != error)
577 Log.Error(Globals.LogTag, "Search Failed with error " + error);
578 throw ContactsErrorFactory.CheckAndCreateException(error);
580 return new ContactsList(recordList);
584 /// Finds records based on a given keyword for snippet
587 /// This API works only for the Views below.
588 /// Person, PersonContact, PersonGroupRelation, PersonGroupAssigned and PersonGroupNotAssigned.
589 /// 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).
591 /// <param name="viewUri">The view URI to find records</param>
592 /// <param name="keyword">The keyword</param>
593 /// <param name="offset">The index from which to get results</param>
594 /// <param name="limit">The number to limit results(value 0 used for get all records)</param>
595 /// <param name="startMatch">The text which is inserted into the fragment before the keyword(If NULL, default is "[")</param>
596 /// <param name="endMatch">The text which is inserted into the fragment after the keyword(If NULL, default is "]")</param>
597 /// <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>
598 /// <returns>The record list</returns>
599 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
600 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
601 public ContactsList Search(string viewUri, string keyword, int offset, int limit, string startMatch, string endMatch, int tokenNumber)
604 int error = Interop.Database.Search(viewUri, keyword, offset, limit, startMatch, endMatch, tokenNumber, out recordList);
605 if ((int)ContactsError.None != error)
607 Log.Error(Globals.LogTag, "Search Failed with error " + error);
608 throw ContactsErrorFactory.CheckAndCreateException(error);
610 return new ContactsList(recordList);
614 /// Finds records based on given query and keyword for snippet.
617 /// This API works only for the Views below.
618 /// Person, PersonContact, PersonGroupRelation, PersonGroupAssigned and PersonGroupNotAssigned.
619 /// 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).
621 /// <param name="query">The query to filter</param>
622 /// <param name="keyword">The keyword</param>
623 /// <param name="offset">The index from which to get results</param>
624 /// <param name="limit">The number to limit results(value 0 used for get all records)</param>
625 /// <param name="startMatch">The text which is inserted into the fragment before the keyword(If NULL, default is "[")</param>
626 /// <param name="endMatch">The text which is inserted into the fragment after the keyword(If NULL, default is "]")</param>
627 /// <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>
628 /// <returns>The record list</returns>
629 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
630 public ContactsList Search(ContactsQuery query, string keyword, int offset, int limit, string startMatch, string endMatch, int tokenNumber)
633 int error = Interop.Database.Search(query._queryHandle, keyword, offset, limit, startMatch, endMatch, tokenNumber, out recordList);
634 if ((int)ContactsError.None != error)
636 Log.Error(Globals.LogTag, "Search Failed with error " + error);
637 throw ContactsErrorFactory.CheckAndCreateException(error);
639 return new ContactsList(recordList);
643 /// Finds records based on a keyword and range for snippet.
646 /// This API works only for the Views below.
647 /// Person, PersonContact, PersonGroupRelation, PersonGroupAssigned, PersonGroupNotAssigned, PersonNumber and PersonEmail
648 /// 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).
650 /// <param name="viewUri">The view URI</param>
651 /// <param name="keyword">The keyword</param>
652 /// <param name="offset">The index from which to get results</param>
653 /// <param name="limit">The number to limit results(value 0 is used for get all records)</param>
654 /// <param name="range">The search range, it should be a element of SearchRange or bitwise OR operation of them</param>
655 /// <param name="startMatch">The text which is inserted into the fragment before the keyword(If NULL, default is "[")</param>
656 /// <param name="endMatch">The text which is inserted into the fragment after the keyword(If NULL, default is "]")</param>
657 /// <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>
658 /// <returns>The record list</returns>
659 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
660 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
661 public ContactsList Search(string viewUri, string keyword, int offset, int limit, int range, string startMatch, string endMatch, int tokenNumber)
664 int error = Interop.Database.Search(viewUri, keyword, offset, limit, range, startMatch, endMatch, tokenNumber, out recordList);
665 if ((int)ContactsError.None != error)
667 Log.Error(Globals.LogTag, "Search Failed with error " + error);
668 throw ContactsErrorFactory.CheckAndCreateException(error);
670 return new ContactsList(recordList);
674 /// Gets the number of records in a specific view
676 /// <param name="viewUri">The view URI</param>
677 /// <returns>The count of records</returns>
678 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
679 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
680 public int GetCount(string viewUri)
683 int error = Interop.Database.GetCount(viewUri, out count);
684 if ((int)ContactsError.None != error)
686 Log.Error(Globals.LogTag, "GetCount Failed with error " + error);
687 throw ContactsErrorFactory.CheckAndCreateException(error);
693 /// Gets the number of records matching a query.
695 /// <param name="query">The query used for filtering the results</param>
696 /// <returns>The count of records</returns>
697 [SuppressMessage("Microsoft.Performance", "CA1822:MarkMembersAsStatic")]
698 public int GetCount(ContactsQuery query)
701 int error = Interop.Database.GetCount(query._queryHandle, out count);
702 if ((int)ContactsError.None != error)
704 Log.Error(Globals.LogTag, "GetCount Failed with error " + error);
705 throw ContactsErrorFactory.CheckAndCreateException(error);
711 /// Registers a EventHandler to be invoked when a record changes.
713 /// <param name="viewUri">The view URI of records whose changes are monitored</param>
714 /// <param name="DBChanged">The EventHandler to register</param>
715 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
716 public void AddDBChangedEventHandler(string viewUri, EventHandler<DBChangedEventArgs> DBChanged)
718 if (!_callbackMap.ContainsKey(viewUri))
720 _callbackMap[viewUri] = (string uri, IntPtr userData) =>
722 DBChangedEventArgs args = new DBChangedEventArgs(uri);
723 _eventHandlerMap[uri]?.Invoke(this, args);
726 int error = Interop.Database.AddChangedCb(viewUri, _callbackMap[viewUri], IntPtr.Zero);
727 if ((int)ContactsError.None != error)
729 Log.Error(Globals.LogTag, "AddDBChangedEventHandler Failed with error " + error);
730 throw ContactsErrorFactory.CheckAndCreateException(error);
734 EventHandler<DBChangedEventArgs> handler = null;
735 if (!_eventHandlerMap.TryGetValue(viewUri, out handler))
736 _eventHandlerMap.Add(viewUri, null);
738 _eventHandlerMap[viewUri] = handler + DBChanged;
742 /// Deregisters a EventHandler.
744 /// <param name="viewUri">The view URI of records whose changes are monitored</param>
745 /// <param name="DBChanged">The EventHandler to deregister</param>
746 [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
747 public void RemoveDBChangedEventHandler(string viewUri, EventHandler<DBChangedEventArgs> DBChanged)
749 EventHandler<DBChangedEventArgs> handler = null;
750 if (!_eventHandlerMap.TryGetValue(viewUri, out handler))
751 _eventHandlerMap.Add(viewUri, null);
753 _eventHandlerMap[viewUri] = handler - DBChanged;
755 if (_eventHandlerMap[viewUri] == null)
757 int error = Interop.Database.RemoveChangedCb(viewUri, _callbackMap[viewUri], IntPtr.Zero);
758 if ((int)ContactsError.None != error)
760 Log.Error(Globals.LogTag, "RemoveDBChangedEventHandler Failed with error " + error);
761 throw ContactsErrorFactory.CheckAndCreateException(error);
763 _callbackMap.Remove(viewUri);