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.
19 namespace Tizen.Content.MediaContent
22 /// Provides commands to manage bookmarks in the database.
24 /// <seealso cref="Bookmark"/>
25 public class BookmarkCommand : MediaCommand
28 /// Initializes a new instance of the <see cref="BookmarkCommand"/> class with the specified <see cref="MediaDatabase"/>.
30 /// <param name="database">The <see cref="MediaDatabase"/> that the commands run on.</param>
31 /// <exception cref="ArgumentNullException"><paramref name="database"/> is null.</exception>
32 /// <exception cref="ObjectDisposedException"><paramref name="database"/> has already been disposed of.</exception>
33 public BookmarkCommand(MediaDatabase database) : base(database)
38 /// Retrieves the number of bookmarks.
40 /// <returns>The number of bookmarks.</returns>
41 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
42 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
43 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
50 /// Retrieves the number of bookmarks with <see cref="CountArguments"/>.
52 /// <param name="arguments">The criteria to use to filter. This value can be null.</param>
53 /// <returns>The number of bookmarks.</returns>
54 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
55 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
56 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
57 public int Count(CountArguments arguments)
61 return CommandHelper.Count(Interop.Bookmark.GetCount, arguments);
65 /// Inserts a new bookmark into the database with the specified media and offset.
67 /// <privilege>http://tizen.org/privilege/content.write</privilege>
68 /// <param name="mediaId">The media ID to be associated with.</param>
69 /// <param name="offset">The time offset in milliseconds.</param>
70 /// <returns>The <see cref="Bookmark"/> instance that contains the record information inserted.</returns>
71 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
72 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
73 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
74 /// <exception cref="ArgumentNullException"><paramref name="mediaId"/> is null.</exception>
75 /// <exception cref="ArgumentException"><paramref name="mediaId"/> is a zero-length string, contains only white space.</exception>
76 /// <exception cref="UnauthorizedAccessException">The caller has no required privilege.</exception>
77 public Bookmark Insert(string mediaId, int offset)
79 return Insert(mediaId, offset, null);
83 /// Inserts a new bookmark into the database with the specified media ID, offset, and name.
85 /// <privilege>http://tizen.org/privilege/content.write</privilege>
86 /// <param name="mediaId">The media ID to be associated with.</param>
87 /// <param name="offset">The time offset in milliseconds.</param>
88 /// <param name="name">The name of the bookmark. This value can be null.</param>
89 /// <returns>The <see cref="Bookmark"/> instance that contains the record information inserted.</returns>
90 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
91 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
92 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
93 /// <exception cref="ArgumentNullException"><paramref name="mediaId"/> is null.</exception>
94 /// <exception cref="ArgumentException"><paramref name="mediaId"/> is a zero-length string, contains only white space.</exception>
95 /// <exception cref="UnauthorizedAccessException">The caller has no required privilege.</exception>
96 public Bookmark Insert(string mediaId, int offset, string name)
98 return Insert(mediaId, offset, name, null);
102 /// Inserts a new bookmark into the database with the specified media ID, offset, name, and thumbnail path.
104 /// <privilege>http://tizen.org/privilege/content.write</privilege>
106 /// The thumbnail may be useful only when the media is video.
108 /// <param name="mediaId">The media ID to be associated with.</param>
109 /// <param name="offset">The time offset in milliseconds.</param>
110 /// <param name="name">The name of the bookmark. This value can be null.</param>
111 /// <param name="thumbnailPath">The thumbnail path of the bookmark. This value can be null.</param>
112 /// <returns>The <see cref="Bookmark"/> instance that contains the record information inserted.</returns>
113 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
114 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
115 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
116 /// <exception cref="ArgumentNullException"><paramref name="mediaId"/> is null.</exception>
117 /// <exception cref="ArgumentException"><paramref name="mediaId"/> is a zero-length string, contains only white space.</exception>
118 /// <exception cref="UnauthorizedAccessException">The caller has no required privilege.</exception>
119 public Bookmark Insert(string mediaId, int offset, string name, string thumbnailPath)
123 ValidationUtil.ValidateNotNullOrEmpty(mediaId, nameof(mediaId));
125 Interop.Bookmark.Create(mediaId, offset, out var handle).ThrowIfError("Failed to insert new bookmark");
129 Interop.Bookmark.SetName(handle, name).ThrowIfError("Failed to insert new bookmark");
131 if (thumbnailPath != null)
133 Interop.Bookmark.SetThumbnailPath(handle, thumbnailPath).
134 ThrowIfError("Failed to insert new bookmark");
137 Interop.Bookmark.Insert(handle).ThrowIfError("Failed to insert new bookmark");
139 return new Bookmark(handle);
143 Interop.Bookmark.Destroy(handle);
148 /// Deletes a bookmark from the database.
150 /// <privilege>http://tizen.org/privilege/content.write</privilege>
151 /// <param name="bookmarkId">The bookmark ID to delete.</param>
152 /// <returns>true if the matched record was found and deleted, otherwise false.</returns>
153 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
154 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
155 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
156 /// <exception cref="ArgumentOutOfRangeException"><paramref name="bookmarkId"/> is less than zero.</exception>
157 /// <exception cref="UnauthorizedAccessException">The caller has no required privilege.</exception>
158 public bool Delete(int bookmarkId)
164 throw new ArgumentOutOfRangeException(nameof(bookmarkId), bookmarkId,
165 "Bookmark id shouldn't be negative.");
168 if (CommandHelper.Count(Interop.Bookmark.GetCount, $"{BookmarkColumns.Id}={bookmarkId}") == 0)
173 CommandHelper.Delete(Interop.Bookmark.Delete, bookmarkId);
180 /// Retrieves the bookmarks.
182 /// <returns>The <see cref="MediaDataReader{TRecord}"/> containing the results.</returns>
183 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
184 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
185 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
186 public MediaDataReader<Bookmark> Select()
192 /// Retrieves the bookmarks with <see cref="SelectArguments"/>.
194 /// <param name="filter">The criteria to use to filter. This value can be null.</param>
195 /// <returns>The <see cref="MediaDataReader{TRecord}"/> containing the results.</returns>
196 /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
197 /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
198 /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
199 public MediaDataReader<Bookmark> Select(SelectArguments filter)
203 return CommandHelper.Select(filter, Interop.Bookmark.ForeachFromDb, Bookmark.FromHandle);