metadb_display_field_provider Class Reference
#include <metadb.h>
Inheritance diagram for metadb_display_field_provider:
Public Types | |
| typedef metadb_display_field_provider | t_interface_entrypoint |
| typedef metadb_display_field_provider | t_interface |
| typedef service_base | t_interface_parent |
Public Member Functions | |
| virtual t_uint32 | get_field_count ()=0 |
| Returns number of fields provided by this metadb_display_field_provider implementation. | |
| virtual void | get_field_name (t_uint32 index, pfc::string_base &out)=0 |
| 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 | process_field (t_uint32 index, metadb_handle *handle, titleformat_text_out *out)=0 |
Static Public Attributes | |
| static const GUID | class_guid = { 0x5923fa2a, 0x504b, 0x4022, { 0xb2, 0x86, 0x0, 0x22, 0x75, 0x38, 0x45, 0x5e } } |
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.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, which one gets called is undefined.
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.
Member Typedef Documentation
Reimplemented from service_base.
Member Function Documentation
| 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:
-
index Index of field being processed : 0 <= index < get_field_count(). handle Handle to item being processed. You can safely call "locked" methods on this handle to retrieve track information and such. out Interface 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.
Member Data Documentation
const GUID metadb_display_field_provider::class_guid = { 0x5923fa2a, 0x504b, 0x4022, { 0xb2, 0x86, 0x0, 0x22, 0x75, 0x38, 0x45, 0x5e } } [static] |
The documentation for this class was generated from the following files:
