C# Class TagLib.File

This abstract class provides a basic framework for reading from and writing to a file, as well as accessing basic tagging and media properties.

This class is agnostic to all specific media types. Its child classes, on the other hand, support the the intricacies of different media and tagging formats. For example, supports the MPEG-4 specificication and Apple's tagging format.

Each file type can be created using its format specific constructors, ie. Mpeg4.File(string), but the preferred method is to use or one of its variants, as it automatically detects the appropriate class from the file extension or provided mime-type.

Inheritance: IDisposable

Show file Open project: secred/Tachycardia Class Usage Examples

Public Methods

Method	Description
AddFileTypeResolver ( FileTypeResolver resolver ) : void	Adds a FileTypeResolver to the class. The one added last gets run first. A FileTypeResolver adds support for recognizing a file type outside of the standard mime-type methods.
Create ( IFileAbstraction abstraction ) : File	Creates a new instance of a File subclass for a specified file abstraction, guessing the mime-type from the file's extension and using the average read style.
Create ( IFileAbstraction abstraction, ReadStyle propertiesStyle ) : File	Creates a new instance of a File subclass for a specified file abstraction and read style, guessing the mime-type from the file's extension.
Create ( IFileAbstraction abstraction, string mimetype, ReadStyle propertiesStyle ) : File	Creates a new instance of a File subclass for a specified file abstraction, mime-type, and read style.
Create ( string path ) : File	Creates a new instance of a File subclass for a specified path, guessing the mime-type from the file's extension and using the average read style.
Create ( string path, ReadStyle propertiesStyle ) : File	Creates a new instance of a File subclass for a specified path and read style, guessing the mime-type from the file's extension.
Create ( string path, string mimetype, ReadStyle propertiesStyle ) : File	Creates a new instance of a File subclass for a specified path, mime-type, and read style.
Dispose ( ) : void
Find ( ByteVector pattern ) : long	Searches forwards through a file for a specified pattern, starting at the beginning of the file.
Find ( ByteVector pattern, long startPosition ) : long	Searches forwards through a file for a specified pattern, starting at a specified offset.
Find ( ByteVector pattern, long startPosition, ByteVector before ) : long	Searches forwards through a file for a specified pattern, starting at a specified offset.
Insert ( ByteVector data, long start ) : void	Inserts a specifed block of data into the file repesented by the current instance at a specified location. This method inserts a new block of data into the file. To replace an existing block, ie. replacing an existing tag with a new one of different size, use .
Insert ( ByteVector data, long start, long replace ) : void	Inserts a specifed block of data into the file repesented by the current instance at a specified location, replacing a specified number of bytes.
RFind ( ByteVector pattern ) : long	Searches backwards through a file for a specified pattern, starting at the end of the file.
RFind ( ByteVector pattern, long startPosition ) : long	Searches backwards through a file for a specified pattern, starting at a specified offset.
ReadBlock ( int length ) : ByteVector	Removes a set of tag types from the current instance. Gets a tag of a specified type from the current instance, optionally creating a new tag if possible. Gets a tag of a specified type from the current instance. Reads a specified number of bytes at the current seek position from the current instance. In order to remove all tags from a file, pass as types. Passing to does not guarantee the tag will be created. For example, trying to create an ID3v2 tag on an OGG Vorbis file will always fail. It is safe to assume that if is not returned, the returned tag can be cast to the appropriate type. This class merely accesses the tag if it exists. GetTag(TagTypes,bool) provides the option of adding the tag to the current instance if it does not exist. It is safe to assume that if is not returned, the returned tag can be cast to the appropriate type. This method reads the block of data at the current seek position. To change the seek position, use .
RemoveBlock ( long start, long length ) : void	Removes a specified block of data from the file represented by the current instance.
Save ( ) : void	Saves the changes made in the current instance to the file it represents.
Seek ( long offset ) : void	Seeks the read/write pointer to a specified offset in the current instance, relative to the beginning of the file.
Seek ( long offset, System origin ) : void	Seeks the read/write pointer to a specified offset in the current instance, relative to a specified origin.
WriteBlock ( ByteVector data ) : void	Writes a block of data to the file represented by the current instance at the current seek position. This will overwrite any existing data at the seek position and append new data to the file if writing past the current end.

Protected Methods

