src/Tizen.Pims.Contacts/Tizen.Pims.Contacts/ContactsQuery.cs

   1 /*
   2 * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   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
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  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.
  15 */
  16
  17 using System;
  18 using static Interop.Contacts;
  19
  20 namespace Tizen.Pims.Contacts
  21 {
  22     /// <summary>
  23     /// A query is used to retrieve data which satisfies given criteria
  24     /// </summary>
  25     /// <remarks>
  26     /// A query is used to retrieve person, group, speed dial, and log data which satisfies a given criteria, such as an integer property being greater than a given value, or a string property containing a given substring.
  27     /// A query needs a filter which can set the conditions for the search.
  28     /// </remarks>
  29     public class ContactsQuery : IDisposable
  30     {
  31         internal IntPtr _queryHandle;
  32
  33         /// <summary>
  34         /// Creates a query.
  35         /// </summary>
  36         /// <param name="viewUri">The view URI of a query</param>
  37         /// <exception cref="NotSupportedException">Thrown when an invoked method is not supported</exception>
  38         /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
  39         /// <exception cref="OutOfMemoryException">Thrown when failed due to out of memory</exception>
  40         public ContactsQuery(string viewUri)
  41         {
  42             int error = Interop.Query.ContactsQueryCreate(viewUri, out _queryHandle);
  43             if ((int)ContactsError.None != error)
  44             {
  45                 Log.Error(Globals.LogTag, "ContactsQuery Failed with error " + error);
  46                 throw ContactsErrorFactory.CheckAndCreateException(error);
  47             }
  48         }
  49
  50         internal ContactsQuery(IntPtr handle)
  51         {
  52             _queryHandle = handle;
  53         }
  54
  55         ~ContactsQuery()
  56         {
  57             Dispose(false);
  58         }
  59         #region IDisposable Support
  60         private bool disposedValue = false;
  61
  62         protected virtual void Dispose(bool disposing)
  63         {
  64             if (!disposedValue)
  65             {
  66                 int error = Interop.Query.ContactsQueryDestroy(_queryHandle);
  67                 if ((int)ContactsError.None != error)
  68                 {
  69                     Log.Error(Globals.LogTag, "ContactsQueryDestroy Failed with error " + error);
  70                 }
  71
  72                 disposedValue = true;
  73             }
  74         }
  75
  76         /// <summary>
  77         /// Releases all resources used by the ContactsQuery.
  78         /// It should be called after finished using of the object.
  79         /// </summary>
  80         public void Dispose()
  81         {
  82             Dispose(true);
  83         }
  84         #endregion
  85
  86         /// <summary>
  87         /// Adds property IDs for projection.
  88         /// </summary>
  89         /// <param name="propertyIdArray">The property ID array </param>
  90         /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
  91         public void SetProjection(uint[] propertyIdArray)
  92         {
  93             int error = Interop.Query.ContactsQuerySetProjection(_queryHandle, propertyIdArray, propertyIdArray.Length);
  94             if ((int)ContactsError.None != error)
  95             {
  96                 Log.Error(Globals.LogTag, "SetProjection Failed with error " + error);
  97                 throw ContactsErrorFactory.CheckAndCreateException(error);
  98             }
  99         }
 100
 101         /// <summary>
 102         /// Sets the "distinct" option for projection.
 103         /// </summary>
 104         /// <param name="set">If true it is set, otherwise if false it is unset</param>
 105         /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
 106         public void SetDistinct(bool set)
 107         {
 108             int error = Interop.Query.ContactsQuerySetDistinct(_queryHandle, set);
 109             if ((int)ContactsError.None != error)
 110             {
 111                 Log.Error(Globals.LogTag, "SetDistinct Failed with error " + error);
 112                 throw ContactsErrorFactory.CheckAndCreateException(error);
 113             }
 114         }
 115
 116         /// <summary>
 117         /// Sets the filter for a query.
 118         /// </summary>
 119         /// <param name="filter">The filter</param>
 120         /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
 121         public void SetFilter(ContactsFilter filter)
 122         {
 123             int error = Interop.Query.ContactsQuerySetFilter(_queryHandle, filter._filterHandle);
 124             if ((int)ContactsError.None != error)
 125             {
 126                 Log.Error(Globals.LogTag, "SetFilter Failed with error " + error);
 127                 throw ContactsErrorFactory.CheckAndCreateException(error);
 128             }
 129         }
 130
 131         /// <summary>
 132         /// Sets the sort mode for a query.
 133         /// </summary>
 134         /// <param name="propertyId">The property ID to sort</param>
 135         /// <param name="isAscending">If true it sorts in the ascending order, otherwise if false it sorts in the descending order</param>
 136         /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
 137         public void SetSort(uint propertyId, bool isAscending)
 138         {
 139             int error = Interop.Query.ContactsQuerySetSort(_queryHandle, propertyId, isAscending);
 140             if ((int)ContactsError.None != error)
 141             {
 142                 Log.Error(Globals.LogTag, "SetSort Failed with error " + error);
 143                 throw ContactsErrorFactory.CheckAndCreateException(error);
 144             }
 145         }
 146     }
 147 }