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