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