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
  30     /// Setting content filter properties helps to limit the number of filtered items as following:
  31     ///<list>
  32     /// <item><description>
  33     /// Offset - Used to set starting position of the filter's search
  34     /// </description></item>
  35     /// <item><description>
  36     /// Count - Used to set number of items to be searched from offset
  37     /// </description></item>
  38     /// <item><description>
  39     /// Condition - Used to set keyword which user want to search
  40     /// </description></item>
  41     /// <item><description>
  42     /// Order - Used to set type of media to be ordered by the filter
  43     /// </description></item>
  44     /// </list>
  45
  46     /// Searchable expression can use one of the following forms:
  47
  48     ///<list>
  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     /// column <= value
  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     /// value <= column
  75     /// </description></item>
  76     /// <item><description>
  77     /// column IN (value)
  78     /// </description></item>
  79     /// <item><description>
  80     /// column IN(value-list)
  81     /// </description></item>
  82     /// <item><description>
  83     /// column NOT IN(value)
  84     /// </description></item>
  85     /// <item><description>
  86     /// column NOT IN(value-list)
  87     /// </description></item>
  88     /// <item><description>
  89     /// column LIKE value
  90     /// </description></item>
  91     /// <item><description>
  92     /// expression1 AND expression2 OR expression3
  93     /// </description></item>
  94     /// </list>
  95
  96
  97     /// 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.
  98     /// If these characters are used as value of LIKE operation, then the expression following the ESCAPE caluse of sqlite.
  99     /// </remarks>
 100     public class ContentFilter : IDisposable
 101     {
 102         private IntPtr _filterHandle = IntPtr.Zero;
 103         private bool _disposedValue = false;
 104         private ContentCollation _conditionCollate = ContentCollation.Default;
 105         private ContentCollation _orderCollate = ContentCollation.Default;
 106         private ContentOrder _orderType = ContentOrder.Asc;
 107         private string _orderKeyword = null;
 108         private string _conditionMsg = null;
 109
 110         internal IntPtr Handle
 111         {
 112             get
 113             {
 114                 if (_filterHandle == IntPtr.Zero)
 115                 {
 116                     throw new ObjectDisposedException(nameof(ContentFilter));
 117                 }
 118
 119                 return _filterHandle;
 120             }
 121         }
 122         /// <summary>
 123         /// The start position of the given filter Starting from zero.
 124         /// Please note that count value has to be set properly for correct result.
 125         /// </summary>
 126         public int Offset
 127         {
 128             get
 129             {
 130                 int offset;
 131                 int count;
 132                 MediaContentValidator.ThrowIfError(
 133                     Interop.Filter.GetOffset(Handle, out offset, out count), "Failed to get offset");
 134
 135                 return offset;
 136             }
 137
 138             set
 139             {
 140                 MediaContentValidator.ThrowIfError(
 141                     Interop.Filter.SetOffset(Handle, value, this.Count), "Failed to set offset");
 142             }
 143         }
 144
 145         public ContentFilter()
 146         {
 147             MediaContentValidator.ThrowIfError(
 148                 Interop.Filter.Create(out _filterHandle), "Failed to Create Filter handle.");
 149         }
 150
 151         /// <summary>
 152         /// The number of items to be searched with respect to the offset
 153         /// </summary>
 154         public int Count
 155         {
 156             get
 157             {
 158                 int offset;
 159                 int count;
 160                 MediaContentValidator.ThrowIfError(
 161                     Interop.Filter.GetOffset(Handle, out offset, out count), "Failed to get count");
 162
 163                 return count;
 164             }
 165
 166             set
 167             {
 168                 MediaContentValidator.ThrowIfError(
 169                     Interop.Filter.SetOffset(Handle, this.Offset, value), "Failed to set count");
 170             }
 171         }
 172
 173         /// <summary>
 174         /// Gets the media filter content order and order keyword.
 175         /// </summary>
 176         public ContentOrder Order
 177         {
 178             get
 179             {
 180                 return _orderType;
 181             }
 182
 183             set
 184             {
 185                 if (_orderKeyword != null)
 186                 {
 187                     MediaContentValidator.ThrowIfError(
 188                         Interop.Filter.SetOrder(Handle, value, _orderKeyword, _orderCollate), "Failed to set order");
 189                 }
 190
 191                 _orderType = value;
 192             }
 193         }
 194
 195         /// <summary>
 196         /// The search order keyword
 197         /// </summary>
 198         public string OrderKey
 199         {
 200             get
 201             {
 202                 ContentOrder order;
 203                 IntPtr val = IntPtr.Zero;
 204                 ContentCollation type;
 205                 try
 206                 {
 207                     MediaContentValidator.ThrowIfError(
 208                         Interop.Filter.GetOrder(Handle, out order, out val, out type), "Failed to GetOrder for OrderKey");
 209
 210                     return Marshal.PtrToStringAnsi(val);
 211                 }
 212                 finally
 213                 {
 214                     Interop.Libc.Free(val);
 215                 }
 216             }
 217
 218             set
 219             {
 220                 MediaContentValidator.ThrowIfError(
 221                     Interop.Filter.SetOrder(Handle, _orderType, value, _orderCollate), "Failed to set OrderKey");
 222
 223                 _orderKeyword = value;
 224             }
 225         }
 226
 227         /// <summary>
 228         /// The collate type for comparing two strings
 229         /// </summary>
 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         public string Condition
 253         {
 254             get
 255             {
 256                 IntPtr val = IntPtr.Zero;
 257                 ContentCollation type;
 258                 try
 259                 {
 260                     MediaContentValidator.ThrowIfError(
 261                         Interop.Filter.GetCondition(Handle, out val, out type), "Failed to get condition");
 262
 263                     return Marshal.PtrToStringAnsi(val);
 264                 }
 265                 finally
 266                 {
 267                     Interop.Libc.Free(val);
 268                 }
 269             }
 270
 271             set
 272             {
 273                 MediaContentValidator.ThrowIfError(
 274                     Interop.Filter.SetCondition(Handle, value, _conditionCollate), "Failed to set condition");
 275
 276                 _conditionMsg = value;
 277             }
 278         }
 279
 280         /// <summary>
 281         /// The collate type for comparing two strings
 282         /// </summary>
 283         public ContentCollation ConditionCollationType
 284         {
 285             get
 286             {
 287                 return _conditionCollate;
 288             }
 289
 290             set
 291             {
 292                 if (_conditionMsg != null)
 293                 {
 294                     MediaContentValidator.ThrowIfError(
 295                         Interop.Filter.SetCondition(Handle, _conditionMsg, value), "Failed to set collation");
 296                 }
 297
 298                 _conditionCollate = value;
 299             }
 300         }
 301
 302         /// <summary>
 303         /// Sets the storage id for the given filter.
 304         /// You can use this property when you want to search items only in the specific storage
 305         /// </summary>
 306         public string StorageId
 307         {
 308             get
 309             {
 310                 IntPtr val = IntPtr.Zero;
 311                 try
 312                 {
 313                     MediaContentValidator.ThrowIfError(
 314                         Interop.Filter.GetStorage(Handle, out val), "Failed to get condition");
 315
 316                     return Marshal.PtrToStringAnsi(val);
 317                 }
 318                 finally
 319                 {
 320                     Interop.Libc.Free(val);
 321                 }
 322             }
 323
 324             set
 325             {
 326                 MediaContentValidator.ThrowIfError(
 327                     Interop.Filter.SetStorage(Handle, value), "Failed to set condition");
 328             }
 329         }
 330
 331         /// <summary>
 332         /// The type of the media group
 333         /// </summary>
 334         public MediaGroupType GroupType { get; set; }
 335
 336         /// <summary>
 337         /// Dispose API for closing the internal resources.
 338         /// This function can be used to stop all effects started by Vibrate().
 339         /// </summary>
 340         public void Dispose()
 341         {
 342             Dispose(true);
 343             GC.SuppressFinalize(this);
 344         }
 345
 346         protected virtual void Dispose(bool disposing)
 347         {
 348             if (!_disposedValue)
 349             {
 350                 if (_filterHandle != IntPtr.Zero)
 351                 {
 352                     Interop.Filter.Destroy(_filterHandle);
 353                     _filterHandle = IntPtr.Zero;
 354                 }
 355
 356                 _disposedValue = true;
 357             }
 358         }
 359     }
 360 }