metadb_handle Class Reference

#include <metadb_handle.h>

Inheritance diagram for metadb_handle:

service_base

List of all members.

Public Types

typedef metadb_handle t_interface
typedef service_base t_interface_parent

Public Member Functions

virtual const playable_location & get_location () const =0
 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).
virtual bool format_title (titleformat_hook *p_hook, pfc::string_base &p_out, const service_ptr_t< class titleformat_object > &p_script, titleformat_text_filter *p_filter)=0
virtual void metadb_lock ()=0
virtual void metadb_unlock ()=0
virtual t_filestats get_filestats () const =0
 Returns last seen file stats, filestats_invalid if unknown.
virtual bool is_info_loaded () const =0
virtual bool get_info (file_info &p_info) const =0
virtual bool get_info_locked (const file_info *&p_info) const =0
virtual bool is_info_loaded_async () const =0
virtual bool get_info_async (file_info &p_info) const =0
virtual bool get_info_async_locked (const file_info *&p_info) const =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< class titleformat_object > &p_script, titleformat_text_filter *p_filter)=0
 Renders information about item referenced by this metadb_handle object, using external file_info data.
virtual bool format_title_nonlocking (titleformat_hook *p_hook, pfc::string_base &p_out, const service_ptr_t< class titleformat_object > &p_script, titleformat_text_filter *p_filter)=0
virtual void format_title_from_external_info_nonlocking (const file_info &p_info, titleformat_hook *p_hook, pfc::string_base &p_out, const service_ptr_t< class titleformat_object > &p_script, titleformat_text_filter *p_filter)=0
bool should_reload (const t_filestats &p_new_stats, bool p_fresh) const
bool format_title_legacy (titleformat_hook *p_hook, pfc::string_base &out, const char *p_spec, titleformat_text_filter *p_filter)
const char * get_path () const
 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).
t_uint32 get_subsong_index () const
 Retrieves subsong index of item described by this metadb_handle instance (used for multiple playable tracks within single physical file).
double get_length ()
t_filetimestamp get_filetimestamp ()
t_filesize get_filesize ()

Static Public Member Functions

static bool g_should_reload (const t_filestats &p_old_stats, const t_filestats &p_new_stats, bool p_fresh)

Static Public Attributes

static const GUID class_guid

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.

Member Typedef Documentation

typedef metadb_handle metadb_handle::t_interface

Reimplemented from service_base.

typedef service_base metadb_handle::t_interface_parent

Member Function Documentation

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

virtual bool metadb_handle::format_title ( titleformat_hook *  p_hook,
pfc::string_base &  p_out,
const service_ptr_t< class 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::metadb_lock (  )  [pure virtual]

Locks metadb to prevent other threads from modifying it while you're working with some of its contents. Some functions (metadb_handle::get_info_locked(), metadb_handle::get_info_async_locked()) can be called only from inside metadb lock section. Same as metadb::database_lock().

virtual void metadb_handle::metadb_unlock (  )  [pure virtual]

Unlocks metadb after metadb_lock(). Some functions (metadb_handle::get_info_locked(), metadb_handle::get_info_async_locked()) can be called only from inside metadb lock section. Same as metadb::database_unlock().

virtual t_filestats metadb_handle::get_filestats (  )  const [pure virtual]

Returns last seen file stats, filestats_invalid if unknown.

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 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 ( 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 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_locked ( const 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. This is more efficient than get_info() since no data is copied.
You must lock the metadb before calling this function, and unlock it after you are done working with the returned pointer, to ensure multithread safety.
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.

Parameters:
p_info On success, receives a pointer to metadb's file_info object. The pointer is for temporary use only, and becomes invalid when metadb is unlocked.

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.

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.
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_async_locked ( const 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. This is more efficient than get_info() since no data is copied.
You must lock the metadb before calling this function, and unlock it after you are done working with the returned pointer, to ensure multithread safety.
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.

Parameters:
p_info On success, receives a pointer to metadb's file_info object. The pointer is for temporary use only, and becomes invalid when metadb is unlocked.

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

virtual bool metadb_handle::format_title_nonlocking ( titleformat_hook *  p_hook,
pfc::string_base &  p_out,
const service_ptr_t< class titleformat_object > &  p_script,
titleformat_text_filter *  p_filter 
) [pure virtual]

Since:
0.9.5

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

Since:
0.9.5

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

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

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.

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

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

double metadb_handle::get_length (  ) 

t_filetimestamp metadb_handle::get_filetimestamp (  ) 

t_filesize metadb_handle::get_filesize (  ) 

Member Data Documentation

const GUID metadb_handle::class_guid [static]

Initial value:

{ 0x160885c6, 0x3aa3, 0x4f60, { 0x87, 0x18, 0x12, 0x40, 0x61, 0x5e, 0x64, 0x14 } }

The documentation for this class was generated from the following files:
Generated on Fri Apr 25 18:49:46 2008 for foobar2000 SDK by  doxygen 1.5.5