35eada25279e7da2832c730ce67c59618887b746
[platform/core/csapi/tizenfx.git] / src / Tizen.Content.MediaContent / Tizen.Content.MediaContent / TagCommand.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.Collections.Generic;
19 using System.Linq;
20
21 namespace Tizen.Content.MediaContent
22 {
23     /// <summary>
24     /// Provides the commands to manage tags in the database.
25     /// </summary>
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
30     {
31         /// <summary>
32         /// Initializes a new instance of the <see cref="TagCommand"/> class with the specified <see cref="MediaDatabase"/>.
33         /// </summary>
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)
40         {
41         }
42
43         /// <summary>
44         /// Retrieves the number of tags.
45         /// </summary>
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.")]
52         public int Count()
53         {
54             return Count(arguments: null);
55         }
56
57         /// <summary>
58         /// Retrieves the number of tags with the <see cref="CountArguments"/>.
59         /// </summary>
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)
68         {
69             ValidateDatabase();
70
71             return CommandHelper.Count(Interop.Tag.GetTagCount, arguments);
72         }
73
74
75         /// <summary>
76         /// Deletes a tag from the database.
77         /// </summary>
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)
89         {
90             ValidateDatabase();
91
92             if (tagId <= 0)
93             {
94                 throw new ArgumentOutOfRangeException(nameof(tagId), tagId,
95                     "Tag id can't be less than or equal to zero.");
96             }
97
98             if (CommandHelper.Count(Interop.Tag.GetTagCount, $"{TagColumns.Id}={tagId}") == 0)
99             {
100                 return false;
101             }
102
103             CommandHelper.Delete(Interop.Tag.Delete, tagId);
104             return true;
105         }
106
107
108         /// <summary>
109         /// Inserts a tag into the database with the specified name.
110         /// </summary>
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)
122         {
123             ValidateDatabase();
124
125             if (name == null)
126             {
127                 throw new ArgumentNullException(nameof(name));
128             }
129
130             if (name.Length == 0)
131             {
132                 throw new ArgumentException("Tag name can't be an empty string.");
133             }
134
135             Interop.Tag.Insert(name, out var handle).ThrowIfError("Failed to insert a new tag");
136
137             try
138             {
139                 return new Tag(handle);
140             }
141             finally
142             {
143                 Interop.Tag.Destroy(handle);
144             }
145         }
146
147         /// <summary>
148         /// Updates a tag with the specified name.
149         /// </summary>
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)
163         {
164             ValidateDatabase();
165
166             if (tagId <= 0)
167             {
168                 throw new ArgumentOutOfRangeException(nameof(tagId), tagId,
169                     "Tag id can't be less than or equal to zero.");
170             }
171
172             if (name == null)
173             {
174                 throw new ArgumentNullException(nameof(name));
175             }
176
177             if (CommandHelper.Count(Interop.Tag.GetTagCount, $"{TagColumns.Id}={tagId}") == 0)
178             {
179                 return false;
180             }
181
182             Interop.Tag.Create(out var handle).ThrowIfError("Failed to update");
183
184             try
185             {
186                 Interop.Tag.SetName(handle, name).ThrowIfError("Failed to update");
187                 Interop.Tag.Update(tagId, handle).ThrowIfError("Failed to update");
188
189                 return true;
190             }
191             finally
192             {
193                 Interop.Tag.Destroy(handle);
194             }
195         }
196
197         /// <summary>
198         /// Retrieves the tag with the specified ID.
199         /// </summary>
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)
209         {
210             ValidateDatabase();
211
212             if (tagId <= 0)
213             {
214                 throw new ArgumentOutOfRangeException(nameof(tagId), tagId,
215                     "Tag id can't be less than or equal to zero.");
216             }
217
218             IntPtr handle = IntPtr.Zero;
219
220             try
221             {
222                 Interop.Tag.GetTagFromDb(tagId, out handle).ThrowIfError("Failed to query");
223
224                 return new Tag(handle);
225             }
226             catch (ArgumentException)
227             {
228                 // Native FW returns ArgumentException when there's no matched record.
229                 return null;
230             }
231             finally
232             {
233                 if (handle != IntPtr.Zero)
234                 {
235                     Interop.Tag.Destroy(handle);
236                 }
237             }
238
239         }
240
241         /// <summary>
242         /// Retrieves all the tags.
243         /// </summary>
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()
251         {
252             return Select(arguments: null);
253         }
254
255         /// <summary>
256         /// Retrieves the tags with the <see cref="SelectArguments"/>.
257         /// </summary>
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)
266         {
267             ValidateDatabase();
268
269             return CommandHelper.Select(arguments, Interop.Tag.ForeachTagFromDb, Tag.FromHandle);
270         }
271
272         /// <summary>
273         /// Retrieves the number of media info of the tag.
274         /// </summary>
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)
284         {
285             return CountMedia(tagId, null);
286         }
287
288         /// <summary>
289         /// Retrieves the number of the media information of the tag with the <see cref="CountArguments"/>.
290         /// </summary>
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)
301         {
302             ValidateDatabase();
303
304             if (tagId <= 0)
305             {
306                 throw new ArgumentOutOfRangeException(nameof(tagId), tagId,
307                     "Tag id can't be less than or equal to zero.");
308             }
309
310             return CommandHelper.Count(Interop.Tag.GetMediaCount, tagId, arguments);
311         }
312
313         /// <summary>
314         /// Retrieves the media information of the tag.
315         /// </summary>
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)
325         {
326             return SelectMedia(tagId, null);
327         }
328
329         /// <summary>
330         /// Retrieves the media information of the tag with the <see cref="SelectArguments"/>.
331         /// </summary>
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)
342         {
343             ValidateDatabase();
344
345             if (tagId <= 0)
346             {
347                 throw new ArgumentOutOfRangeException(nameof(tagId), tagId,
348                     "Tag id can't be less than or equal to zero.");
349             }
350
351             return CommandHelper.SelectMedia(Interop.Tag.ForeachMediaFromDb, tagId, filter);
352         }
353
354         private bool UpdateMember(int tagId, IEnumerable<string> mediaIds,
355             Func<IntPtr, string, MediaContentError> func)
356         {
357             ValidateDatabase();
358
359             if (tagId <= 0)
360             {
361                 throw new ArgumentOutOfRangeException(nameof(tagId), tagId,
362                     "Tag id can't be less than or equal to zero.");
363             }
364
365             if (mediaIds == null)
366             {
367                 throw new ArgumentNullException(nameof(mediaIds));
368             }
369
370             if (mediaIds.Count() == 0)
371             {
372                 throw new ArgumentException("mediaIds has no element.", nameof(mediaIds));
373             }
374
375             if (CommandHelper.Count(Interop.Tag.GetTagCount, $"{TagColumns.Id}={tagId}") == 0)
376             {
377                 return false;
378             }
379
380             IntPtr handle = IntPtr.Zero;
381             Interop.Tag.Create(out handle).ThrowIfError("Failed to initialize update member operation");
382
383             try
384             {
385                 foreach (var mediaId in mediaIds)
386                 {
387                     if (mediaId == null)
388                     {
389                         throw new ArgumentException("Media id should not be null.", nameof(mediaIds));
390                     }
391
392                     if (string.IsNullOrWhiteSpace(mediaId))
393                     {
394                         throw new ArgumentException("Media id should not be a zero-length string.", nameof(mediaId));
395                     }
396
397                     func(handle, mediaId).ThrowIfError("Failed to update member");
398                 }
399
400                 Interop.Tag.Update(tagId, handle).ThrowIfError("Failed to run member update");
401                 return true;
402             }
403             finally
404             {
405                 if (handle != IntPtr.Zero)
406                 {
407                     Interop.Tag.Destroy(handle);
408                 }
409             }
410         }
411
412         /// <summary>
413         /// Adds the media to a tag.
414         /// </summary>
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)
428         {
429             ValidationUtil.ValidateNotNullOrEmpty(mediaId, nameof(mediaId));
430
431             return AddMedia(tagId, new string[] { mediaId });
432         }
433
434         /// <summary>
435         /// Adds the media set to a tag.
436         /// </summary>
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/>
447         ///     -or-<br/>
448         ///     <paramref name="mediaIds"/> contains null value.<br/>
449         ///     -or-<br/>
450         ///     <paramref name="mediaIds"/> contains a zero-length string, contains only white space.
451         /// </exception>
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)
456         {
457             return UpdateMember(tagId, mediaIds, Interop.Tag.AddMedia);
458         }
459
460         /// <summary>
461         /// Removes the media from a tag.
462         /// </summary>
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)
476         {
477             ValidationUtil.ValidateNotNullOrEmpty(mediaId, nameof(mediaId));
478
479             return RemoveMedia(tagId, new string[] { mediaId });
480         }
481
482         /// <summary>
483         /// Removes the media set from a tag.
484         /// </summary>
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/>
495         ///     -or-<br/>
496         ///     <paramref name="mediaIds"/> contains null value.<br/>
497         ///     -or-<br/>
498         ///     <paramref name="mediaIds"/> contains a zero-length string or white space.
499         /// </exception>
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)
504         {
505             return UpdateMember(tagId, mediaIds, Interop.Tag.RemoveMedia);
506         }
507     }
508 }