foobar2000 SDK  2015-08-03
Public Member Functions | Static Public Member Functions | Data Fields
metadb_handleabstract

#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_locationget_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_filterp_filter = 0
 
titleformat_hook pfc::string_base const service_ptr_t< titleformat_object > titleformat_text_filterp_filter = 0
 
titleformat_hookp_hook
 
pfc::string_basep_out
 
titleformat_hook pfc::string_basep_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_hookOptional callback object overriding fields and functions; set to NULL if not used.
p_outString receiving the output on success.
p_scriptTitleformat script to use. Use titleformat_compiler service to create one.
p_filterOptional 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.

20 {
22  if (static_api_ptr_t<titleformat_compiler>()->compile(script,p_spec)) {
23  return format_title(p_hook,p_out,script,p_filter);
24  } else {
25  p_out.reset();
26  return false;
27  }
28 }
pfc::string_base & p_out
Definition: metadb_handle.h:66
This is free and unencumbered software released into the public domain Anyone is free to compile
Definition: pfc-license.txt:3
Helper template used to easily access core services. Usage: static_api_ptr_t<myclass> api; api->doso...
Definition: service.h:533
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
Renders information about item referenced by this metadb_handle object.
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.

33 {
34  if (p_new_stats.m_timestamp == filetimestamp_invalid) return p_fresh;
35  else if (p_fresh) return p_old_stats!= p_new_stats;
36  else return p_old_stats.m_timestamp < p_new_stats.m_timestamp;
37 }
const t_filetimestamp filetimestamp_invalid
Invalid/unknown file timestamp constant. Also see: t_filetimestamp.
Definition: filesystem.h:14
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.

46  {
47  bool rv = true;
48  metadb_info_container::ptr info, browse;
49  this->get_browse_info_ref(info, browse);
50  if (info.is_valid() && browse.is_valid()) {
51  infoMerged = info->info();
52  infoMerged.merge_fallback( browse->info() );
53  } else if (info.is_valid()) {
54  infoMerged = info->info();
55  } else if (browse.is_valid()) {
56  infoMerged = browse->info();
57  } else {
58  infoMerged.reset();
59  rv = false;
60  }
61  return rv;
62 }
virtual void get_browse_info_ref(metadb_info_container::ptr &outInfo, metadb_info_container::ptr &outBrowse) const =0
void info(const char *p_message)
Definition: console.cpp:4
void merge_fallback(const file_info &fallback)
void reset()
Definition: file_info.cpp:287
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.

15 {
16  return get_filestats().m_size;
17 }
virtual t_filestats get_filestats() const =0
Returns last seen file stats, filestats_invalid if unknown.
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.

10 {
11  return get_filestats().m_timestamp;
12 }
virtual t_filestats get_filestats() const =0
Returns last seen file stats, filestats_invalid if unknown.
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.

85  {
86  {
87  metadb_info_container::ptr info;
88  if (this->get_info_ref( info ) ) {
89  if (!info->isInfoPartial()) return info;
90  }
91  }
92 
93 
94  input_info_reader::ptr reader;
95  input_entry::g_open_for_info_read( reader, NULL, this->get_path(), aborter );
96 
98  obj->m_stats = reader->get_file_stats( aborter );
99  reader->get_info( this->get_subsong_index(), obj->m_info, aborter );
100  return obj;
101 }
Template implementing reference-counting features of service_base. Intended for dynamic instantiation...
Definition: service_impl.h:4
void info(const char *p_message)
Definition: console.cpp:4
const char * get_path() const
Retrieves path of item described by this metadb_handle instance. Returned string is valid until calli...
static void g_open_for_info_read(service_ptr_t< input_info_reader > &p_instance, service_ptr_t< file > p_filehint, const char *p_path, abort_callback &p_abort, bool p_from_redirect=false)
Definition: input.cpp:175
Autopointer class to be used with all services. Manages reference counter calls behind-the-scenes.
Definition: service.h:55
virtual metadb_info_container::ptr get_info_ref() const =0
Simplified method, always returns non-null, dummy info if nothing to return.
t_uint32 get_subsong_index() const
Retrieves subsong index of item described by this metadb_handle instance (used for multiple playable ...
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.

5 {
6  return this->get_info_ref()->info().get_length();
7 }
virtual metadb_info_container::ptr get_info_ref() const =0
Simplified method, always returns non-null, dummy info if nothing to return.
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.

125 {return get_location().get_path();}
virtual const char * get_path() const =0
virtual const playable_location & get_location() const =0
Retrieves location represented by this metadb_handle object. Returned reference is valid until callin...
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.

127 {return get_location().get_subsong_index();}
virtual const playable_location & get_location() const =0
Retrieves location represented by this metadb_handle object. Returned reference is valid until callin...
t_uint32 get_subsong_index() const
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.

40 {
41  if (!is_info_loaded_async()) return true;
42  else return g_should_reload(get_filestats(),p_new_stats,p_fresh);
43 }
virtual t_filestats get_filestats() const =0
Returns last seen file stats, filestats_invalid if unknown.
static bool g_should_reload(const t_filestats &p_old_stats, const t_filestats &p_new_stats, bool p_fresh)
virtual bool is_info_loaded_async() const =0
Queries whether cached info about item referenced by this metadb_handle object is already available...

Field Documentation

t_filetimestamp& ts metadb_handle::const = 0

Definition at line 75 of file metadb_handle.h.

Definition at line 66 of file metadb_handle.h.

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.

Definition at line 66 of file metadb_handle.h.

Definition at line 68 of file metadb_handle.h.


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