foobar2000 SDK  2015-08-03
Public Member Functions
metadb_display_field_providerabstract

#include <metadb.h>

+ Inheritance diagram for metadb_display_field_provider:

Public Member Functions

 FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT (metadb_display_field_provider)
 
virtual t_uint32 get_field_count ()=0
 
virtual void get_field_name (t_uint32 index, pfc::string_base &out)=0
 
virtual bool process_field (t_uint32 index, metadb_handle *handle, titleformat_text_out *out)=0
 
- 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 ()
 

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

Implementing this service lets you provide your own title-formatting fields that are parsed globally with each call to metadb_handle::format_title methods.
Note that this API is meant to allow you to add your own component-specific fields - not to overlay your data over standard fields or over fields provided by other components. Any attempts to interfere with standard fields will have severe ill effects.
This should be implemented only where absolutely necessary, for safety and performance reasons. Any expensive operations inside the process_field() method may severely damage performance of affected title-formatting calls.
You must NEVER make any other foobar2000 API calls from inside process_field, other than possibly querying information from the passed metadb_handle pointer; you should read your own implementation-specific private data and return as soon as possible. You must not make any assumptions about calling context (threading etc).
It is guaranteed that process_field() is called only inside a metadb lock scope so you can safely call "locked" metadb_handle methods on the metadb_handle pointer you get. You must not lock metadb by yourself inside process_field() - while it is always called from inside a metadb lock scope, it may be called from another thread than the one maintaining the lock because of multi-CPU optimizations active.
If there are multiple metadb_display_field_provider services registered providing fields of the same name, the behavior is undefined. You must pick unique names for provided fields to ensure safe coexistence with other people's components.
IMPORTANT: Any components implementing metadb_display_field_provider MUST call metadb_io::dispatch_refresh() with affected metadb_handles whenever info that they present changes. Otherwise, anything rendering title-formatting strings that reference your data will not update properly, resulting in unreliable/broken output, repaint glitches, etc.
Do not expect a process_field() call each time somebody uses title formatting, calling code might perform its own caching of strings that you return, getting new ones only after metadb_io::dispatch_refresh() with relevant items.
If you can't reliably notify other components about changes of content of fields that you provide (such as when your fields provide some kind of global information and not information specific to item identified by passed metadb_handle), you should not be providing those fields in first place. You must not change returned values of your fields without dispatching appropriate notifications.
Use static service_factory_single_t<myclass> to register your metadb_display_field_provider implementations. Do not call other people's metadb_display_field_provider services directly, they're meant to be called by backend only.
List of fields that you provide is expected to be fixed at run-time. The backend will enumerate your fields only once and refer to them by indexes later.

Definition at line 272 of file metadb.h.

Member Function Documentation

metadb_display_field_provider::FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT ( metadb_display_field_provider  )
virtual t_uint32 metadb_display_field_provider::get_field_count ( )
pure virtual

Returns number of fields provided by this metadb_display_field_provider implementation.

virtual void metadb_display_field_provider::get_field_name ( t_uint32  index,
pfc::string_base out 
)
pure virtual

Returns name of specified field provided by this metadb_display_field_provider implementation. Names are not case sensitive. It's strongly recommended that you keep your field names plain English / ASCII only.

virtual bool metadb_display_field_provider::process_field ( t_uint32  index,
metadb_handle handle,
titleformat_text_out out 
)
pure virtual

Evaluates the specified field.

Parameters
indexIndex of field being processed : 0 <= index < get_field_count().
handleHandle to item being processed. You can safely call "locked" methods on this handle to retrieve track information and such.
outInterface receiving your text output.
Returns
Return true to indicate that the field is present so if it's enclosed in square brackets, contents of those brackets should not be skipped, false otherwise.

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