src/Tizen.Content.MediaContent/Tizen.Content.MediaContent/ContentFilter.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
  18 using System;
  19 using System.Runtime.InteropServices;
  20
  21 namespace Tizen.Content.MediaContent
  22 {
  23     /// <summary>
  24     /// The Content Filter API provides functions to manage media filters.
  25     /// </summary>
  26     /// <remarks>
  27     /// A Content filter is required for filtering information associated with Media Folder, Tag, Audio, MediaBookmark and Media Information on basis of details like offset, count, order and condition for searching.
  28     /// It provide functionality to set properties associated with a given content filter.
  29     /// Setting content filter properties helps to limit the number of filtered items as following:
  30     /// <list>
  31     /// <item><description>
  32     /// Offset - Used to set starting position of the filter's search
  33     /// </description></item>
  34     /// <item><description>
  35     /// Count - Used to set number of items to be searched from offset
  36     /// </description></item>
  37     /// <item><description>
  38     /// Condition - Used to set keyword which user want to search
  39     /// </description></item>
  40     /// <item><description>
  41     /// Order - Used to set type of media to be ordered by the filter
  42     /// </description></item>
  43     /// </list>
  44     /// Searchable expression can use one of the following forms:
  45     /// <list>
  46     /// <item><description>
  47     /// column = value
  48     /// </description></item>
  49     /// <item><description>
  50     /// column > value
  51     /// </description></item>
  52     /// <item><description>
  53     /// column >= value
  54     /// </description></item>
  55     /// <item><description>
  56     /// column < value
  57     /// </description></item>
  58     /// <item><description>
  59     /// column <= value
  60     /// </description></item>
  61     /// <item><description>
  62     /// value = column
  63     /// </description></item>
  64     /// <item><description>
  65     /// value >= column
  66     /// </description></item>
  67     /// <item><description>
  68     /// value < column
  69     /// </description></item>
  70     /// <item><description>
  71     /// value <= column
  72     /// </description></item>
  73     /// <item><description>
  74     /// column IN (value)
  75     /// </description></item>
  76     /// <item><description>
  77     /// column IN(value-list)
  78     /// </description></item>
  79     /// <item><description>
  80     /// column NOT IN(value)
  81     /// </description></item>
  82     /// <item><description>
  83     /// column NOT IN(value-list)
  84     /// </description></item>
  85     /// <item><description>
  86     /// column LIKE value
  87     /// </description></item>
  88     /// <item><description>
  89     /// expression1 AND expression2 OR expression3
  90     /// </description></item>
  91     /// </list>
  92     /// Note that if you want to set qoutation(" ' " or " " ") as value of LIKE operator, you should use two times.(" '' " or " "" ") \n And the optional ESCAPE clause is supported. Both percent symbol("%") and underscore symbol("_") are used in the LIKE pattern.
  93     /// If these characters are used as value of LIKE operation, then the expression following the ESCAPE caluse of sqlite.
  94     /// </remarks>
  95     public class ContentFilter : IDisposable
  96     {
  97         private IntPtr _filterHandle = IntPtr.Zero;
  98         private bool _disposedValue = false;
  99         private ContentCollation _conditionCollate = ContentCollation.Default;
 100         private ContentCollation _orderCollate = ContentCollation.Default;
 101         private ContentOrder _orderType = ContentOrder.Asc;
 102         private string _orderKeyword = null;
 103         private string _conditionMsg = null;
 104
 105         internal IntPtr Handle
 106         {
 107             get
 108             {
 109                 if (_filterHandle == IntPtr.Zero)
 110                 {
 111                     throw new ObjectDisposedException(nameof(ContentFilter));
 112                 }
 113
 114                 return _filterHandle;
 115             }
 116         }
 117         /// <summary>
 118         /// The start position of the given filter Starting from zero.
 119         /// Please note that count value has to be set properly for correct result.
 120         /// </summary>
 121         /// <since_tizen> 3 </since_tizen>
 122         public int Offset
 123         {
 124             get
 125             {
 126                 int offset;
 127                 int count;
 128                 MediaContentValidator.ThrowIfError(
 129                     Interop.Filter.GetOffset(Handle, out offset, out count), "Failed to get offset");
 130
 131                 return offset;
 132             }
 133
 134             set
 135             {
 136                 MediaContentValidator.ThrowIfError(
 137                     Interop.Filter.SetOffset(Handle, value, this.Count), "Failed to set offset");
 138             }
 139         }
 140
 141         public ContentFilter()
 142         {
 143             MediaContentValidator.ThrowIfError(
 144                 Interop.Filter.Create(out _filterHandle), "Failed to Create Filter handle.");
 145         }
 146
 147         /// <summary>
 148         /// The number of items to be searched with respect to the offset
 149         /// </summary>
 150         /// <since_tizen> 3 </since_tizen>
 151         public int Count
 152         {
 153             get
 154             {
 155                 int offset;
 156                 int count;
 157                 MediaContentValidator.ThrowIfError(
 158                     Interop.Filter.GetOffset(Handle, out offset, out count), "Failed to get count");
 159
 160                 return count;
 161             }
 162
 163             set
 164             {
 165                 MediaContentValidator.ThrowIfError(
 166                     Interop.Filter.SetOffset(Handle, this.Offset, value), "Failed to set count");
 167             }
 168         }
 169
 170         /// <summary>
 171         /// Gets the media filter content order and order keyword.
 172         /// </summary>
 173         /// <since_tizen> 3 </since_tizen>
 174         public ContentOrder Order
 175         {
 176             get
 177             {
 178                 return _orderType;
 179             }
 180
 181             set
 182             {
 183                 if (_orderKeyword != null)
 184                 {
 185                     MediaContentValidator.ThrowIfError(
 186                         Interop.Filter.SetOrder(Handle, value, _orderKeyword, _orderCollate), "Failed to set order");
 187                 }
 188
 189                 _orderType = value;
 190             }
 191         }
 192
 193         /// <summary>
 194         /// The search order keyword
 195         /// </summary>
 196         /// <since_tizen> 3 </since_tizen>
 197         public string OrderKey
 198         {
 199             get
 200             {
 201                 ContentOrder order;
 202                 IntPtr val = IntPtr.Zero;
 203                 ContentCollation type;
 204                 try
 205                 {
 206                     MediaContentValidator.ThrowIfError(
 207                         Interop.Filter.GetOrder(Handle, out order, out val, out type), "Failed to GetOrder for OrderKey");
 208
 209                     return Marshal.PtrToStringAnsi(val);
 210                 }
 211                 finally
 212                 {
 213                     Interop.Libc.Free(val);
 214                 }
 215             }
 216
 217             set
 218             {
 219                 MediaContentValidator.ThrowIfError(
 220                     Interop.Filter.SetOrder(Handle, _orderType, value, _orderCollate), "Failed to set OrderKey");
 221
 222                 _orderKeyword = value;
 223             }
 224         }
 225
 226         /// <summary>
 227         /// The collate type for comparing two strings
 228         /// </summary>
 229         /// <since_tizen> 3 </since_tizen>
 230         public ContentCollation OrderCollationType
 231         {
 232             get
 233             {
 234                 return _orderCollate;
 235             }
 236
 237             set
 238             {
 239                 if (_orderKeyword != null)
 240                 {
 241                     MediaContentValidator.ThrowIfError(
 242                         Interop.Filter.SetOrder(Handle, _orderType, _orderKeyword, value), "Failed to set collation");
 243                 }
 244
 245                 _orderCollate = value;
 246             }
 247         }
 248
 249         /// <summary>
 250         /// Gets/Sets the condition for the given filter.
 251         /// </summary>
 252         /// <since_tizen> 3 </since_tizen>
 253         public string Condition
 254         {
 255             get
 256             {
 257                 IntPtr val = IntPtr.Zero;
 258                 ContentCollation type;
 259                 try
 260                 {
 261                     MediaContentValidator.ThrowIfError(
 262                         Interop.Filter.GetCondition(Handle, out val, out type), "Failed to get condition");
 263
 264                     return Marshal.PtrToStringAnsi(val);
 265                 }
 266                 finally
 267                 {
 268                     Interop.Libc.Free(val);
 269                 }
 270             }
 271
 272             set
 273             {
 274                 MediaContentValidator.ThrowIfError(
 275                     Interop.Filter.SetCondition(Handle, value, _conditionCollate), "Failed to set condition");
 276
 277                 _conditionMsg = value;
 278             }
 279         }
 280
 281         /// <summary>
 282         /// The collate type for comparing two strings
 283         /// </summary>
 284         /// <since_tizen> 3 </since_tizen>
 285         public ContentCollation ConditionCollationType
 286         {
 287             get
 288             {
 289                 return _conditionCollate;
 290             }
 291
 292             set
 293             {
 294                 if (_conditionMsg != null)
 295                 {
 296                     MediaContentValidator.ThrowIfError(
 297                         Interop.Filter.SetCondition(Handle, _conditionMsg, value), "Failed to set collation");
 298                 }
 299
 300                 _conditionCollate = value;
 301             }
 302         }
 303
 304         /// <summary>
 305         /// Sets the storage id for the given filter.
 306         /// You can use this property when you want to search items only in the specific storage
 307         /// </summary>
 308         /// <since_tizen> 3 </since_tizen>
 309         public string StorageId
 310         {
 311             get
 312             {
 313                 IntPtr val = IntPtr.Zero;
 314                 try
 315                 {
 316                     MediaContentValidator.ThrowIfError(
 317                         Interop.Filter.GetStorage(Handle, out val), "Failed to get condition");
 318
 319                     return Marshal.PtrToStringAnsi(val);
 320                 }
 321                 finally
 322                 {
 323                     Interop.Libc.Free(val);
 324                 }
 325             }
 326
 327             set
 328             {
 329                 MediaContentValidator.ThrowIfError(
 330                     Interop.Filter.SetStorage(Handle, value), "Failed to set condition");
 331             }
 332         }
 333
 334         /// <summary>
 335         /// The type of the media group
 336         /// </summary>
 337         /// <since_tizen> 3 </since_tizen>
 338         public MediaGroupType GroupType { get; set; }
 339
 340         /// <summary>
 341         /// Dispose API for closing the internal resources.
 342         /// This function can be used to stop all effects started by Vibrate().
 343         /// </summary>
 344         /// <since_tizen> 3 </since_tizen>
 345         public void Dispose()
 346         {
 347             Dispose(true);
 348             GC.SuppressFinalize(this);
 349         }
 350
 351         protected virtual void Dispose(bool disposing)
 352         {
 353             if (!_disposedValue)
 354             {
 355                 if (_filterHandle != IntPtr.Zero)
 356                 {
 357                     Interop.Filter.Destroy(_filterHandle);
 358                     _filterHandle = IntPtr.Zero;
 359                 }
 360
 361                 _disposedValue = true;
 362             }
 363         }
 364     }
 365 }