metadb_display_field_provider Class Reference

#include <metadb.h>

Inheritance diagram for metadb_display_field_provider:
service_base

List of all members.

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


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:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines

Generated by  doxygen 1.6.2