Method	Description
File ( IFileAbstraction abstraction ) : System	Constructs and initializes a new instance of for a specified file abstraction.
File ( string path ) : System	Constructs and initializes a new instance of for a specified path in the local file system.
Truncate ( long length ) : void	Resized the current instance to a specified number of bytes.

Private Methods

Method	Description
RFind ( ByteVector pattern, long startPosition, ByteVector after ) : long	Searches backwards through a file for a specified pattern, starting at a specified offset. Searching for after is not yet implemented.

Method Details

AddFileTypeResolver() public static method

Adds a FileTypeResolver to the class. The one added last gets run first.

A FileTypeResolver adds support for recognizing a file type outside of the standard mime-type methods.

public static AddFileTypeResolver ( FileTypeResolver resolver ) : void
resolver	FileTypeResolver	/// A delegate to add to the /// file type recognition stack. ///
return	void

Create() public static method

Creates a new instance of a File subclass for a specified file abstraction, guessing the mime-type from the file's extension and using the average read style.

/// The file could not be read due to corruption. /// /// The file could not be read because the mime-type could /// not be resolved or the library does not support an /// internal feature of the file crucial to its reading. ///

public static Create ( IFileAbstraction abstraction ) : File
abstraction	IFileAbstraction	/// A object to use when /// reading to and writing from the current instance. ///
return	File

Create() public static method

Creates a new instance of a File subclass for a specified file abstraction and read style, guessing the mime-type from the file's extension.

public static Create ( IFileAbstraction abstraction, ReadStyle propertiesStyle ) : File
abstraction	IFileAbstraction	/// A object to use when /// reading to and writing from the current instance. ///
propertiesStyle	ReadStyle	/// A value specifying the level of /// detail to use when reading the media information from the /// new instance. ///
return	File

Create() public static method

Creates a new instance of a File subclass for a specified file abstraction, mime-type, and read style.

public static Create ( IFileAbstraction abstraction, string mimetype, ReadStyle propertiesStyle ) : File
abstraction	IFileAbstraction	/// A object to use when /// reading to and writing from the current instance. ///
mimetype	string	/// A object containing the mime-type /// to use when selecting the appropriate class to use, or /// if the extension in is to be used. ///
propertiesStyle	ReadStyle	/// A value specifying the level of /// detail to use when reading the media information from the /// new instance. ///
return	File

Create() public static method

Creates a new instance of a File subclass for a specified path, guessing the mime-type from the file's extension and using the average read style.

public static Create ( string path ) : File
path	string	/// A object specifying the file to /// read from and write to. ///
return	File

Create() public static method

Creates a new instance of a File subclass for a specified path and read style, guessing the mime-type from the file's extension.

public static Create ( string path, ReadStyle propertiesStyle ) : File
path	string	/// A object specifying the file to /// read from and write to. ///
propertiesStyle	ReadStyle	/// A value specifying the level of /// detail to use when reading the media information from the /// new instance. ///
return	File

Create() public static method

Creates a new instance of a File subclass for a specified path, mime-type, and read style.

public static Create ( string path, string mimetype, ReadStyle propertiesStyle ) : File
path	string	/// A object specifying the file to /// read from and write to. ///
mimetype	string	/// A object containing the mime-type /// to use when selecting the appropriate class to use, or /// if the extension in is to be used. ///
propertiesStyle	ReadStyle	/// A value specifying the level of /// detail to use when reading the media information from the /// new instance. ///
return	File

Dispose() public method

public Dispose ( ) : void
return	void

File() protected method

Constructs and initializes a new instance of for a specified file abstraction.

/// is . ///

protected File ( IFileAbstraction abstraction ) : System
abstraction	IFileAbstraction	/// A object to use when /// reading from and writing to the file. ///
return	System

File() protected method

Constructs and initializes a new instance of for a specified path in the local file system.

/// is . ///

protected File ( string path ) : System
path	string	/// A object containing the path of the /// file to use in the new instance. ///
return	System

Find() public method

Searches forwards through a file for a specified pattern, starting at the beginning of the file.

/// is . ///

public Find ( ByteVector pattern ) : long
pattern	ByteVector	/// A object containing a pattern /// to search for in the current instance. ///
return	long

Find() public method

Searches forwards through a file for a specified pattern, starting at a specified offset.

/// is . ///

public Find ( ByteVector pattern, long startPosition ) : long
pattern	ByteVector	/// A object containing a pattern /// to search for in the current instance. ///
startPosition	long	/// A value specifying at what /// seek position to start searching. ///
return	long

