C# Tag.GetFrames方法代码示例

		/// <summary>
		///    Gets a specified comments frame from the specified tag,
		///    trying to to match the description and language but
		///    accepting an incomplete match.
		/// </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="language">
		///    A <see cref="string" /> specifying the ISO-639-2 language
		///   code to match.
		/// </param>
		/// <returns>
		///    A <see cref="UnsynchronisedLyricsFrame" /> object
		///    containing the matching frame, or <see langword="null" />
		///    if a match wasn't found.
		/// </returns>
		/// <remarks>
		///    <para>The method tries matching with the following order
		///    of precidence:</para>
		///    <list type="number">
		///       <item><term>The first frame with a matching
		///       description and language.</term></item>
		///       <item><term>The first frame with a matching
		///       language.</term></item>
		///       <item><term>The first frame with a matching
		///       description.</term></item>
		///       <item><term>The first frame.</term></item>
		///    </list>
		/// </remarks>
		public static UnsynchronisedLyricsFrame GetPreferred (Tag tag,
		                                                      string description,
		                                                      string language)
		{
			// This is weird, so bear with me. The best thing we can
			// have is something straightforward and in our own
			// language. If it has a description, then it is
			// probably used for something other than an actual
			// comment. If that doesn't work, we'd still rather have
			// something in our language than something in another.
			// After that all we have left are things in other
			// languages, so we'd rather have one with actual
			// content, so we try to get one with no description
			// first.
			
			int best_value = -1;
			UnsynchronisedLyricsFrame best_frame = null;
			
			foreach (Frame frame in tag.GetFrames (FrameType.USLT)) {
				UnsynchronisedLyricsFrame uslt =
					frame as UnsynchronisedLyricsFrame;
				
				if (uslt == null)
					continue;
				
				bool same_name = uslt.Description == description;
				bool same_lang = uslt.Language == language;
				
				if (same_name && same_lang)
					return uslt;
				
				int value = same_lang ? 2 : same_name ? 1 : 0;
				
				if (value <= best_value)
					continue;
				
				best_value = value;
				best_frame = uslt;
			}
			
			return best_frame;
		}

		/// <summary>
		///    Gets a <see cref="TextInformationFrame" /> object of a
		///    specified type from a specified tag, optionally creating
		///    and adding one with a specified encoding if none is
		///    found.
		/// </summary>
		/// <param name="tag">
		///    A <see cref="Tag" /> object to search for the specified
		///    tag in.
		/// </param>
		/// <param name="ident">
		///    A <see cref="ByteVector" /> object containing the frame
		///    identifer to search for.
		/// </param>
		/// <param name="encoding">
		///    A <see cref="StringType" /> value specifying the encoding
		///    to use if a new frame is created.
		/// </param>
		/// <param name="create">
		///    A <see cref="bool" /> value specifying whether or not to
		///    create a new frame if an existing frame was not found.
		/// </param>
		/// <returns>
		///    A <see cref="TextInformationFrame" /> object containing
		///    the frame found in or added to <paramref name="tag" /> or
		///    <see langref="null" /> if no value was found <paramref
		///    name="create" /> is <see langref="false" />.
		/// </returns>
		/// <remarks>
		///    To create a frame without having to specify the encoding,
		///    use <see cref="Get(Tag,ByteVector,bool)" />.
		/// </remarks>
		/// <exception cref="ArgumentNullException">
		///    <paramref name="tag" /> or <paramref name="type" /> is
		///    <see langref="null" />.
		/// </exception>
		/// <exception cref="ArgumentException">
		///    <paramref name="type" /> is not exactly four bytes long.
		/// </exception>
		public static TextInformationFrame Get (Tag tag,
		                                        ByteVector ident,
		                                        StringType encoding,
		                                        bool create)
		{
			if (tag == null)
				throw new ArgumentNullException ("tag");
			
			if (ident == null)
				throw new ArgumentNullException ("ident");
			
			if (ident.Count != 4)
				throw new ArgumentException (
					"Identifier must be four bytes long.",
					"ident");
			
			foreach (TextInformationFrame frame in
				tag.GetFrames<TextInformationFrame> (ident))
				return frame;
			
			if (!create)
				return null;
			
			TextInformationFrame new_frame =
				new TextInformationFrame (ident, encoding);
			tag.AddFrame (new_frame);
			return new_frame;
		}

		/// <summary>
		///    Gets a specified lyrics 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="language">
		///    A <see cref="string" /> specifying the ISO-639-2 language
		///   code 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="UnsynchronisedLyricsFrame" /> object
		///    containing the matching frame, or <see langword="null" />
		///    if a match wasn't found and <paramref name="create" /> is
		///    <see langword="false" />.
		/// </returns>
		public static UnsynchronisedLyricsFrame Get (Tag tag,
		                                             string description,
		                                             string language,
		                                             bool create)
		{
			UnsynchronisedLyricsFrame uslt;
			foreach (Frame frame in tag.GetFrames (FrameType.USLT)) {
				uslt = frame as UnsynchronisedLyricsFrame;
				
				if (uslt == null)
					continue;
				
				if (uslt.Description != description)
					continue;
				
				if (language != null && language != uslt.Language)
					continue;
				
				return uslt;
			}
			
			if (!create)
				return null;
			
			uslt = new UnsynchronisedLyricsFrame (description,
				language);
			tag.AddFrame (uslt);
			return uslt;
		}

		/// <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;
		}

		/// <summary>
		///    Gets a specified terms of use frame from the specified
		///    tag, trying to to match the language but accepting one
		///    with a different language if a match was not found.
		/// </summary>
		/// <param name="tag">
		///    A <see cref="Tag" /> object to search in.
		/// </param>
		/// <param name="language">
		///    A <see cref="string" /> specifying the ISO-639-2 language
		///   code to match.
		/// </param>
		/// <returns>
		///    A <see cref="TermsOfUseFrame" /> object containing the
		///    matching frame, or <see langword="null" /> if a match
		///    wasn't found.
		/// </returns>
		public static TermsOfUseFrame GetPreferred (Tag tag,
		                                            string language)
		{
			TermsOfUseFrame best = null;
			foreach (Frame f in tag.GetFrames (FrameType.USER)) {
				TermsOfUseFrame cf = f as TermsOfUseFrame;
				if (cf == null)
					continue;
				
				if (cf.Language == language)
					return cf;
				
				if (best == null)
					best = cf;
			}
			
			return best;
		}

        /// <summary>
        ///    Gets a <see cref="UrlLinkFrame" /> object of a
        ///    specified type from a specified tag, optionally creating
        ///    and adding one with a specified encoding if none is
        ///    found.
        /// </summary>
        /// <param name="tag">
        ///    A <see cref="Tag" /> object to search for the specified
        ///    tag in.
        /// </param>
        /// <param name="ident">
        ///    A <see cref="ByteVector" /> object containing the frame
        ///    identifer to search for.
        /// </param>
        /// <param name="create">
        ///    A <see cref="bool" /> value specifying whether or not to
        ///    create a new frame if an existing frame was not found.
        /// </param>
        /// <returns>
        ///    A <see cref="UrlLinkFrame" /> object containing
        ///    the frame found in or added to <paramref name="tag" /> or
        ///    <see langword="null" /> if no value was found <paramref
        ///    name="create" /> is <see langword="false" />.
        /// </returns>
        /// <remarks>
        ///    To create a frame without having to specify the encoding,
        ///    use <see cref="Get(Tag,ByteVector,bool)" />.
        /// </remarks>
        /// <exception cref="ArgumentNullException">
        ///    <paramref name="tag" /> or <paramref name="type" /> is
        ///    <see langword="null" />.
        /// </exception>
        /// <exception cref="ArgumentException">
        ///    <paramref name="type" /> is not exactly four bytes long.
        /// </exception>
        public static UrlLinkFrame Get(Tag tag,
            ByteVector ident,
            bool create)
        {
            if (tag == null)
            throw new ArgumentNullException("tag");

              if (ident == null)
            throw new ArgumentNullException("ident");

              if (ident.Count != 4)
            throw new ArgumentException(
              "Identifier must be four bytes long.",
              "ident");

              foreach (UrlLinkFrame frame in
            tag.GetFrames<UrlLinkFrame>(ident))
            return frame;

              if (!create)
            return null;

              UrlLinkFrame new_frame =
            new UrlLinkFrame(ident);
              tag.AddFrame(new_frame);
              return new_frame;
        }

		/// <summary>
		///    Gets a specified comments frame from the specified tag,
		///    trying to to match the description and language but
		///    accepting an incomplete match.
		/// </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="language">
		///    A <see cref="string" /> specifying the ISO-639-2 language
		///   code to match.
		/// </param>
		/// <returns>
		///    A <see cref="CommentsFrame" /> object containing the
		///    matching frame, or <see langword="null" /> if a match
		///    wasn't found.
		/// </returns>
		/// <remarks>
		///    <para>The method tries matching with the following order
		///    of precidence:</para>
		///    <list type="number">
		///       <item><term>The first frame with a matching
		///       description and language.</term></item>
		///       <item><term>The first frame with a matching
		///       language.</term></item>
		///       <item><term>The first frame with a matching
		///       description.</term></item>
		///       <item><term>The first frame.</term></item>
		///    </list>
		/// </remarks>
		public static CommentsFrame GetPreferred (Tag tag,
		                                          string description,
		                                          string language)
		{
			// This is weird, so bear with me. The best thing we can
			// have is something straightforward and in our own
			// language. If it has a description, then it is
			// probably used for something other than an actual
			// comment. If that doesn't work, we'd still rather have
			// something in our language than something in another.
			// After that all we have left are things in other
			// languages, so we'd rather have one with actual
			// content, so we try to get one with no description
			// first.

			bool skip_itunes = description == null ||
				!description.StartsWith ("iTun");
			
			int best_value = -1;
			CommentsFrame best_frame = null;
			
			foreach (Frame frame in tag.GetFrames (FrameType.COMM)) {
				CommentsFrame comm = frame as CommentsFrame;
				
				if (comm == null)
					continue;
				
				if (skip_itunes &&
					comm.Description.StartsWith ("iTun"))
					continue;
				
				bool same_name = comm.Description == description;
				bool same_lang = comm.Language == language;
				
				if (same_name && same_lang)
					return comm;
				
				int value = same_lang ? 2 : same_name ? 1 : 0;
				
				if (value <= best_value)
					continue;
				
				best_value = value;
				best_frame = comm;
			}
			
			return best_frame;
		}

		/// <summary>
		///    Gets a specified terms of use 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="language">
		///    A <see cref="string" /> specifying the ISO-639-2 language
		///   code 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="TermsOfUseFrame" /> object containing the
		///    matching frame, or <see langword="null" /> if a match
		///    wasn't found and <paramref name="create" /> is <see
		///    langword="false" />.
		/// </returns>
		public static TermsOfUseFrame Get (Tag tag, string language,
		                                   bool create)
		{
			foreach (Frame f in tag.GetFrames (FrameType.USER)) {
				TermsOfUseFrame cf = f as TermsOfUseFrame;
				
				if (cf != null && (language == null ||
					language == cf.Language))
					return cf;
			}
			
			if (!create)
				return null;
			
			TermsOfUseFrame frame = new TermsOfUseFrame (language);
			tag.AddFrame (frame);
			return frame;
		}

        /// <summary>
        ///    Gets a specified volume adjustment 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="identification">
        ///    A <see cref="string" /> specifying the identification 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="RelativeVolumeFrame" /> object containing
        ///    the matching frame, or <see langword="null" /> if a match
        ///    wasn't found and <paramref name="create" /> is <see
        ///    langword="false" />.
        /// </returns>
        public static RelativeVolumeFrame Get(Tag tag,
            string identification,
            bool create)
        {
            RelativeVolumeFrame rva2;
            foreach (Frame frame in tag.GetFrames (FrameType.RVA2)) {
                rva2 = frame as RelativeVolumeFrame;

                if (rva2 == null)
                    continue;

                if (rva2.Identification != identification)
                    continue;

                return rva2;
            }

            if (!create)
                return null;

            rva2 = new RelativeVolumeFrame (identification);
            tag.AddFrame (rva2);
            return rva2;
        }

		/// <summary>
		///    Gets a specified comments 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="language">
		///    A <see cref="string" /> specifying the ISO-639-2 language
		///   code 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="CommentsFrame" /> object containing the
		///    matching frame, or <see langword="null" /> if a match
		///    wasn't found and <paramref name="create" /> is <see
		///    langword="false" />.
		/// </returns>
		public static CommentsFrame Get (Tag tag, string description,
		                                 string language, bool create)
		{
			CommentsFrame comm;
			foreach (Frame frame in tag.GetFrames (FrameType.COMM)) {
				comm = frame as CommentsFrame;
				
				if (comm == null)
					continue;
				
				if (comm.Description != description)
					continue;
				
				if (language != null && language != comm.Language)
					continue;
				
				return comm;
			}
			
			if (!create)
				return null;
			
			comm = new CommentsFrame (description, language);
			tag.AddFrame (comm);
			return comm;
		}

		/// <summary>
		///    Gets a specified private 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="owner">
		///    A <see cref="string" /> specifying the owner 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="PrivateFrame" /> object containing the
		///    matching frame, or <see langword="null" /> if a match
		///    wasn't found and <paramref name="create" /> is <see
		///    langword="false" />.
		/// </returns>
		public static PrivateFrame Get (Tag tag, string owner,
		                                bool create)
		{
			PrivateFrame priv;
			
			foreach (Frame frame in tag.GetFrames (FrameType.PRIV)) {
				priv = frame as PrivateFrame;
				if (priv != null && priv.Owner == owner)
					return priv;
			}
			
			if (!create)
				return null;
			
			priv = new PrivateFrame (owner);
			tag.AddFrame (priv);
			return priv;
		}

		/// <summary>
		///    Gets a specified unique file identifer 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="owner">
		///    A <see cref="string" /> specifying the owner 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="UserTextInformationFrame" /> object
		///    containing the matching frame, or <see langword="null" />
		///    if a match wasn't found and <paramref name="create" /> is
		///    <see langword="false" />.
		/// </returns>
		public static UniqueFileIdentifierFrame Get (Tag tag,
		                                             string owner,
		                                             bool create)
		{
			UniqueFileIdentifierFrame ufid;
			
			foreach (Frame frame in tag.GetFrames (FrameType.UFID)) {
				ufid = frame as UniqueFileIdentifierFrame;
				
				if (ufid == null)
					continue;
				
				if (ufid.Owner == owner)
					return ufid;
			}
			
			if (!create)
				return null;
			
			ufid = new UniqueFileIdentifierFrame (owner, null);
			tag.AddFrame (ufid);
			return ufid;
		}

        /// <summary>
        ///    Gets a specified encapsulated object 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="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="GeneralEncapsulatedObjectFrame" /> object
        ///    containing the matching frame, or <see langword="null" />
        ///    if a match wasn't found and <paramref name="create" /> is
        ///    <see langword="false" />.
        /// </returns>
        public static GeneralEncapsulatedObjectFrame Get(Tag tag,
            string description,
            bool create)
        {
            GeneralEncapsulatedObjectFrame geob;
            foreach (Frame frame in tag.GetFrames (FrameType.GEOB)) {
                geob = frame as GeneralEncapsulatedObjectFrame;

                if (geob == null)
                    continue;

                if (geob.Description != description)
                    continue;

                return geob;
            }

            if (!create)
                return null;

            geob = new GeneralEncapsulatedObjectFrame ();
            geob.Description = description;
            tag.AddFrame (geob);
            return geob;
        }

 public static UnsynchronisedLyricsFrame Get (Tag tag, string description, string language, bool create)
 {
    foreach (Frame f in tag.GetFrames (FrameType.USLT))
    {
       UnsynchronisedLyricsFrame cf = f as UnsynchronisedLyricsFrame;
       
       if (cf != null && cf.Description == description && (language == null || language == cf.Language))
          return cf;
    }
    
    if (!create)
       return null;
    
    UnsynchronisedLyricsFrame frame = new UnsynchronisedLyricsFrame (description, language);
    tag.AddFrame (frame);
    return frame;
 }

 public static UniqueFileIdentifierFrame Get (Tag tag, string owner, bool create)
 {
    foreach (Frame f in tag.GetFrames (FrameType.UFID))
       if (f is UniqueFileIdentifierFrame && (f as UniqueFileIdentifierFrame).Owner == owner)
          return f as UniqueFileIdentifierFrame;
    
    if (!create) return null;
    
    UniqueFileIdentifierFrame frame = new UniqueFileIdentifierFrame (owner, null);
    tag.AddFrame (frame);
    return frame;
 }