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 System.Diagnostics.CodeAnalysis;
  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         [SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings")]
  41         public ContactsQuery(string viewUri)
  42         {
  43             int error = Interop.Query.ContactsQueryCreate(viewUri, out _queryHandle);
  44             if ((int)ContactsError.None != error)
  45             {
  46                 Log.Error(Globals.LogTag, "ContactsQuery Failed with error " + error);
  47                 throw ContactsErrorFactory.CheckAndCreateException(error);
  48             }
  49         }
  50
  51         internal ContactsQuery(IntPtr handle)
  52         {
  53             _queryHandle = handle;
  54         }
  55
  56         /// <summary>
  57         /// Destructor
  58         /// </summary>
  59         ~ContactsQuery()
  60         {
  61             Dispose(false);
  62         }
  63         #region IDisposable Support
  64         private bool disposedValue = false;
  65
  66         /// <summary>
  67         /// Releases all resources used by the ContactsQuery.
  68         /// </summary>
  69         /// <param name="disposing">Disposing by User</param>
  70         protected virtual void Dispose(bool disposing)
  71         {
  72             if (disposing)
  73             {
  74                 //Called by User
  75                 //Release your own managed resources here.
  76                 //You should release all of your own disposable objects here
  77             }
  78
  79             if (!disposedValue)
  80             {
  81                 int error = Interop.Query.ContactsQueryDestroy(_queryHandle);
  82                 if ((int)ContactsError.None != error)
  83                 {
  84                     Log.Error(Globals.LogTag, "ContactsQueryDestroy Failed with error " + error);
  85                 }
  86
  87                 disposedValue = true;
  88             }
  89         }
  90
  91         /// <summary>
  92         /// Releases all resources used by the ContactsQuery.
  93         /// It should be called after finished using of the object.
  94         /// </summary>
  95         public void Dispose()
  96         {
  97             Dispose(true);
  98             GC.SuppressFinalize(this);
  99         }
 100         #endregion
 101
 102         /// <summary>
 103         /// Adds property IDs for projection.
 104         /// </summary>
 105         /// <param name="propertyIdArray">The property ID array </param>
 106         /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
 107         public void SetProjection(uint[] propertyIdArray)
 108         {
 109             int error = Interop.Query.ContactsQuerySetProjection(_queryHandle, propertyIdArray, propertyIdArray.Length);
 110             if ((int)ContactsError.None != error)
 111             {
 112                 Log.Error(Globals.LogTag, "SetProjection Failed with error " + error);
 113                 throw ContactsErrorFactory.CheckAndCreateException(error);
 114             }
 115         }
 116
 117         /// <summary>
 118         /// Sets the "distinct" option for projection.
 119         /// </summary>
 120         /// <param name="set">If true it is set, otherwise if false it is unset</param>
 121         /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
 122         public void SetDistinct(bool set)
 123         {
 124             int error = Interop.Query.ContactsQuerySetDistinct(_queryHandle, set);
 125             if ((int)ContactsError.None != error)
 126             {
 127                 Log.Error(Globals.LogTag, "SetDistinct Failed with error " + error);
 128                 throw ContactsErrorFactory.CheckAndCreateException(error);
 129             }
 130         }
 131
 132         /// <summary>
 133         /// Sets the filter for a query.
 134         /// </summary>
 135         /// <param name="filter">The filter</param>
 136         /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
 137         public void SetFilter(ContactsFilter filter)
 138         {
 139             int error = Interop.Query.ContactsQuerySetFilter(_queryHandle, filter._filterHandle);
 140             if ((int)ContactsError.None != error)
 141             {
 142                 Log.Error(Globals.LogTag, "SetFilter Failed with error " + error);
 143                 throw ContactsErrorFactory.CheckAndCreateException(error);
 144             }
 145         }
 146
 147         /// <summary>
 148         /// Sets the sort mode for a query.
 149         /// </summary>
 150         /// <param name="propertyId">The property ID to sort</param>
 151         /// <param name="isAscending">If true it sorts in the ascending order, otherwise if false it sorts in the descending order</param>
 152         /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
 153         public void SetSort(uint propertyId, bool isAscending)
 154         {
 155             int error = Interop.Query.ContactsQuerySetSort(_queryHandle, propertyId, isAscending);
 156             if ((int)ContactsError.None != error)
 157             {
 158                 Log.Error(Globals.LogTag, "SetSort Failed with error " + error);
 159                 throw ContactsErrorFactory.CheckAndCreateException(error);
 160             }
 161         }
 162     }
 163 }