NAME

Audio::TagLib::FileRef - This class provides a simple abstraction for creating and handling files

SYNOPSIS

  use Audio::TagLib::FileRef;
  
  my $i = Audio::TagLib::FileRef->new("sample file.mp3");
  $i->tag()->setTitle(Audio::TagLib::String->new("sample title"));
  print $i->tag()->toCString(), "\n"; # got "sample title"

DESCRIPTION

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 Audio::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 FileTypeResolver

see addFileTypeResolver()

new()

Creates a null FileRef.

new(PV $fileName, BOOL $readAudioProperties = TRUE PV $audioPropertiesStyle = "Average")

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.

new(PV $file)

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

new(FileRef $ref)

Make a copy of $ref.

DESTROY()

Destroys this FileRef instance.

Tag tag()

Returns the file's tag.

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

see File::tag()

AudioProperties audioProperties()

Returns the audio properties for this FileRef. If no audio properties were read then this will return undef.

File file()

Returns 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.

BOOL save()

Saves the file. Returns true on success.

FileTypeResolver addFileTypeResolver(FileTypeResolver $resolver) [static]

Adds a FileTypeResolver to the list of those used by Audio::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 the added resolver (the same one that's passed in -- this is mostly so that static inialializers have something to use for assignment).

see FileTypeResolver

StringList defaultFileExtensions() [static]

As is mentioned elsewhere in this class's documentation, the default file type resolution code provided by Audio::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 Audio::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 propper mime-type resolution system, but is just here for reference.

see FileTypeResolver

BOOL isNull()

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

File create(PV $fileName, BOOL $readAudioProperties = TRUE, PV $audioPropertiesStyle = "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.

OVERLOADED OPERATORS

== !=

EXPORT

None by default.

SEE ALSO

Audio::TagLib

AUTHOR

Dongxu Ma, <dongxu@cpan.org>

MAINTAINER

Geoffrey Leach GLEACH@cpan.org

COPYRIGHT AND LICENSE

Copyright (C) 2005-2010 by Dongxu Ma

Copyright (C) 2011 - 2012 Geoffrey Leach

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.