From: coderhyme Date: Mon, 5 Jun 2017 07:55:45 +0000 (+0900) Subject: [MetadataEditor] Updated comments and exception types thrown from MetadataEditor. X-Git-Tag: submit/trunk/20170823.075128~94^2~10 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=6f81bdda459af550b4fe5d044416ec00bc3172dc;p=platform%2Fcore%2Fcsapi%2Ftizenfx.git [MetadataEditor] Updated comments and exception types thrown from MetadataEditor. Change-Id: I6465393399d9ca36c87885bad4cc61fd3ddb8639 Signed-off-by: coderhyme --- diff --git a/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditor.cs b/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditor.cs index 18bdaf6..aeda76e 100755 --- a/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditor.cs +++ b/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditor.cs @@ -1,32 +1,27 @@ /* -* Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved -* -* Licensed under the Apache License, Version 2.0 (the License); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an AS IS BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - + * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the License); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an AS IS BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ using System; +using System.IO; using System.Runtime.InteropServices; namespace Tizen.Multimedia { - static internal class MetadataEditorLog - { - internal const string LogTag = "Tizen.Multimedia.MetadataEditor"; - } - /// - /// The Metadata editor class provides a set of functions to edit the metadata of the media file + /// Provides a means to edit the metadata of the media file. /// /// /// If you want to access only internal storage, @@ -38,8 +33,9 @@ namespace Tizen.Multimedia { private bool _disposed = false; private IntPtr _handle = IntPtr.Zero; + private bool _isFileReadOnly; - private IntPtr MetadataHandle + private IntPtr Handle { get { @@ -56,10 +52,12 @@ namespace Tizen.Multimedia /// Initializes a new instance of the class with the specified path. /// /// 3 - /// The path of the media file to edit metadata + /// The path of the media file to edit metadata. /// is null. - /// The file is unsupported format. - /// The file does not exist. + /// is a zero-length string, contains only white space. + /// The file is not supported. + /// File does not exist. + /// Caller does not have required privilege to access the file. public MetadataEditor(string path) { if (path == null) @@ -67,18 +65,22 @@ namespace Tizen.Multimedia throw new ArgumentNullException(nameof(path)); } - MetadataEditorError ret = Interop.MetadataEditor.Create(out _handle); - MetadataEditorErrorFactory.ThrowIfError(ret, "Failed to create metadata"); + if (string.IsNullOrWhiteSpace(path)) + { + throw new ArgumentException($"{nameof(path)} is a zero-length string.", nameof(path)); + } + + Interop.MetadataEditor.Create(out _handle).ThrowIfError("Failed to create metadata"); try { - MetadataEditorErrorFactory.ThrowIfError( - Interop.MetadataEditor.SetPath(MetadataHandle, path), "Failed to set path"); + Interop.MetadataEditor.SetPath(Handle, path).ThrowIfError("Failed to set path"); + + _isFileReadOnly = File.GetAttributes(path).HasFlag(FileAttributes.ReadOnly); } catch (Exception) { Interop.MetadataEditor.Destroy(_handle); - _handle = IntPtr.Zero; throw; } } @@ -89,8 +91,8 @@ namespace Tizen.Multimedia try { - MetadataEditorError e = Interop.MetadataEditor.GetMetadata(MetadataHandle, attr, out val); - MetadataEditorErrorFactory.ThrowIfError(e, "Failed to get metadata"); + Interop.MetadataEditor.GetMetadata(Handle, attr, out val) + .ThrowIfError("Failed to get metadata"); return Marshal.PtrToStringAnsi(val); } @@ -102,14 +104,20 @@ namespace Tizen.Multimedia private void SetParam(MetadataEditorAttr attr, string value) { - MetadataEditorErrorFactory.ThrowIfError( - Interop.MetadataEditor.SetMetadata(MetadataHandle, attr, value), "Fail to set value"); + if (_isFileReadOnly) + { + throw new InvalidOperationException("The media file is read-only."); + } + + Interop.MetadataEditor.SetMetadata(Handle, attr, value).ThrowIfError("Failed to set value"); } /// - /// Artist of media + /// Gets or sets the artist of media. /// /// 3 + /// The file is read-only. + /// The has already been disposed. public string Artist { get @@ -124,9 +132,11 @@ namespace Tizen.Multimedia } /// - /// Title of media + /// Gets or sets the title of media. /// /// 3 + /// The file is read-only. + /// The has already been disposed. public string Title { get @@ -141,9 +151,11 @@ namespace Tizen.Multimedia } /// - /// Album name of media + /// Gets or sets the album name of media. /// /// 3 + /// The file is read-only. + /// The has already been disposed. public string Album { get @@ -158,9 +170,11 @@ namespace Tizen.Multimedia } /// - /// Genre of media + /// Gets or sets the genre of media. /// /// 3 + /// The file is read-only. + /// The has already been disposed. public string Genre { get @@ -175,9 +189,11 @@ namespace Tizen.Multimedia } /// - /// Author of media + /// Gets or sets the author of media. /// /// 3 + /// The file is read-only. + /// The has already been disposed. public string Author { get @@ -192,9 +208,11 @@ namespace Tizen.Multimedia } /// - /// Copyright of media + /// Gets or sets the copyright of media. /// /// 3 + /// The file is read-only. + /// The has already been disposed. public string Copyright { get @@ -209,13 +227,15 @@ namespace Tizen.Multimedia } /// - /// Date of media + /// Gets or sets the date of media. /// /// 3 /// - /// If the added media contains ID3 tag, This parameter refers to the recording time. - /// If the added media is a mp4 format, This parameter refers to the year. + /// If the media contains ID3 tag, this refers to the recorded date. + /// If the media is a mp4 format, this refers to the year and the value to set will be converted into integer. /// + /// The file is read-only. + /// The has already been disposed. public string Date { get @@ -230,9 +250,11 @@ namespace Tizen.Multimedia } /// - /// Description of media + /// Gets or sets the description of media. /// /// 3 + /// The file is read-only. + /// The has already been disposed. public string Description { get @@ -247,9 +269,11 @@ namespace Tizen.Multimedia } /// - /// Comment of media + /// Gets or sets the comment of media. /// /// 3 + /// The file is read-only. + /// The has already been disposed. public string Comment { get @@ -264,9 +288,11 @@ namespace Tizen.Multimedia } /// - /// Track number of media + /// Gets or sets the track number of media. /// /// 3 + /// The file is read-only. + /// The has already been disposed. public string TrackNumber { get @@ -281,21 +307,21 @@ namespace Tizen.Multimedia } /// - /// Album art count of media + /// Gets the count of album arts of media. /// /// 3 - public string PictureCount + /// The has already been disposed. + public int PictureCount { - get - { - return GetParam(MetadataEditorAttr.PictureCount); - } + get => int.TryParse(GetParam(MetadataEditorAttr.PictureCount), out var value) ? value : 0; } /// - /// Conductor of media + /// Gets or sets the conductor of media. /// /// 3 + /// The file is read-only. + /// The has already been disposed. public string Conductor { get @@ -310,9 +336,11 @@ namespace Tizen.Multimedia } /// - /// Unsynchronized lyric of media + /// Gets or sets the unsynchronized lyrics of media. /// /// 3 + /// The file is read-only. + /// The has already been disposed. public string UnsyncLyrics { get @@ -327,39 +355,59 @@ namespace Tizen.Multimedia } /// - /// Writes the modified metadata to a media file + /// Writes the modified metadata to the media file. /// - /// 3 - /// When internal process error is occured + /// + /// An internal error occurs.\n + /// -or-\n + /// The file is read-only. + /// + /// The has already been disposed. public void Commit() { - MetadataEditorErrorFactory.ThrowIfError( - Interop.MetadataEditor.UpdateMetadata(MetadataHandle), "Failed to update file"); + if (_isFileReadOnly) + { + throw new InvalidOperationException("The media file is read-only."); + } + + Interop.MetadataEditor.UpdateMetadata(Handle).ThrowIfError("Failed to update file"); } /// - /// Gets the artwork image in a media file + /// Gets the artwork image in the media file. /// /// 3 - /// Index of picture to import - /// Artwork included in the media file - /// When internal process error is occured - /// Wrong index number + /// The index of picture to import. + /// Artwork included in the media file. + /// Artwork included in the media file. + /// An internal error occurs. + /// + /// is less than zero.\n + /// -or-\n + /// is greater than or equal to .\n + /// + /// The has already been disposed. public Artwork GetPicture(int index) { if (index < 0) { - throw new ArgumentOutOfRangeException("Index should be larger than 0 [" + index + "]"); + throw new ArgumentOutOfRangeException(nameof(index), index, + "Index should not be less than zero."); + } + + if (index >= PictureCount) + { + throw new ArgumentOutOfRangeException(nameof(index), index, + "Index should not be greater thor or equal to PictureCount."); } IntPtr data = IntPtr.Zero; - int size; IntPtr mimeType = IntPtr.Zero; try { - MetadataEditorErrorFactory.ThrowIfError( - Interop.MetadataEditor.GetPicture(MetadataHandle, index, out data, out size, out mimeType), "Failed to get the value"); + Interop.MetadataEditor.GetPicture(Handle, index, out data, out var size, out mimeType). + ThrowIfError("Failed to get the value"); if (size > 0) { @@ -390,8 +438,16 @@ namespace Tizen.Multimedia /// /// 3 /// The path of picture for adding to the metadata. - /// Internal error occurs. - /// is null. + /// + /// An internal error occurs.\n + /// -or-\n + /// The media file is read-only. + /// + /// Picture path is null + /// File does not exist. + /// Caller does not have required privilege to access the file. + /// The has already been disposed. + /// The specified file is not supported. public void AddPicture(string path) { if (path == null) @@ -399,17 +455,36 @@ namespace Tizen.Multimedia throw new ArgumentNullException(nameof(path)); } - MetadataEditorErrorFactory.ThrowIfError( - Interop.MetadataEditor.AddPicture(MetadataHandle, path), "Failed to append picture"); + if (File.Exists(path) == false) + { + throw new FileNotFoundException("File does not exist.", path); + } + + if (_isFileReadOnly) + { + throw new InvalidOperationException("The media file is read-only."); + } + + Interop.MetadataEditor.AddPicture(Handle, path). + ThrowIfError("Failed to append picture"); } /// /// Removes the picture from the media file. /// /// 3 - /// Index of picture to remove - /// When internal process error is occured - /// Wrong index number + /// The index of picture to remove. + /// + /// An internal error occurs.\n + /// -or-\n + /// The media file is read-only. + /// + /// + /// is less than zero.\n + /// -or-\n + /// is greater than or equal to .\n + /// + /// The has already been disposed. public void RemovePicture(int index) { if (index < 0) @@ -417,14 +492,20 @@ namespace Tizen.Multimedia throw new ArgumentOutOfRangeException("Index should be larger than 0 [" + index + "]"); } - MetadataEditorErrorFactory.ThrowIfError( - Interop.MetadataEditor.RemovePicture(MetadataHandle, index), "Failed to remove picture"); + if (index >= PictureCount) + { + throw new ArgumentOutOfRangeException(nameof(index), index, + "Index should not be greater thor or equal to PictureCount."); + } + + if (_isFileReadOnly) + { + throw new InvalidOperationException("The media file is read-only."); + } + + Interop.MetadataEditor.RemovePicture(Handle, index).ThrowIfError("Failed to remove picture"); } - /// - /// Metadata Editor destructor - /// - /// 3 ~MetadataEditor() { Dispose(false); @@ -434,11 +515,6 @@ namespace Tizen.Multimedia { if (!_disposed) { - if (disposing) - { - // To be used if there are any other disposable objects - } - if (_handle != IntPtr.Zero) { Interop.MetadataEditor.Destroy(_handle); @@ -449,6 +525,9 @@ namespace Tizen.Multimedia } } + /// + /// Releases all resources used by the object. + /// public void Dispose() { Dispose(true); diff --git a/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditorAttr.cs b/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditorAttr.cs index 30b972b..2c9a018 100644 --- a/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditorAttr.cs +++ b/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditorAttr.cs @@ -1,18 +1,18 @@ /* -* Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved -* -* Licensed under the Apache License, Version 2.0 (the License); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an AS IS BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ + * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the License); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an AS IS BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ namespace Tizen.Multimedia { diff --git a/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditorError.cs b/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditorError.cs new file mode 100644 index 0000000..4459d60 --- /dev/null +++ b/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditorError.cs @@ -0,0 +1,70 @@ +/* + * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the License); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an AS IS BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +using System; +using System.IO; +using Tizen.Internals.Errors; + +namespace Tizen.Multimedia +{ + /// + /// Enumeration for metadata extractor's error codes. + /// + internal enum MetadataEditorError + { + None = ErrorCode.None, + InvalidParameter = ErrorCode.InvalidParameter, + OutOfMemory = ErrorCode.OutOfMemory, + FileNotExists = ErrorCode.FileExists, + PermissionDenied = ErrorCode.PermissionDenied, + NotSupported = ErrorCode.NotSupported, + TizenMetadataEditorError = -0x019C0000, + OperationFailed = TizenMetadataEditorError | 0x01 + } + + internal static class MetadataEditorErrorExtensions + { + internal static void ThrowIfError(this MetadataEditorError errorCode, string errorMessage) + { + if (errorCode == MetadataEditorError.None) + { + return; + } + + switch (errorCode) + { + case MetadataEditorError.InvalidParameter: + throw new ArgumentException(errorMessage); + + case MetadataEditorError.OutOfMemory: + throw new OutOfMemoryException(errorMessage); + + case MetadataEditorError.FileNotExists: + throw new FileNotFoundException(errorMessage); + + case MetadataEditorError.PermissionDenied: + throw new UnauthorizedAccessException(errorMessage); + + case MetadataEditorError.NotSupported: + throw new FileFormatException(errorMessage); + + case MetadataEditorError.OperationFailed: + throw new InvalidOperationException(errorMessage); + } + } + } +} + diff --git a/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditorErrorFactory.cs b/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditorErrorFactory.cs deleted file mode 100644 index 8875b0f..0000000 --- a/src/Tizen.Multimedia.Metadata/MetadataEditor/MetadataEditorErrorFactory.cs +++ /dev/null @@ -1,66 +0,0 @@ -/* -* Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved -* -* Licensed under the Apache License, Version 2.0 (the License); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an AS IS BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -*/ - - -using System; -using System.IO; -using Tizen.Internals.Errors; - -namespace Tizen.Multimedia -{ - /// - /// Enumeration for metadata extractor's error codes. - /// - internal enum MetadataEditorError - { - None = ErrorCode.None, // Success - InvalidParameter = ErrorCode.InvalidParameter, // Invalid parameter - OutOfMemory = ErrorCode.OutOfMemory, // Out of memory - FileNotExists = ErrorCode.FileExists, // File does not exist - PermissionDenied = ErrorCode.PermissionDenied, // Permission deny - NotSupported = ErrorCode.NotSupported, // Unsupported type - TizenMetadataEditorError = -0x019C0000, - OperationFailed = TizenMetadataEditorError | 0x01 // Invalid operation - }; - - internal static class MetadataEditorErrorFactory - { - internal static void ThrowIfError(MetadataEditorError errorCode, string errorMessage) - { - switch (errorCode) - { - case MetadataEditorError.InvalidParameter: - throw new ArgumentException(errorMessage); - - case MetadataEditorError.OutOfMemory: - throw new OutOfMemoryException(errorMessage); - - case MetadataEditorError.FileNotExists: - throw new FileNotFoundException(errorMessage); - - case MetadataEditorError.PermissionDenied: - throw new UnauthorizedAccessException(errorMessage); - - case MetadataEditorError.NotSupported: - throw new NotSupportedException(errorMessage); - - case MetadataEditorError.OperationFailed: - throw new InvalidOperationException(errorMessage); - } - } - } -} - diff --git a/src/Tizen.Multimedia.Metadata/MetadataExtractor/Metadata.cs b/src/Tizen.Multimedia.Metadata/MetadataExtractor/Metadata.cs index 36234ac..4efafa1 100755 --- a/src/Tizen.Multimedia.Metadata/MetadataExtractor/Metadata.cs +++ b/src/Tizen.Multimedia.Metadata/MetadataExtractor/Metadata.cs @@ -103,7 +103,7 @@ namespace Tizen.Multimedia /// public class AudioMetadata { - internal AudioMetadata(int streamCount, IntPtr handle) + private AudioMetadata(int streamCount, IntPtr handle) { Debug.Assert(streamCount > 0); Debug.Assert(handle != IntPtr.Zero); @@ -194,7 +194,7 @@ namespace Tizen.Multimedia Genre = GetMetadata(handle, MetadataExtractorAttr.Genre); Author = GetMetadata(handle, MetadataExtractorAttr.Author); Copyright = GetMetadata(handle, MetadataExtractorAttr.Copyright); - ReleaseDate = GetMetadata(handle, MetadataExtractorAttr.ReleaseDate); + DateReleased = GetMetadata(handle, MetadataExtractorAttr.ReleaseDate); Description = GetMetadata(handle, MetadataExtractorAttr.Description); Comment = GetMetadata(handle, MetadataExtractorAttr.Comment); TrackNumber = GetMetadata(handle, MetadataExtractorAttr.TrackNum); @@ -288,7 +288,7 @@ namespace Tizen.Multimedia /// /// 3 /// A string representing the release date, or null if the information does not exist. - public string ReleaseDate { get; } + public string DateReleased { get; } /// /// Gets the description of the media. diff --git a/src/Tizen.Multimedia.Metadata/Tizen.Multimedia.Metadata.csproj b/src/Tizen.Multimedia.Metadata/Tizen.Multimedia.Metadata.csproj index c486813..1bfa154 100644 --- a/src/Tizen.Multimedia.Metadata/Tizen.Multimedia.Metadata.csproj +++ b/src/Tizen.Multimedia.Metadata/Tizen.Multimedia.Metadata.csproj @@ -3,7 +3,7 @@ - 1.0.0 + 1.0.1 Provides the Multimedia Metadata API for Tizen .NET @@ -20,4 +20,8 @@ + + + +