/// <summary>
/// Gets a specified picture frame from the specified tag,
/// optionally creating it if it does not exist.
/// </summary>
/// <param name="tag">
/// A <see cref="Tag" /> object to search in.
/// </param>
/// <param name="description">
/// A <see cref="string" /> specifying the description to
/// match.
/// </param>
/// <param name="type">
/// A <see cref="PictureType" /> specifying the picture type
/// to match.
/// </param>
/// <param name="create">
/// A <see cref="bool" /> specifying whether or not to create
/// and add a new frame to the tag if a match is not found.
/// </param>
/// <returns>
/// A <see cref="AttachedPictureFrame" /> object containing
/// the matching frame, or <see langword="null" /> if a match
/// wasn't found and <paramref name="create" /> is <see
/// langword="false" />.
/// </returns>
/// <example>
/// <para>Sets a cover image with a description. Because <see
/// cref="Get(Tag,string,PictureType,bool)" /> is used, if
/// the program is called again with the same audio file and
/// desciption, the picture will be overwritten with the new
/// one.</para>
/// <code lang="C#">
/// using TagLib;
/// using TagLib.Id3v2;
///
/// public static class SetId3v2Cover
/// {
/// public static void Main (string [] args)
/// {
/// if (args.Length != 3)
/// throw new ApplicationException (
/// "USAGE: SetId3v2Cover.exe AUDIO_FILE PICTURE_FILE DESCRIPTION");
///
/// // Create the file. Can throw file to TagLib# exceptions.
/// File file = File.Create (args [0]);
///
/// // Get or create the ID3v2 tag.
/// TagLib.Id3v2.Tag tag = file.GetTag (TagTypes.Id3v2, true) as TagLib.Id3v2.Tag;
/// if (tag == null)
/// throw new ApplicationException ("File does not support ID3v2 tags.");
///
/// // Create a picture. Can throw file related exceptions.
/// TagLib.Picture picture = TagLib.Picture.CreateFromPath (args [1]);
///
/// // Get or create the picture frame.
/// AttachedPictureFrame frame = AttachedPictureFrame.Get (
/// tag, args [2], PictureType.FrontCover, true);
///
/// // Set the data from the picture.
/// frame.MimeType = picture.MimeType;
/// frame.Data = picture.data;
///
/// // Save the file.
/// file.Save ();
/// }
/// }
/// </code>
/// </example>
public static AttachedPictureFrame Get(Tag tag,
string description,
PictureType type,
bool create)
{
AttachedPictureFrame apic;
foreach (Frame frame in tag.GetFrames (FrameType.APIC)) {
apic = frame as AttachedPictureFrame;
if (apic == null)
continue;
if (description != null && apic.Description != description)
continue;
if (type != PictureType.Other && apic.Type != type)
continue;
return apic;
}
if (!create)
return null;
apic = new AttachedPictureFrame ();
apic.Description = description;
apic.Type = type;
tag.AddFrame (apic);
return apic;
}
