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             if (propertyIdArray == null)
 110             {
 111                 throw new ArgumentException("Invalid Parameters Provided");
 112             }
 113
 114             int error = Interop.Query.ContactsQuerySetProjection(_queryHandle, propertyIdArray, propertyIdArray.Length);
 115             if ((int)ContactsError.None != error)
 116             {
 117                 Log.Error(Globals.LogTag, "SetProjection Failed with error " + error);
 118                 throw ContactsErrorFactory.CheckAndCreateException(error);
 119             }
 120         }
 121
 122         /// <summary>
 123         /// Sets the "distinct" option for projection.
 124         /// </summary>
 125         /// <param name="set">If true it is set, otherwise if false it is unset</param>
 126         public void SetDistinct(bool set)
 127         {
 128             int error = Interop.Query.ContactsQuerySetDistinct(_queryHandle, set);
 129             if ((int)ContactsError.None != error)
 130             {
 131                 Log.Error(Globals.LogTag, "SetDistinct Failed with error " + error);
 132                 throw ContactsErrorFactory.CheckAndCreateException(error);
 133             }
 134         }
 135
 136         /// <summary>
 137         /// Sets the filter for a query.
 138         /// </summary>
 139         /// <param name="filter">The filter</param>
 140         /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
 141         public void SetFilter(ContactsFilter filter)
 142         {
 143             int error = Interop.Query.ContactsQuerySetFilter(_queryHandle, filter._filterHandle);
 144             if ((int)ContactsError.None != error)
 145             {
 146                 Log.Error(Globals.LogTag, "SetFilter Failed with error " + error);
 147                 throw ContactsErrorFactory.CheckAndCreateException(error);
 148             }
 149         }
 150
 151         /// <summary>
 152         /// Sets the sort mode for a query.
 153         /// </summary>
 154         /// <param name="propertyId">The property ID to sort</param>
 155         /// <param name="isAscending">If true it sorts in the ascending order, otherwise if false it sorts in the descending order</param>
 156         /// <exception cref="ArgumentException">Thrown when one of the arguments provided to a method is not valid</exception>
 157         public void SetSort(uint propertyId, bool isAscending)
 158         {
 159             int error = Interop.Query.ContactsQuerySetSort(_queryHandle, propertyId, isAscending);
 160             if ((int)ContactsError.None != error)
 161             {
 162                 Log.Error(Globals.LogTag, "SetSort Failed with error " + error);
 163                 throw ContactsErrorFactory.CheckAndCreateException(error);
 164             }
 165         }
 166     }
 167 }