Audio::Codec Class Reference

#include <Codec.h>

Inheritance diagram for Audio::Codec:

Public Types
typedef std::vector< std::string >	Extensions

Public Member Functions
virtual	~Codec ()
const std::string &	getName () const throw ()
virtual const Extensions *	getExtensions () const throw ()
virtual bool	canHandle (const std::string &path, bool canOpen, VSFileSystem::VSFileType type=VSFileSystem::UnknownFile)=0 throw ()
virtual Stream *	open (const std::string &path, VSFileSystem::VSFileType type=VSFileSystem::UnknownFile)=0 throw (Exception)

Protected Member Functions
	Codec (const std::string &name) throw ()

Detailed Description

Codec factory class.

Remarks

Use it to create Stream instances attached to a file.

See Also

CodecRegistry to create Codec instances.

Definition at line 27 of file Codec.h.

Member Typedef Documentation

typedef std::vector<std::string> Audio::Codec::Extensions

Back-appendable collection of std::string, optimally for static readonly data

Definition at line 38 of file Codec.h.

Constructor & Destructor Documentation

Audio::Codec::Codec ( const std::string &  name) throw ( )

protected

Internal constructor

Definition at line 14 of file Codec.cpp.

                                               : name(_name)
    {
    }

Audio::Codec::~Codec ( )

virtual

Definition at line 10 of file Codec.cpp.

    {
    }

Member Function Documentation

virtual bool Audio::Codec::canHandle ( const std::string &  path, bool  canOpen, VSFileSystem::VSFileType  type = VSFileSystem::UnknownFile  ) throw ( )

pure virtual

Returns whether this codec instanc can handle the specified file.

Parameters

path	the file to be tested
canOpen	whether opening the file to take a peek is allowed. If not, the implementation should rely on the filename alone to do its task (ie: look for an extension). See the remarks for more details.

Remarks

This member will return true when it thinks the codec can decode the specified file, and false otherwise. No certainty is required. However, an assumption is made that codec implementations will make a reasonable effort to guess the outcome of an "open" call, given the allowed operations. If canOpen is true, the implementation can open the file to inspect its format and accurately decide that. The operation is still expected to be rather quick. If canOpen is false, the operation is expected to be even quicker and the implementation may not open the file. Rather, filename patterns (or any other method that doesn't open the file) are the only viable methods of implementation, and thus it is expected that the returned value will be less accurate. Whenever in doubt, the function will return success (true).

Implemented in Audio::OggCodec, and Audio::FFCodec.

const std::vector< std::string > * Audio::Codec::getExtensions ( ) const throw ( )

virtual

Return a list of supported extensions.

Remarks

If it returns something, it is expected that files handled by this codec be named by appending one of the returned extensions as a suffix.

Though supported extensions are a big help to the codec registry

when asked to suggest codecs for a file, a null value can be returned asking the registry to always try this codec. This is useful if the codec can handle many (perhaps unknown) file types, or if there is no associated extension to the type handled.

The base implementation does just that - returns null.

It is expected that files named with returned extensions will pass the

tests for canHandle(path,false). Though this may not always be true. So the final test canHandle(path,true) should never be skipped, even if the file includes an extension within the returned set.

Reimplemented in Audio::OggCodec.

Definition at line 23 of file Codec.cpp.

    {
        return 0;
    }

const std::string & Audio::Codec::getName	(	)		const
throw	(
	)

Return the descriptive name of the codec.

Definition at line 18 of file Codec.cpp.

    {
        return name;
    }

virtual Stream* Audio::Codec::open ( const std::string &  path, VSFileSystem::VSFileType  type = VSFileSystem::UnknownFile  ) throw ( Exception )

pure virtual

Returns an instance of the Stream class attached to this codec and the specified file.

Parameters

path	the file to be attached to the returned object.
type	(optional) the type of file, used by resource management APIs.

Remarks

Don't even bother to call it if canHandle returns false. However, if it returns true, this can still fail. Be prepared to catch exceptions and deal with them accordingly.

Implemented in Audio::OggCodec, and Audio::FFCodec.

Referenced by Audio::CodecRegistry::open().

---

The documentation for this class was generated from the following files:

• src/audio/codecs/Codec.h
• src/audio/codecs/Codec.cpp