Find() public method

Searches forwards through a file for a specified pattern, starting at a specified offset.

/// is . ///

public Find ( ByteVector pattern, long startPosition, ByteVector before ) : long
pattern	ByteVector	/// A object containing a pattern /// to search for in the current instance. ///
startPosition	long	/// A value specifying at what /// seek position to start searching. ///
before	ByteVector	/// A object specifying a pattern /// that the searched for pattern must appear before. If this /// pattern is found first, -1 is returned. ///
return	long

Insert() public method

Inserts a specifed block of data into the file repesented by the current instance at a specified location.

This method inserts a new block of data into the file. To replace an existing block, ie. replacing an existing tag with a new one of different size, use .

/// is . ///

public Insert ( ByteVector data, long start ) : void
data	ByteVector	/// A object containing the data to /// insert into the file. ///
start	long	/// A value specifying at which point to /// insert the data. ///
return	void

Insert() public method

Inserts a specifed block of data into the file repesented by the current instance at a specified location, replacing a specified number of bytes.

/// is . ///

public Insert ( ByteVector data, long start, long replace ) : void
data	ByteVector	/// A object containing the data to /// insert into the file. ///
start	long	/// A value specifying at which point to /// insert the data. ///
replace	long	/// A value specifying the number of /// bytes to replace. Typically this is the original size of /// the data block so that a new block will replace the old /// one. ///
return	void

RFind() public method

Searches backwards through a file for a specified pattern, starting at the end of the file.

/// is . ///

public RFind ( ByteVector pattern ) : long
pattern	ByteVector	/// A object containing a pattern /// to search for in the current instance. ///
return	long

RFind() public method

Searches backwards through a file for a specified pattern, starting at a specified offset.

/// is . ///

public RFind ( ByteVector pattern, long startPosition ) : long
pattern	ByteVector	/// A object containing a pattern /// to search for in the current instance. ///
startPosition	long	/// A value specifying at what /// seek position to start searching. ///
return	long

ReadBlock() public method

Removes a set of tag types from the current instance. Gets a tag of a specified type from the current instance, optionally creating a new tag if possible. Gets a tag of a specified type from the current instance. Reads a specified number of bytes at the current seek position from the current instance.

In order to remove all tags from a file, pass as types.

Passing to does not guarantee the tag will be created. For example, trying to create an ID3v2 tag on an OGG Vorbis file will always fail.

It is safe to assume that if is not returned, the returned tag can be cast to the appropriate type.

This class merely accesses the tag if it exists. GetTag(TagTypes,bool) provides the option of adding the tag to the current instance if it does not exist.

It is safe to assume that if is not returned, the returned tag can be cast to the appropriate type.

This method reads the block of data at the current seek position. To change the seek position, use .

/// is less than zero. ///

public ReadBlock ( int length ) : ByteVector
length	int	/// A value specifying the number of bytes /// to read. ///
return	ByteVector

RemoveBlock() public method

Removes a specified block of data from the file represented by the current instance.

public RemoveBlock ( long start, long length ) : void
start	long	/// A value specifying at which point to /// remove data. ///
length	long	/// A value specifying the number of /// bytes to remove. ///
return	void

Save() public abstract method

Saves the changes made in the current instance to the file it represents.

public abstract Save ( ) : void
return	void

Seek() public method

Seeks the read/write pointer to a specified offset in the current instance, relative to the beginning of the file.

public Seek ( long offset ) : void
offset	long	/// A value indicating the byte offset to /// seek to. ///
return	void

Seek() public method

Seeks the read/write pointer to a specified offset in the current instance, relative to a specified origin.

public Seek ( long offset, System origin ) : void
offset	long	/// A value indicating the byte offset to /// seek to. ///
origin	System	/// A value specifying an /// origin to seek from. ///
return	void

Truncate() protected method

Resized the current instance to a specified number of bytes.

protected Truncate ( long length ) : void
length	long	/// A value specifying the number of /// bytes to resize the file to. ///
return	void

WriteBlock() public method

Writes a block of data to the file represented by the current instance at the current seek position.

This will overwrite any existing data at the seek position and append new data to the file if writing past the current end.

/// is . ///

public WriteBlock ( ByteVector data ) : void
data	ByteVector	/// A object containing data to be /// written to the current instance. ///
return	void