src/Tizen.Content.MediaContent/Tizen.Content.MediaContent/FolderCommand.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
  19 namespace Tizen.Content.MediaContent
  20 {
  21     /// <summary>
  22     /// Provides commands to manage folders and query related media items in the database.
  23     /// </summary>
  24     public class FolderCommand : MediaCommand
  25     {
  26         /// <summary>
  27         /// Initializes a new instance of the <see cref="FolderCommand"/> class with the specified <see cref="MediaDatabase"/>.
  28         /// </summary>
  29         /// <param name="database">The <see cref="MediaDatabase"/> that the commands run on.</param>
  30         /// <exception cref="ArgumentNullException"><paramref name="database"/> is null.</exception>
  31         /// <exception cref="ObjectDisposedException"><paramref name="database"/> has already been disposed of.</exception>
  32         public FolderCommand(MediaDatabase database) : base(database)
  33         {
  34         }
  35
  36         /// <summary>
  37         /// Retrieves the number of folders.
  38         /// </summary>
  39         /// <returns>The number of folders.</returns>
  40         /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
  41         /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
  42         /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
  43         public int Count()
  44         {
  45             return Count(null);
  46         }
  47
  48         /// <summary>
  49         /// Retrieves the number of folders with the <see cref="CountArguments"/>.
  50         /// </summary>
  51         /// <param name="arguments">The criteria to use to filter. This value can be null.</param>
  52         /// <returns>The number of folders.</returns>
  53         /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
  54         /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
  55         /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
  56         public int Count(CountArguments arguments)
  57         {
  58             ValidateDatabase();
  59
  60             return CommandHelper.Count(Interop.Folder.GetFolderCountFromDb, arguments);
  61         }
  62
  63         /// <summary>
  64         /// Retrieves the folders.
  65         /// </summary>
  66         /// <returns>The <see cref="MediaDataReader{TRecord}"/> containing the results.</returns>
  67         /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
  68         /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
  69         /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
  70         public MediaDataReader<Folder> Select()
  71         {
  72             return Select(arguments: null);
  73         }
  74
  75         /// <summary>
  76         /// Retrieves the folders with the <see cref="SelectArguments"/>.
  77         /// </summary>
  78         /// <param name="arguments">The criteria to use to filter. This value can be null.</param>
  79         /// <returns>The <see cref="MediaDataReader{TRecord}"/> containing the results.</returns>
  80         /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
  81         /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
  82         /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
  83         public MediaDataReader<Folder> Select(SelectArguments arguments)
  84         {
  85             ValidateDatabase();
  86
  87             return CommandHelper.Select(arguments, Interop.Folder.ForeachFolderFromDb, Folder.FromHandle);
  88         }
  89
  90         /// <summary>
  91         /// Retrieves the folder.
  92         /// </summary>
  93         /// <param name="folderId">The folder ID to query with.</param>
  94         /// <returns>The <see cref="Folder"/> instance if the matched record was found in the database, otherwise null.</returns>
  95         /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
  96         /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
  97         /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
  98         /// <exception cref="ArgumentNullException"><paramref name="folderId"/> is null.</exception>
  99         /// <exception cref="ArgumentException"><paramref name="folderId"/> is a zero-length string, contains only white space.</exception>
 100         public Folder Select(string folderId)
 101         {
 102             ValidateDatabase();
 103
 104             ValidationUtil.ValidateNotNullOrEmpty(folderId, nameof(folderId));
 105
 106             Interop.Folder.GetFolderFromDb(folderId, out var handle).ThrowIfError("Failed to query");
 107
 108             if (handle == IntPtr.Zero)
 109             {
 110                 return null;
 111             }
 112
 113             try
 114             {
 115                 return new Folder(handle);
 116             }
 117             finally
 118             {
 119                 Interop.Folder.Destroy(handle);
 120             }
 121         }
 122
 123         /// <summary>
 124         /// Retrieves the number of media information under the folder.
 125         /// </summary>
 126         /// <param name="folderId">The ID of the folder to count media in the folder.</param>
 127         /// <returns>The number of media information.</returns>
 128         /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
 129         /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
 130         /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
 131         /// <exception cref="ArgumentNullException"><paramref name="folderId"/> is null.</exception>
 132         /// <exception cref="ArgumentException"><paramref name="folderId"/> is a zero-length string, contains only white space.</exception>
 133         public int CountMedia(string folderId)
 134         {
 135             return CountMedia(folderId, null);
 136         }
 137
 138         /// <summary>
 139         /// Retrieves the number of media information under the folder with the <see cref="CountArguments"/>.
 140         /// </summary>
 141         /// <param name="folderId">The ID of the folder to count media in the folder.</param>
 142         /// <param name="arguments">The criteria to use to filter. This value can be null.</param>
 143         /// <returns>The number of media information.</returns>
 144         /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
 145         /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
 146         /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
 147         /// <exception cref="ArgumentNullException"><paramref name="folderId"/> is null.</exception>
 148         /// <exception cref="ArgumentException"><paramref name="folderId"/> is a zero-length string, contains only white space.</exception>
 149         public int CountMedia(string folderId, CountArguments arguments)
 150         {
 151             ValidateDatabase();
 152
 153             ValidationUtil.ValidateNotNullOrEmpty(folderId, nameof(folderId));
 154
 155             return CommandHelper.Count(Interop.Folder.GetMediaCountFromDb, folderId, arguments);
 156         }
 157
 158         /// <summary>
 159         /// Retrieves the media information under the folder.
 160         /// </summary>
 161         /// <param name="folderId">The ID of the folder to select media in the folder.</param>
 162         /// <returns>The <see cref="MediaDataReader{TRecord}"/> containing the results.</returns>
 163         /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
 164         /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
 165         /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
 166         /// <exception cref="ArgumentNullException"><paramref name="folderId"/> is null.</exception>
 167         /// <exception cref="ArgumentException"><paramref name="folderId"/> is a zero-length string, contains only white space.</exception>
 168         public MediaDataReader<MediaInfo> SelectMedia(string folderId)
 169         {
 170             return SelectMedia(folderId, null);
 171         }
 172
 173         /// <summary>
 174         /// Retrieves the media information under the folder with the <see cref="SelectArguments"/>.
 175         /// </summary>
 176         /// <param name="folderId">The ID of the folder to select media in the folder.</param>
 177         /// <param name="filter">The criteria to use to filter. This value can be null.</param>
 178         /// <returns>The <see cref="MediaDataReader{TRecord}"/> containing the results.</returns>
 179         /// <exception cref="InvalidOperationException">The <see cref="MediaDatabase"/> is disconnected.</exception>
 180         /// <exception cref="ObjectDisposedException">The <see cref="MediaDatabase"/> has already been disposed of.</exception>
 181         /// <exception cref="MediaDatabaseException">An error occurred while executing the command.</exception>
 182         /// <exception cref="ArgumentNullException"><paramref name="folderId"/> is null.</exception>
 183         /// <exception cref="ArgumentException"><paramref name="folderId"/> is a zero-length string, contains only white space.</exception>
 184         public MediaDataReader<MediaInfo> SelectMedia(string folderId, SelectArguments filter)
 185         {
 186             ValidateDatabase();
 187
 188             ValidationUtil.ValidateNotNullOrEmpty(folderId, nameof(folderId));
 189
 190             return CommandHelper.SelectMedia(Interop.Folder.ForeachMediaFromDb, folderId, filter);
 191         }
 192     }
 193 }