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.Collections.Generic;
21 namespace Tizen.Content.MediaContent
24 /// Provides the commands to manage tags in the database.
26 /// <seealso cref="Tag"/>
27 /// <since_tizen> 4 </since_tizen>
28 [Obsolete("Deprecated since API12; Will be removed in API14.")]
29 public class TagCommand : MediaCommand
32 /// Initializes a new instance of the <see cref="TagCommand"/> class with the specified <see cref="MediaDatabase"/>.
34 /// <param name="database">The <see cref="MediaDatabase"/> that the commands run on.</param>
35 /// <exception cref="ArgumentNullException"><paramref name="database"/> is null.</exception>
36 /// <exception cref="ObjectDisposedException"><paramref name="database"/> has already been disposed.</exception>
37 /// <since_tizen> 4 </since_tizen>
38 [Obsolete("Deprecated since API12; Will be removed in API14.")]
39 public TagCommand(MediaDatabase database) : base(database)
44 /// Retrieves the number of tags.
46 /// <returns>The number of tags.</returns>
47 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
48 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
49 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
50 /// <since_tizen> 4 </since_tizen>
51 [Obsolete("Deprecated since API12; Will be removed in API14.")]
54 return Count(arguments: null);
58 /// Retrieves the number of tags with the <see cref="CountArguments"/>.
60 /// <param name="arguments">The criteria to use to filter. This value can be null.</param>
61 /// <returns>The number of tags filtered.</returns>
62 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
63 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
64 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
65 /// <since_tizen> 4 </since_tizen>
66 [Obsolete("Deprecated since API12; Will be removed in API14.")]
67 public int Count(CountArguments arguments)
71 return CommandHelper.Count(Interop.Tag.GetTagCount, arguments);
76 /// Deletes a tag from the database.
78 /// <privilege>http://tizen.org/privilege/content.write</privilege>
79 /// <param name="tagId">The tag ID to delete.</param>
80 /// <returns>true if the matched record was found and deleted, otherwise false.</returns>
81 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
82 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
83 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
84 /// <exception cref="ArgumentOutOfRangeException"><paramref name="tagId"/> is less than or equal to zero.</exception>
85 /// <exception cref="UnauthorizedAccessException">The caller has no required privilege.</exception>
86 /// <since_tizen> 4 </since_tizen>
87 [Obsolete("Deprecated since API12; Will be removed in API14.")]
88 public bool Delete(int tagId)
94 throw new ArgumentOutOfRangeException(nameof(tagId), tagId,
95 "Tag id can't be less than or equal to zero.");
98 if (CommandHelper.Count(Interop.Tag.GetTagCount, $"{TagColumns.Id}={tagId}") == 0)
103 CommandHelper.Delete(Interop.Tag.Delete, tagId);
109 /// Inserts a tag into the database with the specified name.
111 /// <privilege>http://tizen.org/privilege/content.write</privilege>
112 /// <param name="name">The name of tag.</param>
113 /// <returns>The <see cref="Tag"/> instance that contains the record information inserted.</returns>
114 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
115 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
116 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
117 /// <exception cref="ArgumentNullException"><paramref name="name"/> is null.</exception>
118 /// <exception cref="UnauthorizedAccessException">The caller has no required privilege.</exception>
119 /// <since_tizen> 4 </since_tizen>
120 [Obsolete("Deprecated since API12; Will be removed in API14.")]
121 public Tag Insert(string name)
127 throw new ArgumentNullException(nameof(name));
130 if (name.Length == 0)
132 throw new ArgumentException("Tag name can't be an empty string.");
135 Interop.Tag.Insert(name, out var handle).ThrowIfError("Failed to insert a new tag");
139 return new Tag(handle);
143 Interop.Tag.Destroy(handle);
148 /// Updates a tag with the specified name.
150 /// <privilege>http://tizen.org/privilege/content.write</privilege>
151 /// <param name="tagId">The tag ID to update.</param>
152 /// <param name="name">The new name.</param>
153 /// <returns>true if the matched record was found and updated, otherwise false.</returns>
154 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
155 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
156 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
157 /// <exception cref="ArgumentNullException"><paramref name="name"/> is null.</exception>
158 /// <exception cref="ArgumentOutOfRangeException"><paramref name="tagId"/> is less than or equal to zero.</exception>
159 /// <exception cref="UnauthorizedAccessException">The caller has no required privilege.</exception>
160 /// <since_tizen> 4 </since_tizen>
161 [Obsolete("Deprecated since API12; Will be removed in API14.")]
162 public bool UpdateName(int tagId, string name)
168 throw new ArgumentOutOfRangeException(nameof(tagId), tagId,
169 "Tag id can't be less than or equal to zero.");
174 throw new ArgumentNullException(nameof(name));
177 if (CommandHelper.Count(Interop.Tag.GetTagCount, $"{TagColumns.Id}={tagId}") == 0)
182 Interop.Tag.Create(out var handle).ThrowIfError("Failed to update");
186 Interop.Tag.SetName(handle, name).ThrowIfError("Failed to update");
187 Interop.Tag.Update(tagId, handle).ThrowIfError("Failed to update");
193 Interop.Tag.Destroy(handle);
198 /// Retrieves the tag with the specified ID.
200 /// <param name="tagId">The tag ID to select.</param>
201 /// <returns>The <see cref="Tag"/> instance if the matched record was found in the database, otherwise null.</returns>
202 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
203 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
204 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
205 /// <exception cref="ArgumentOutOfRangeException"><paramref name="tagId"/> is less than or equal to zero.</exception>
206 /// <since_tizen> 4 </since_tizen>
207 [Obsolete("Deprecated since API12; Will be removed in API14.")]
208 public Tag Select(int tagId)
214 throw new ArgumentOutOfRangeException(nameof(tagId), tagId,
215 "Tag id can't be less than or equal to zero.");
218 IntPtr handle = IntPtr.Zero;
222 Interop.Tag.GetTagFromDb(tagId, out handle).ThrowIfError("Failed to query");
224 return new Tag(handle);
226 catch (ArgumentException)
228 // Native FW returns ArgumentException when there's no matched record.
233 if (handle != IntPtr.Zero)
235 Interop.Tag.Destroy(handle);
242 /// Retrieves all the tags.
244 /// <returns>The <see cref="MediaDataReader{TRecord}"/> containing the results.</returns>
245 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
246 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
247 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
248 /// <since_tizen> 4 </since_tizen>
249 [Obsolete("Deprecated since API12; Will be removed in API14.")]
250 public MediaDataReader<Tag> Select()
252 return Select(arguments: null);
256 /// Retrieves the tags with the <see cref="SelectArguments"/>.
258 /// <param name="arguments">The criteria to use to filter. This value can be null.</param>
259 /// <returns>The <see cref="MediaDataReader{TRecord}"/> containing the results.</returns>
260 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
261 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
262 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
263 /// <since_tizen> 4 </since_tizen>
264 [Obsolete("Deprecated since API12; Will be removed in API14.")]
265 public MediaDataReader<Tag> Select(SelectArguments arguments)
269 return CommandHelper.Select(arguments, Interop.Tag.ForeachTagFromDb, Tag.FromHandle);
273 /// Retrieves the number of media info of the tag.
275 /// <param name="tagId">The tag ID.</param>
276 /// <returns>The number of the media information.</returns>
277 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
278 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
279 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
280 /// <exception cref="ArgumentOutOfRangeException"><paramref name="tagId"/> is less than or equal to zero.</exception>
281 /// <since_tizen> 4 </since_tizen>
282 [Obsolete("Deprecated since API12; Will be removed in API14.")]
283 public int CountMedia(int tagId)
285 return CountMedia(tagId, null);
289 /// Retrieves the number of the media information of the tag with the <see cref="CountArguments"/>.
291 /// <param name="tagId">The tag ID to query with.</param>
292 /// <param name="arguments">The criteria to use to filter. This value can be null.</param>
293 /// <returns>The number of the media information.</returns>
294 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
295 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
296 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
297 /// <exception cref="ArgumentOutOfRangeException"><paramref name="tagId"/> is less than or equal to zero.</exception>
298 /// <since_tizen> 4 </since_tizen>
299 [Obsolete("Deprecated since API12; Will be removed in API14.")]
300 public int CountMedia(int tagId, CountArguments arguments)
306 throw new ArgumentOutOfRangeException(nameof(tagId), tagId,
307 "Tag id can't be less than or equal to zero.");
310 return CommandHelper.Count(Interop.Tag.GetMediaCount, tagId, arguments);
314 /// Retrieves the media information of the tag.
316 /// <param name="tagId">The tag ID.</param>
317 /// <returns>The <see cref="MediaDataReader{TRecord}"/> containing the results.</returns>
318 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
319 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
320 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
321 /// <exception cref="ArgumentOutOfRangeException"><paramref name="tagId"/> is less than or equal to zero.</exception>
322 /// <since_tizen> 4 </since_tizen>
323 [Obsolete("Deprecated since API12; Will be removed in API14.")]
324 public MediaDataReader<MediaInfo> SelectMedia(int tagId)
326 return SelectMedia(tagId, null);
330 /// Retrieves the media information of the tag with the <see cref="SelectArguments"/>.
332 /// <param name="tagId">The tag ID.</param>
333 /// <param name="filter">The criteria to use to filter. This value can be null.</param>
334 /// <returns>The <see cref="MediaDataReader{TRecord}"/> containing the results.</returns>
335 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
336 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
337 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
338 /// <exception cref="ArgumentOutOfRangeException"><paramref name="tagId"/> is less than or equal to zero.</exception>
339 /// <since_tizen> 4 </since_tizen>
340 [Obsolete("Deprecated since API12; Will be removed in API14.")]
341 public MediaDataReader<MediaInfo> SelectMedia(int tagId, SelectArguments filter)
347 throw new ArgumentOutOfRangeException(nameof(tagId), tagId,
348 "Tag id can't be less than or equal to zero.");
351 return CommandHelper.SelectMedia(Interop.Tag.ForeachMediaFromDb, tagId, filter);
354 private bool UpdateMember(int tagId, IEnumerable<string> mediaIds,
355 Func<IntPtr, string, MediaContentError> func)
361 throw new ArgumentOutOfRangeException(nameof(tagId), tagId,
362 "Tag id can't be less than or equal to zero.");
365 if (mediaIds == null)
367 throw new ArgumentNullException(nameof(mediaIds));
370 if (mediaIds.Count() == 0)
372 throw new ArgumentException("mediaIds has no element.", nameof(mediaIds));
375 if (CommandHelper.Count(Interop.Tag.GetTagCount, $"{TagColumns.Id}={tagId}") == 0)
380 IntPtr handle = IntPtr.Zero;
381 Interop.Tag.Create(out handle).ThrowIfError("Failed to initialize update member operation");
385 foreach (var mediaId in mediaIds)
389 throw new ArgumentException("Media id should not be null.", nameof(mediaIds));
392 if (string.IsNullOrWhiteSpace(mediaId))
394 throw new ArgumentException("Media id should not be a zero-length string.", nameof(mediaId));
397 func(handle, mediaId).ThrowIfError("Failed to update member");
400 Interop.Tag.Update(tagId, handle).ThrowIfError("Failed to run member update");
405 if (handle != IntPtr.Zero)
407 Interop.Tag.Destroy(handle);
413 /// Adds the media to a tag.
415 /// <param name="tagId">The tag ID that the media will be added to.</param>
416 /// <param name="mediaId">The media ID to add to the tag.</param>
417 /// <returns>true if the matched record was found and updated, otherwise false.</returns>
418 /// <remarks>The invalid media ID will be ignored.</remarks>
419 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
420 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
421 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
422 /// <exception cref="ArgumentNullException"><paramref name="mediaId"/> is null.</exception>
423 /// <exception cref="ArgumentException"><paramref name="mediaId"/> is a zero-length string, contains only white space.</exception>
424 /// <exception cref="ArgumentOutOfRangeException"><paramref name="tagId"/> is less than or equal to zero.</exception>
425 /// <since_tizen> 4 </since_tizen>
426 [Obsolete("Deprecated since API12; Will be removed in API14.")]
427 public bool AddMedia(int tagId, string mediaId)
429 ValidationUtil.ValidateNotNullOrEmpty(mediaId, nameof(mediaId));
431 return AddMedia(tagId, new string[] { mediaId });
435 /// Adds the media set to a tag.
437 /// <param name="tagId">The tag ID that the media will be added to.</param>
438 /// <param name="mediaIds">The media ID to add to the tag.</param>
439 /// <returns>true if the matched record was found and updated, otherwise false.</returns>
440 /// <remarks>The invalid media IDs will be ignored.</remarks>
441 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
442 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
443 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
444 /// <exception cref="ArgumentNullException"><paramref name="mediaIds"/> is null.</exception>
445 /// <exception cref="ArgumentException">
446 /// <paramref name="mediaIds"/> has no element.<br/>
448 /// <paramref name="mediaIds"/> contains null value.<br/>
450 /// <paramref name="mediaIds"/> contains a zero-length string, contains only white space.
452 /// <exception cref="ArgumentOutOfRangeException"><paramref name="tagId"/> is less than or equal to zero.</exception>
453 /// <since_tizen> 4 </since_tizen>
454 [Obsolete("Deprecated since API12; Will be removed in API14.")]
455 public bool AddMedia(int tagId, IEnumerable<string> mediaIds)
457 return UpdateMember(tagId, mediaIds, Interop.Tag.AddMedia);
461 /// Removes the media from a tag.
463 /// <param name="tagId">The tag ID.</param>
464 /// <param name="mediaId">The media ID to remove from the tag.</param>
465 /// <returns>true if the matched record was found and updated, otherwise false.</returns>
466 /// <remarks>The invalid media ID will be ignored.</remarks>
467 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
468 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
469 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
470 /// <exception cref="ArgumentNullException"><paramref name="mediaId"/> is null.</exception>
471 /// <exception cref="ArgumentException"><paramref name="mediaId"/> is a zero-length string, contains only white space.</exception>
472 /// <exception cref="ArgumentOutOfRangeException"><paramref name="tagId"/> is less than or equal to zero.</exception>
473 /// <since_tizen> 4 </since_tizen>
474 [Obsolete("Deprecated since API12; Will be removed in API14.")]
475 public bool RemoveMedia(int tagId, string mediaId)
477 ValidationUtil.ValidateNotNullOrEmpty(mediaId, nameof(mediaId));
479 return RemoveMedia(tagId, new string[] { mediaId });
483 /// Removes the media set from a tag.
485 /// <param name="tagId">The tag ID.</param>
486 /// <param name="mediaIds">The collection of media ID to remove from the tag.</param>
487 /// <returns>true if the matched record was found and updated, otherwise false.</returns>
488 /// <remarks>The invalid IDs will be ignored.</remarks>
489 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
490 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed.</exception>
491 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
492 /// <exception cref="ArgumentNullException"><paramref name="mediaIds"/> is null.</exception>
493 /// <exception cref="ArgumentException">
494 /// <paramref name="mediaIds"/> has no element.<br/>
496 /// <paramref name="mediaIds"/> contains null value.<br/>
498 /// <paramref name="mediaIds"/> contains a zero-length string or white space.
500 /// <exception cref="ArgumentOutOfRangeException"><paramref name="tagId"/> is less than or equal to zero.</exception>
501 /// <since_tizen> 4 </since_tizen>
502 [Obsolete("Deprecated since API12; Will be removed in API14.")]
503 public bool RemoveMedia(int tagId, IEnumerable<string> mediaIds)
505 return UpdateMember(tagId, mediaIds, Interop.Tag.RemoveMedia);