TagLib API Documentation
Classes | Public Member Functions | Static Public Member Functions | List of all members
TagLib::FileRef Class Reference

This class provides a simple abstraction for creating and handling files. More...

#include <fileref.h>

Classes

class  FileTypeResolver
 A class for pluggable file type resolution. More...
 
class  StreamTypeResolver
 

Public Member Functions

 FileRef ()
 
 FileRef (FileName fileName, bool readAudioProperties=true, AudioProperties::ReadStyle audioPropertiesStyle=AudioProperties::Average)
 
 FileRef (IOStream *stream, bool readAudioProperties=true, AudioProperties::ReadStyle audioPropertiesStyle=AudioProperties::Average)
 
 FileRef (File *file)
 
 FileRef (const FileRef &ref)
 
virtual ~FileRef ()
 
Tag * tag () const
 
AudioProperties * audioProperties () const
 
File * file () const
 
bool save ()
 
bool isNull () const
 
FileRef & operator= (const FileRef &ref)
 
void swap (FileRef &ref)
 
bool operator== (const FileRef &ref) const
 
bool operator!= (const FileRef &ref) const
 

Static Public Member Functions

static const FileTypeResolver * addFileTypeResolver (const FileTypeResolver *resolver)
 
static StringList defaultFileExtensions ()
 
static File * create (FileName fileName, bool readAudioProperties=true, AudioProperties::ReadStyle audioPropertiesStyle=AudioProperties::Average)
 

Detailed Description

This class provides a simple abstraction for creating and handling files.

FileRef exists to provide a minimal, generic and value-based wrapper around a File. It is lightweight and implicitly shared, and as such suitable for pass-by-value use. This hides some of the uglier details of TagLib::File and the non-generic portions of the concrete file implementations.

This class is useful in a "simple usage" situation where it is desirable to be able to get and set some of the tag information that is similar across file types.

Also note that it is probably a good idea to plug this into your mime type system rather than using the constructor that accepts a file name using the FileTypeResolver.

See also
FileTypeResolver
addFileTypeResolver()

Constructor & Destructor Documentation

◆ FileRef() [1/5]

TagLib::FileRef::FileRef ( )

Creates a null FileRef.

◆ FileRef() [2/5]

TagLib::FileRef::FileRef ( FileName  fileName,
bool  readAudioProperties = true,
AudioProperties::ReadStyle  audioPropertiesStyle = AudioProperties::Average 
)
explicit

Create a FileRef from fileName. If readAudioProperties is true then the audio properties will be read using audioPropertiesStyle. If readAudioProperties is false then audioPropertiesStyle will be ignored.

Also see the note in the class documentation about why you may not want to use this method in your application.

◆ FileRef() [3/5]

TagLib::FileRef::FileRef ( IOStream *  stream,
bool  readAudioProperties = true,
AudioProperties::ReadStyle  audioPropertiesStyle = AudioProperties::Average 
)
explicit

Construct a FileRef from an opened IOStream. If readAudioProperties is true then the audio properties will be read using audioPropertiesStyle. If readAudioProperties is false then audioPropertiesStyle will be ignored.

Also see the note in the class documentation about why you may not want to use this method in your application.

Note
TagLib will not take ownership of the stream, the caller is responsible for deleting it after the File object.

◆ FileRef() [4/5]

TagLib::FileRef::FileRef ( File *  file)
explicit

Construct a FileRef using file. The FileRef now takes ownership of the pointer and will delete the File when it passes out of scope.

◆ FileRef() [5/5]

TagLib::FileRef::FileRef ( const FileRef &  ref)

Make a copy of ref.

◆ ~FileRef()

virtual TagLib::FileRef::~FileRef ( )
virtual

Destroys this FileRef instance.

Member Function Documentation

◆ addFileTypeResolver()

static const FileTypeResolver* TagLib::FileRef::addFileTypeResolver ( const FileTypeResolver *  resolver)
static

Adds a FileTypeResolver to the list of those used by TagLib. Each additional FileTypeResolver is added to the front of a list of resolvers that are tried. If the FileTypeResolver returns zero the next resolver is tried.

Returns a pointer to the added resolver (the same one that's passed in – this is mostly so that static initializers have something to use for assignment).

See also
FileTypeResolver

◆ audioProperties()

AudioProperties* TagLib::FileRef::audioProperties ( ) const

Returns the audio properties for this FileRef. If no audio properties were read then this will returns a null pointer.

◆ create()

static File* TagLib::FileRef::create ( FileName  fileName,
bool  readAudioProperties = true,
AudioProperties::ReadStyle  audioPropertiesStyle = AudioProperties::Average 
)
static

A simple implementation of file type guessing. If readAudioProperties is true then the audio properties will be read using audioPropertiesStyle. If readAudioProperties is false then audioPropertiesStyle will be ignored.

Note
You generally shouldn't use this method, but instead the constructor directly.
Deprecated:
Use FileRef(FileName, bool, AudioProperties::ReadStyle).

◆ defaultFileExtensions()

static StringList TagLib::FileRef::defaultFileExtensions ( )
static

As is mentioned elsewhere in this class's documentation, the default file type resolution code provided by TagLib only works by comparing file extensions.

This method returns the list of file extensions that are used by default.

The extensions are all returned in lowercase, though the comparison used by TagLib for resolution is case-insensitive.

Note
This does not account for any additional file type resolvers that are plugged in. Also note that this is not intended to replace a proper mime-type resolution system, but is just here for reference.
See also
FileTypeResolver

◆ file()

File* TagLib::FileRef::file ( ) const

Returns a pointer to the file represented by this handler class.

As a general rule this call should be avoided since if you need to work with file objects directly, you are probably better served instantiating the File subclasses (i.e. MPEG::File) manually and working with their APIs.

This handle exists to provide a minimal, generic and value-based wrapper around a File. Accessing the file directly generally indicates a moving away from this simplicity (and into things beyond the scope of FileRef).

Warning
This pointer will become invalid when this FileRef and all copies pass out of scope.

◆ isNull()

bool TagLib::FileRef::isNull ( ) const

Returns true if the file (and as such other pointers) are null.

◆ operator!=()

bool TagLib::FileRef::operator!= ( const FileRef &  ref) const

Returns true if this FileRef and ref do not point to the same File object.

◆ operator=()

FileRef& TagLib::FileRef::operator= ( const FileRef &  ref)

Assign the file pointed to by ref to this FileRef.

◆ operator==()

bool TagLib::FileRef::operator== ( const FileRef &  ref) const

Returns true if this FileRef and ref point to the same File object.

◆ save()

bool TagLib::FileRef::save ( )

Saves the file. Returns true on success.

◆ swap()

void TagLib::FileRef::swap ( FileRef &  ref)

Exchanges the content of the FileRef by the content of ref.

◆ tag()

Tag* TagLib::FileRef::tag ( ) const

Returns a pointer to represented file's tag.

Warning
This pointer will become invalid when this FileRef and all copies pass out of scope.
Do not cast it to any subclasses of Tag. Use tag returning methods of appropriate subclasses of File instead.
See also
File::tag()
The documentation for this class was generated from the following file: