src/Tizen.Content.MediaContent/Tizen.Content.MediaContent/QueryArguments.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;
  19 using FilterHandle = Interop.FilterHandle;
  20
  21 namespace Tizen.Content.MediaContent
  22 {
  23     /// <summary>
  24     /// The Base class for query arguments.
  25     /// </summary>
  26     /// <remarks>
  27     /// A filter is required for filtering information associated with Album, Folder, Tag, Bookmark, Playlist,
  28     /// and MediaInfo on the basis of details like limit, order, and condition.
  29     /// </remarks>
  30     /// <since_tizen> 4 </since_tizen>
  31     public class QueryArguments
  32     {
  33         private string _filter;
  34
  35         /// <summary>
  36         /// Gets or sets the filtering expression that is applied.
  37         /// </summary>
  38         /// <value>A string that represents a filtering expression applied when data is retrieved.</value>
  39         /// <remarks>
  40         /// Expressions for the filter can be one of the following forms:<br/>
  41         /// - column = value
  42         /// - column > value
  43         /// - column >= value
  44         /// - <![CDATA[column < value]]>
  45         /// - <![CDATA[column <= value]]>
  46         /// - value = column
  47         /// - value >= column
  48         /// - <![CDATA[value < column]]>
  49         /// - <![CDATA[value <= column]]>
  50         /// - column IN (value)
  51         /// - column IN(value-list)
  52         /// - column NOT IN(value)
  53         /// - column NOT IN(value-list)
  54         /// - column LIKE value
  55         /// - expression COLLATE NOCASE
  56         /// - expression COLLATE RTRIM
  57         /// - expression COLLATE LOCALIZED
  58         /// - expression1 AND expression2 OR expression3 ...
  59         /// <br/>
  60         /// Note that if you want to set quotation (" ' " or " " ") as value of LIKE operator, you should use two times. (" '' " or " "" ").
  61         /// And the optional ESCAPE clause is supported. Both percent symbol("%") and underscore symbol("_") are used in the LIKE pattern.
  62         /// If these characters are used as values of the LIKE operation, then the expression following the ESCAPE clause of sqlite will be ignored.<br/>
  63         /// <br/>
  64         /// For example, column LIKE ('#%') ESCAPE ('#') - "#" is an escape character, it will be ignored.
  65         /// </remarks>
  66         /// <exception cref="ArgumentException"><paramref name="value"/> is a zero-length string, contains only white space.</exception>
  67         /// <seealso cref="MediaInfoColumns"/>
  68         /// <seealso cref="AlbumColumns"/>
  69         /// <seealso cref="FolderColumns"/>
  70         /// <seealso cref="PlaylistColumns"/>
  71         /// <seealso cref="TagColumns"/>
  72         /// <seealso cref="BookmarkColumns"/>
  73         /// <seealso cref="FaceInfoColumns"/>
  74         /// <since_tizen> 4 </since_tizen>
  75         public string FilterExpression
  76         {
  77             get => _filter;
  78             set
  79             {
  80                 if (value != null)
  81                 {
  82                     ValidationUtil.ValidateNotNullOrEmpty(value, nameof(value));
  83                 }
  84
  85                 _filter = value;
  86             }
  87         }
  88
  89         private string _storageId;
  90
  91         /// <summary>
  92         /// Gets or sets the storage ID for the given filter.
  93         /// You can use this property when you want to search items only in the specific storage.
  94         /// </summary>
  95         /// <value>The storage ID to restrict storage to search, or null for all storages.</value>
  96         /// <exception cref="ArgumentException"><paramref name="value"/> is a zero-length string, contains only white space.</exception>
  97         /// <since_tizen> 4 </since_tizen>
  98         [Obsolete("Please do not use! this will be deprecated in level 6")]
  99         public string StorageId
 100         {
 101             get => _storageId;
 102             set
 103             {
 104                 if (value != null)
 105                 {
 106                     ValidationUtil.ValidateNotNullOrEmpty(value, nameof(value));
 107                 }
 108
 109                 _storageId = value;
 110             }
 111         }
 112
 113         internal static FilterHandle ToNativeHandle(QueryArguments arguments)
 114         {
 115             if (arguments == null || arguments.IsEmpty())
 116             {
 117                 return FilterHandle.Null;
 118             }
 119
 120             Interop.Filter.Create(out var handle).ThrowIfError("Failed to apply arguments.");
 121
 122             try
 123             {
 124                 arguments.FillHandle(handle);
 125             }
 126             catch (Exception)
 127             {
 128                 handle.Dispose();
 129                 throw;
 130             }
 131
 132             return handle;
 133         }
 134
 135         internal static FilterHandle CreateNativeHandle(string filterExpression)
 136         {
 137             Debug.Assert(filterExpression != null);
 138
 139             Interop.Filter.Create(out var handle).ThrowIfError("Failed to apply arguments.");
 140
 141             Interop.Filter.SetCondition(handle, filterExpression, Collation.Default).
 142                 ThrowIfError("Failed to create filter handle.");
 143
 144             return handle;
 145         }
 146
 147 #pragma warning disable CS0618 // Type or member is obsolete
 148         internal virtual bool IsEmpty()
 149         {
 150             return StorageId == null && FilterExpression == null;
 151         }
 152
 153         internal virtual void FillHandle(FilterHandle handle)
 154         {
 155             if (FilterExpression != null)
 156             {
 157                 Interop.Filter.SetCondition(handle, FilterExpression, Collation.Default).
 158                     ThrowIfError("Failed to create filter handle(condition)");
 159             }
 160
 161             if (StorageId != null)
 162             {
 163                 Interop.Filter.SetStorage(handle, StorageId).
 164                     ThrowIfError("Failed to create filter handle(storage id)"); ;
 165             }
 166         }
 167 #pragma warning restore CS0618 // Type or member is obsolete
 168
 169     }
 170
 171     /// <summary>
 172     /// Provides the ability to filter the result of a Select command.
 173     /// </summary>
 174     /// <remarks>
 175     /// A filter is required for filtering information associated with Album, Folder, Tag, Bookmark, Playlist,
 176     /// and MediaInfo.
 177     /// </remarks>
 178     /// <since_tizen> 4 </since_tizen>
 179     public class SelectArguments : QueryArguments
 180     {
 181         private int _startRowIndex;
 182
 183         /// <summary>
 184         /// Gets or sets the starting row position of a query (starting from zero).
 185         /// </summary>
 186         /// <value>An integer value that indicates the starting row position of a query.</value>
 187         /// <exception cref="ArgumentOutOfRangeException"><paramref name="value"/> is less than zero.<br/></exception>
 188         /// <since_tizen> 4 </since_tizen>
 189         public int StartRowIndex
 190         {
 191             get => _startRowIndex;
 192             set
 193             {
 194                 if (value < 0)
 195                 {
 196                     throw new ArgumentOutOfRangeException(nameof(value), value, "StartRowIndex can't be less than zero.");
 197                 }
 198
 199                 _startRowIndex = value;
 200             }
 201         }
 202
 203         private int _totalRowCount;
 204
 205         /// <summary>
 206         /// Gets or sets the number of rows to be retrieved.
 207         /// </summary>
 208         /// <value>An integer value that indicates the limit of rows of the result.</value>
 209         /// <exception cref="ArgumentOutOfRangeException"><paramref name="value"/> is less than zero.</exception>
 210         /// <since_tizen> 4 </since_tizen>
 211         public int TotalRowCount
 212         {
 213             get => _totalRowCount;
 214             set
 215             {
 216                 if (value < 0)
 217                 {
 218                     throw new ArgumentOutOfRangeException(nameof(value), value, "TotalRowCount can't be less than zero.");
 219                 }
 220
 221                 _totalRowCount = value;
 222             }
 223         }
 224
 225         private string _sortOrder;
 226
 227         /// <summary>
 228         /// Gets or sets the sort order of the results.
 229         /// </summary>
 230         /// <value>The expression for the sort order.</value>
 231         /// <remarks>
 232         /// Expressions for the sort order can be:<br/>
 233         /// column [COLLATE NOCASE/RTRIM/LOCALIZED] [ASC/DESC], column2 ...
 234         /// </remarks>
 235         /// <exception cref="ArgumentException"><paramref name="value"/> is a zero-length string, contains only white space.</exception>
 236         /// <seealso cref="MediaInfoColumns"/>
 237         /// <seealso cref="AlbumColumns"/>
 238         /// <seealso cref="FolderColumns"/>
 239         /// <seealso cref="PlaylistColumns"/>
 240         /// <seealso cref="TagColumns"/>
 241         /// <seealso cref="BookmarkColumns"/>
 242         /// <seealso cref="FaceInfoColumns"/>
 243         /// <since_tizen> 4 </since_tizen>
 244         public string SortOrder
 245         {
 246             get => _sortOrder;
 247             set
 248             {
 249                 if (value != null)
 250                 {
 251                     ValidationUtil.ValidateNotNullOrEmpty(value, nameof(value));
 252                 }
 253
 254                 _sortOrder = value;
 255             }
 256         }
 257
 258         internal override bool IsEmpty()
 259         {
 260             return base.IsEmpty() && StartRowIndex == 0 && TotalRowCount == 0 && SortOrder == null;
 261         }
 262
 263         internal override void FillHandle(FilterHandle handle)
 264         {
 265             base.FillHandle(handle);
 266
 267             if (StartRowIndex != 0 || TotalRowCount != 0)
 268             {
 269                 Interop.Filter.SetOffset(handle, StartRowIndex, TotalRowCount).
 270                     ThrowIfError("Failed to create filter handle(limit)");
 271             }
 272
 273             if (SortOrder != null)
 274             {
 275                 Interop.Filter.SetOrder(handle, SortOrder).ThrowIfError("Failed to create filter handle(order)");
 276             }
 277         }
 278     }
 279
 280     /// <summary>
 281     /// Provides the ability to filter the result of the Count command.
 282     /// </summary>
 283     /// <remarks>
 284     /// A filter is required for filtering information associated with Album, Folder, Tag, Bookmark, Playlist,
 285     /// and MediaInfo.
 286     /// </remarks>
 287     /// <since_tizen> 4 </since_tizen>
 288     public class CountArguments : QueryArguments
 289     {
 290     }
 291 }