metadb_handle

#include <metadb_handle.h>

Inheritance diagram for metadb_handle:

Public Member Functions
	__declspec (deprecated) virtual void metadb_lock()=0
	__declspec (deprecated) virtual void metadb_unlock()=0
	__declspec (deprecated) virtual bool get_info_locked(const file_info *&p_info) const =0
	__declspec (deprecated) virtual bool get_info_async_locked(const file_info *&p_info) const =0
	__declspec (deprecated) virtual bool format_title_nonlocking(titleformat_hook *p_hook
	__declspec (deprecated) virtual void format_title_from_external_info_nonlocking(const file_info &p_info
	__declspec (deprecated) virtual bool get_browse_info_locked(const file_info *&p_info
	FB2K_MAKE_SERVICE_INTERFACE (metadb_handle, service_base)
virtual bool	format_title (titleformat_hook *p_hook, pfc::string_base &p_out, const service_ptr_t< titleformat_object > &p_script, titleformat_text_filter *p_filter)=0
virtual void	format_title_from_external_info (const file_info &p_info, titleformat_hook *p_hook, pfc::string_base &p_out, const service_ptr_t< titleformat_object > &p_script, titleformat_text_filter *p_filter)=0
bool	format_title_legacy (titleformat_hook *p_hook, pfc::string_base &out, const char *p_spec, titleformat_text_filter *p_filter)
virtual bool	get_async_info_ref (metadb_info_container::ptr &outInfo) const =0
virtual metadb_info_container::ptr	get_async_info_ref () const =0
virtual bool	get_browse_info (file_info &info, t_filetimestamp &ts) const =0
bool	get_browse_info_merged (file_info &infoMerged) const
virtual void	get_browse_info_ref (metadb_info_container::ptr &outInfo, metadb_info_container::ptr &outBrowse) const =0
t_filesize	get_filesize ()
virtual t_filestats	get_filestats () const =0
t_filetimestamp	get_filetimestamp ()
metadb_info_container::ptr	get_full_info_ref (abort_callback &aborter) const
virtual bool	get_info (file_info &p_info) const =0
virtual bool	get_info_async (file_info &p_info) const =0
virtual bool	get_info_ref (metadb_info_container::ptr &outInfo) const =0
virtual metadb_info_container::ptr	get_info_ref () const =0
double	get_length ()
virtual const playable_location &	get_location () const =0
const char *	get_path () const
t_uint32	get_subsong_index () const
virtual bool	is_info_loaded () const =0
virtual bool	is_info_loaded_async () const =0
bool	should_reload (const t_filestats &p_new_stats, bool p_fresh) const
Public Member Functions inherited from service_base
template<typename outPtr_t >
bool	cast (outPtr_t &outPtr)
virtual int	service_add_ref ()=0 throw ()
virtual bool	service_query (service_ptr_t< service_base > &p_out, const GUID &p_guid)
template<class T >
bool	service_query_t (service_ptr_t< T > &p_out)
virtual int	service_release ()=0 throw ()

Static Public Member Functions
static bool	g_should_reload (const t_filestats &p_old_stats, const t_filestats &p_new_stats, bool p_fresh)

Data Fields
t_filetimestamp &ts	const = 0
pfc::string_base const service_ptr_t< titleformat_object > titleformat_text_filter *	p_filter = 0
titleformat_hook pfc::string_base const service_ptr_t< titleformat_object > titleformat_text_filter *	p_filter = 0
titleformat_hook *	p_hook
pfc::string_base &	p_out
titleformat_hook pfc::string_base &	p_out
pfc::string_base const service_ptr_t< titleformat_object > &	p_script
titleformat_hook pfc::string_base const service_ptr_t< titleformat_object > &	p_script

Additional Inherited Members
Public Types inherited from service_base
typedef service_base	t_interface
Protected Member Functions inherited from service_base
	service_base ()
	~service_base ()

Detailed Description

A metadb_handle object represents interface to reference-counted file_info cache entry for the specified location.
To obtain a metadb_handle to specific location, use metadb::handle_create(). To obtain a list of metadb_handle objects corresponding to specific path (directory, playlist, multitrack file, etc), use relevant playlist_incoming_item_filter methods (recommended), or call playlist_loader methods directly.
A metadb_handle is also the most efficient way of passing playable object locations around because it provides fast access to both location and infos, and is reference counted so duplicating it is as fast as possible.
To retrieve a path of a file from a metadb_handle, use metadb_handle::get_path() function. Note that metadb_handle is NOT just file path, some formats support multiple subsongs per physical file, which are signaled using subsong indexes.

Definition at line 19 of file metadb_handle.h.

Member Function Documentation

metadb_handle::__declspec ( deprecated  )

pure virtual

OBSOLETE, DO NOT CALL.

metadb_handle::__declspec ( deprecated  )

pure virtual

OBSOLETE, DO NOT CALL.

metadb_handle::__declspec ( deprecated  ) const

pure virtual

OBSOLETE, DO NOT CALL.

metadb_handle::__declspec ( deprecated  ) const

pure virtual

OBSOLETE, DO NOT CALL.

metadb_handle::__declspec

(

deprecated

)

OBSOLETE, DO NOT CALL.

metadb_handle::__declspec

(

deprecated

)

const

OBSOLETE, DO NOT CALL.

metadb_handle::__declspec

(

deprecated

)

const

OBSOLETE, DO NOT CALL.

metadb_handle::FB2K_MAKE_SERVICE_INTERFACE	(	metadb_handle	,
		service_base
	)

virtual bool metadb_handle::format_title ( titleformat_hook *  p_hook, pfc::string_base &  p_out, const service_ptr_t< titleformat_object > &  p_script, titleformat_text_filter *  p_filter  )

pure virtual

Renders information about item referenced by this metadb_handle object.

Parameters

p_hook	Optional callback object overriding fields and functions; set to NULL if not used.
p_out	String receiving the output on success.
p_script	Titleformat script to use. Use titleformat_compiler service to create one.
p_filter	Optional callback object allowing input to be filtered according to context (i.e. removal of linebreak characters present in tags when rendering playlist lines). Set to NULL when not used.

Returns

true on success, false when dummy file_info instance was used because actual info is was not (yet) known.

virtual void metadb_handle::format_title_from_external_info ( const file_info &  p_info, titleformat_hook *  p_hook, pfc::string_base &  p_out, const service_ptr_t< titleformat_object > &  p_script, titleformat_text_filter *  p_filter  )

pure virtual

Renders information about item referenced by this metadb_handle object, using external file_info data.

bool metadb_handle::format_title_legacy	(	titleformat_hook *	p_hook,
		pfc::string_base &	out,
		const char *	p_spec,
		titleformat_text_filter *	p_filter
	)

Helper provided for backwards compatibility; takes formatting script as text string and calls relevant titleformat_compiler methods; returns false when the script could not be compiled.
See format_title() for descriptions of parameters.
Bottleneck warning: you should consider using precompiled titleformat script object and calling regular format_title() instead when processing large numbers of items.

Definition at line 19 of file metadb_handle.cpp.

{
    service_ptr_t<titleformat_object> script;
    if (static_api_ptr_t<titleformat_compiler>()->compile(script,p_spec)) {
        return format_title(p_hook,p_out,script,p_filter);
    } else {
        p_out.reset();
        return false;
    }
}

bool metadb_handle::g_should_reload ( const t_filestats &  p_old_stats, const t_filestats &  p_new_stats, bool  p_fresh  )

static

Definition at line 32 of file metadb_handle.cpp.

{
    if (p_new_stats.m_timestamp == filetimestamp_invalid) return p_fresh;
    else if (p_fresh) return p_old_stats!= p_new_stats;
    else return p_old_stats.m_timestamp < p_new_stats.m_timestamp;
}

virtual bool metadb_handle::get_async_info_ref ( metadb_info_container::ptr &  outInfo ) const

pure virtual

Since

1.3 Retrieve a reference to the async info (pending info update). If async info isn't set, a reference to the primary info is returned.
You can hold the reference to the info as long as you like, call the method in any context you like with no lock semantics involved. The info held by the returned reference will remain constant even if the metadb content changes. Returns true and sets outInfo to a reference to this item's async or primary info on success, returns false on failure (no info known at this time).

virtual metadb_info_container::ptr metadb_handle::get_async_info_ref ( ) const

pure virtual

Simplified method, always returns non-null, dummy info if nothing to return.

virtual bool metadb_handle::get_browse_info ( file_info &  info, t_filetimestamp &  ts  ) const

pure virtual

New in 1.0.

bool metadb_handle::get_browse_info_merged

(

file_info &

infoMerged

)

const

Since

1.3 Helper using get_browse_info_ref() Retrieves primary info + browse info merged together. Returns true on success, false if neither info is available. If neither info is avaialble, output data structure is emptied.

Definition at line 46 of file metadb_handle.cpp.

                                                                       {
    bool rv = true;
    metadb_info_container::ptr info, browse;
    this->get_browse_info_ref(info, browse);
    if (info.is_valid() && browse.is_valid()) {
        infoMerged = info->info();
        infoMerged.merge_fallback( browse->info() );
    } else if (info.is_valid()) {
        infoMerged = info->info();
    } else if (browse.is_valid()) {
        infoMerged = browse->info();
    } else {
        infoMerged.reset();
        rv = false;
    }
    return rv;
}

virtual void metadb_handle::get_browse_info_ref ( metadb_info_container::ptr &  outInfo, metadb_info_container::ptr &  outBrowse  ) const

pure virtual

Since

1.3 Retrieve references to the item's primary and browse infos. If no info is set, NULL pointers are returned. For most local files, browse info is not available and you get a NULL for it.
Since browse info is usually used along with the primary info (as a fallback for missing metas), you can get the two with one call for better performance. You can hold the reference to the info as long as you like, call the method in any context you like with no lock semantics involved. The info held by the returned reference will remain constant even if the metadb content changes.

t_filesize metadb_handle::get_filesize

(

)

Definition at line 14 of file metadb_handle.cpp.

{
    return get_filestats().m_size;
}

virtual t_filestats metadb_handle::get_filestats ( ) const

pure virtual

Returns last seen file stats, filestats_invalid if unknown.

t_filetimestamp metadb_handle::get_filetimestamp

(

)

Definition at line 9 of file metadb_handle.cpp.

{
    return get_filestats().m_timestamp;
}

metadb_info_container::ptr metadb_handle::get_full_info_ref

(

abort_callback &

aborter

)

const

Since

1.3 Retrieve full info using available means - read actual file if not cached.
Throws exceptions on failure.

Definition at line 85 of file metadb_handle.cpp.

                                                                                          {
    {
        metadb_info_container::ptr info;
        if (this->get_info_ref( info ) ) {
            if (!info->isInfoPartial()) return info;
        }
    }


    input_info_reader::ptr reader;
    input_entry::g_open_for_info_read( reader, NULL, this->get_path(), aborter );
    
    service_ptr_t< metadb_info_container_impl > obj = new service_impl_t<metadb_info_container_impl>();
    obj->m_stats = reader->get_file_stats( aborter );
    reader->get_info( this->get_subsong_index(), obj->m_info, aborter );
    return obj;
}

virtual bool metadb_handle::get_info ( file_info &  p_info ) const

pure virtual

Queries cached info about item referenced by this metadb_handle object. Returns true on success, false when info is not yet known. Note that this function causes the metadb to be temporarily locked; you can not use it in context that where locking is forbidden.
Note that state of cached info changes only inside main thread, so you can safely assume that it doesn't change while some block of your code inside main thread is being executed.

virtual bool metadb_handle::get_info_async ( file_info &  p_info ) const

pure virtual

Queries cached info about item referenced by this metadb_handle object. Returns true on success, false when info is not yet known. Note that this function causes the metadb to be temporarily locked; you can not use it in context that where locking is forbidden.
This is intended for use in special cases when you need to immediately retrieve info sent by metadb_io hint from another thread; state of returned data can be altered by any thread, as opposed to non-async methods.

virtual bool metadb_handle::get_info_ref ( metadb_info_container::ptr &  outInfo ) const

pure virtual

Since

1.3 Retrieve a reference to the primary info.
You can hold the reference to the info as long as you like, call the method in any context you like with no lock semantics involved. The info held by the returned reference will remain constant even if the metadb content changes. Returns true and sets outInfo to a reference to this item's primary info on success, returns false on failure (no info known at this time).

virtual metadb_info_container::ptr metadb_handle::get_info_ref ( ) const

pure virtual

Simplified method, always returns non-null, dummy info if nothing to return.

double metadb_handle::get_length

(

)

Definition at line 4 of file metadb_handle.cpp.

{
    return this->get_info_ref()->info().get_length();
}

virtual const playable_location& metadb_handle::get_location ( ) const

pure virtual

Retrieves location represented by this metadb_handle object. Returned reference is valid until calling context releases metadb_handle that returned it (metadb_handle_ptr is deallocated etc).

const char* metadb_handle::get_path ( ) const

inline

Retrieves path of item described by this metadb_handle instance. Returned string is valid until calling context releases metadb_handle that returned it (metadb_handle_ptr is deallocated etc).

Definition at line 125 of file metadb_handle.h.

{return get_location().get_path();}

t_uint32 metadb_handle::get_subsong_index ( ) const

inline

Retrieves subsong index of item described by this metadb_handle instance (used for multiple playable tracks within single physical file).

Definition at line 127 of file metadb_handle.h.

{return get_location().get_subsong_index();}

virtual bool metadb_handle::is_info_loaded ( ) const

pure virtual

Queries whether cached info about item referenced by this metadb_handle object is already available. Note that this function causes the metadb to be temporarily locked; you can not use it in context that where locking is forbidden.
Note that state of cached info changes only inside main thread, so you can safely assume that it doesn't change while some block of your code inside main thread is being executed.

virtual bool metadb_handle::is_info_loaded_async ( ) const

pure virtual

Queries whether cached info about item referenced by this metadb_handle object is already available.
This is intended for use in special cases when you need to immediately retrieve info sent by metadb_io hint from another thread; state of returned data can be altered by any thread, as opposed to non-async methods.

bool metadb_handle::should_reload	(	const t_filestats &	p_new_stats,
		bool	p_fresh
	)		const

Definition at line 39 of file metadb_handle.cpp.

{
    if (!is_info_loaded_async()) return true;
    else return g_should_reload(get_filestats(),p_new_stats,p_fresh);
}

Field Documentation

t_filetimestamp& ts metadb_handle::const = 0

Definition at line 75 of file metadb_handle.h.

pfc::string_base const service_ptr_t<titleformat_object> titleformat_text_filter* metadb_handle::p_filter = 0

Definition at line 66 of file metadb_handle.h.

titleformat_hook pfc::string_base const service_ptr_t<titleformat_object> titleformat_text_filter* metadb_handle::p_filter = 0

Definition at line 68 of file metadb_handle.h.

titleformat_hook* metadb_handle::p_hook

Definition at line 68 of file metadb_handle.h.

pfc::string_base& metadb_handle::p_out

Definition at line 66 of file metadb_handle.h.

titleformat_hook pfc::string_base& metadb_handle::p_out

Definition at line 68 of file metadb_handle.h.

pfc::string_base const service_ptr_t<titleformat_object>& metadb_handle::p_script

Definition at line 66 of file metadb_handle.h.

titleformat_hook pfc::string_base const service_ptr_t<titleformat_object>& metadb_handle::p_script

Definition at line 68 of file metadb_handle.h.

---

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

• foobar2000/SDK/metadb_handle.h
• foobar2000/SDK/metadb_handle.cpp