2 * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 using System.Diagnostics;
19 using FilterHandle = Interop.FilterHandle;
21 namespace Tizen.Content.MediaContent
24 /// The Base class for query arguments.
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.
30 public class QueryArguments
32 private string _filter;
35 /// Gets or sets the filtering expression that is applied.
37 /// <value>A string that represents a filtering expression applied when data is retrieved.</value>
39 /// Expressions for the filter can be one of the following forms:<br/>
43 /// - <![CDATA[column < value]]>
44 /// - <![CDATA[column <= value]]>
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 ...
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/>
63 /// For example, column LIKE ('#%') ESCAPE ('#') - "#" is an escape character, it will be ignored.
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
80 ValidationUtil.ValidateNotNullOrEmpty(value, nameof(value));
87 private string _storageId;
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.
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
102 ValidationUtil.ValidateNotNullOrEmpty(value, nameof(value));
109 internal static FilterHandle ToNativeHandle(QueryArguments arguments)
111 if (arguments == null || arguments.IsEmpty())
113 return FilterHandle.Null;
116 Interop.Filter.Create(out var handle).ThrowIfError("Failed to apply arguments.");
120 arguments.FillHandle(handle);
131 internal static FilterHandle CreateNativeHandle(string filterExpression)
133 Debug.Assert(filterExpression != null);
135 Interop.Filter.Create(out var handle).ThrowIfError("Failed to apply arguments.");
137 Interop.Filter.SetCondition(handle, filterExpression, Collation.Default).
138 ThrowIfError("Failed to create filter handle.");
143 internal virtual bool IsEmpty()
145 return StorageId == null && FilterExpression == null;
148 internal virtual void FillHandle(FilterHandle handle)
150 if (FilterExpression != null)
152 Interop.Filter.SetCondition(handle, FilterExpression, Collation.Default).
153 ThrowIfError("Failed to create filter handle(condition)");
156 if (StorageId != null)
158 Interop.Filter.SetStorage(handle, StorageId).
159 ThrowIfError("Failed to create filter handle(storage id)"); ;
165 /// Provides the ability to filter the result of a Select command.
168 /// A filter is required for filtering information associated with Album, Folder, Tag, Bookmark, Playlist,
171 public class SelectArguments : QueryArguments
173 private int _startRowIndex;
176 /// Gets or sets the starting row position of a query (starting from zero).
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
182 get => _startRowIndex;
187 throw new ArgumentOutOfRangeException(nameof(value), value, "StartRowIndex can't be less than zero.");
190 _startRowIndex = value;
194 private int _totalRowCount;
197 /// Gets or sets the number of rows to be retrieved.
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
203 get => _totalRowCount;
208 throw new ArgumentOutOfRangeException(nameof(value), value, "TotalRowCount can't be less than zero.");
211 _totalRowCount = value;
215 private string _sortOrder;
218 /// Gets or sets the sort order of the results.
220 /// <value>The expression for the sort order.</value>
222 /// Expressions for the sort order can be:<br/>
223 /// column [COLLATE NOCASE/RTRIM/LOCALIZED] [ASC/DESC], column2 ...
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
240 ValidationUtil.ValidateNotNullOrEmpty(value, nameof(value));
247 internal override bool IsEmpty()
249 return base.IsEmpty() && StartRowIndex == 0 && TotalRowCount == 0 && SortOrder == null;
252 internal override void FillHandle(FilterHandle handle)
254 base.FillHandle(handle);
256 if (StartRowIndex != 0 || TotalRowCount != 0)
258 Interop.Filter.SetOffset(handle, StartRowIndex, TotalRowCount).
259 ThrowIfError("Failed to create filter handle(limit)");
262 if (SortOrder != null)
264 Interop.Filter.SetOrder(handle, SortOrder).ThrowIfError("Failed to create filter handle(order)");
270 /// Provides the ability to filter the result of the Count command.
273 /// A filter is required for filtering information associated with Album, Folder, Tag, Bookmark, Playlist,
276 public class CountArguments : QueryArguments