mchapman/foobar2000-sdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

latest SDK

Browse Source
This commit is contained in:
Mikah Chapman
2021-12-14 00:28:25 -07:00
commit 68b10d413b
492 changed files with 80542 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

724
sdk-readme.html Normal file
View File

@@ -0,0 +1,724 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
lang="en" dir="ltr">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>foobar2000 SDK Readme</title>
<link rel="stylesheet" type="text/css" href="sdk-readme.css" />
</head>
<body>
<div class="dokuwiki export">
<div class="toc">
<div class="tocheader toctoggle" id="toc__header">Table of Contents</div>
<div id="toc__inside">
<ul class="toc">
<li class="level1"><div class="li"><span class="li"><a href="#foobar2000_v1.6_sdk_readme" class="toc">foobar2000 v1.6 SDK readme</a></span></div>
<ul class="toc">
<li class="level2"><div class="li"><span class="li"><a href="#compatibility" class="toc">Compatibility</a></span></div></li>
<li class="level2"><div class="li"><span class="li"><a href="#microsoft_visual_studio_compatibility" class="toc">Microsoft Visual Studio compatibility</a></span></div>
<ul class="toc">
<li class="level3"><div class="li"><span class="li"><a href="#ill_behavior_of_visual_c_whole_program_optimization" class="toc">Ill behavior of Visual C whole program optimization</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#virtual_memory_range_for_pch_exceeded_error" class="toc">&quot;virtual memory range for PCH exceeded&quot; error</a></span></div></li>
</ul>
</li>
<li class="level2"><div class="li"><span class="li"><a href="#version_1.6_notes" class="toc">Version 1.6 notes</a></span></div>
<ul class="toc">
<li class="level3"><div class="li"><span class="li"><a href="#windows_xp_support" class="toc">Windows XP support</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#audio_output_api_extensions" class="toc">Audio output API extensions</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#webp_support_imageloaderlite" class="toc">WebP support, imageLoaderLite</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#file_cache_utilities" class="toc">File cache utilities</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#cuesheet_wrapper_fixes" class="toc">Cuesheet wrapper fixes</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#libppui" class="toc">libPPUI</a></span></div></li>
</ul>
</li>
<li class="level2"><div class="li"><span class="li"><a href="#version_1.5_notes" class="toc">Version 1.5 notes</a></span></div>
<ul class="toc">
<li class="level3"><div class="li"><span class="li"><a href="#libppui1" class="toc">libPPUI</a></span></div></li>
</ul>
</li>
<li class="level2"><div class="li"><span class="li"><a href="#version_1.4_notes" class="toc">Version 1.4 notes</a></span></div>
<ul class="toc">
<li class="level3"><div class="li"><span class="li"><a href="#namespace_cleanup" class="toc">Namespace cleanup</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#decoders" class="toc">Decoders</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#dynamic_runtime" class="toc">Dynamic runtime</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#service_query" class="toc">service_query()</a></span></div></li>
</ul>
</li>
<li class="level2"><div class="li"><span class="li"><a href="#version_1.3_notes" class="toc">Version 1.3 notes</a></span></div></li>
<li class="level2"><div class="li"><span class="li"><a href="#basic_usage" class="toc">Basic usage</a></span></div></li>
<li class="level2"><div class="li"><span class="li"><a href="#structure_of_a_component" class="toc">Structure of a component</a></span></div>
<ul class="toc">
<li class="level3"><div class="li"><span class="li"><a href="#services" class="toc">Services</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#entrypoint_services" class="toc">Entrypoint services</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#service_extensions" class="toc">Service extensions</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#autopointer_template_use" class="toc">Autopointer template use</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#exception_use" class="toc">Exception use</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#storing_configuration" class="toc">Storing configuration</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#use_of_global_callback_services" class="toc">Use of global callback services</a></span></div></li>
</ul>
</li>
<li class="level2"><div class="li"><span class="li"><a href="#service_class_design_guidelines_advanced" class="toc">Service class design guidelines (advanced)</a></span></div>
<ul class="toc">
<li class="level3"><div class="li"><span class="li"><a href="#cross-dll_safety" class="toc">Cross-DLL safety</a></span></div></li>
<li class="level3"><div class="li"><span class="li"><a href="#entrypoint_service_efficiency" class="toc">Entrypoint service efficiency</a></span></div></li></ul>
</li></ul>
</li></ul>
</div>
</div>
<h1><a name="foobar2000_v1.6_sdk_readme" id="foobar2000_v1.6_sdk_readme">foobar2000 v1.6 SDK readme</a></h1>
<div class="level1">
</div>
<!-- SECTION "foobar2000 v1.6 SDK readme" [1-42] -->
<h2><a name="compatibility" id="compatibility">Compatibility</a></h2>
<div class="level2">
<p>
Components built with this <acronym title="Software Development Kit">SDK</acronym> are compatible with foobar2000 1.4 and newer. They are not compatible with any earlier versions (will fail to load), and not guaranteed to be compatible with any future versions, though upcoming releases will aim to maintain compatibility as far as possible without crippling newly added functionality.
</p>
<p>
You can alter the targeted foobar2000 <acronym title="Application Programming Interface">API</acronym> level, edit <acronym title="Software Development Kit">SDK</acronym>/foobar2000.h and change the value of FOOBAR2000_TARGET_VERSION.
</p>
<p>
Currently supported values are 79 (for 1.4 series) and 80 (for 1.5 &amp; 1.6 series).
</p>
</div>
<!-- SECTION "Compatibility" [43-610] -->
<h2><a name="microsoft_visual_studio_compatibility" id="microsoft_visual_studio_compatibility">Microsoft Visual Studio compatibility</a></h2>
<div class="level2">
<p>
This <acronym title="Software Development Kit">SDK</acronym> contains project files for Visual Studio 2017.
</p>
</div>
<!-- SECTION "Microsoft Visual Studio compatibility" [611-718] -->
<h3><a name="ill_behavior_of_visual_c_whole_program_optimization" id="ill_behavior_of_visual_c_whole_program_optimization">Ill behavior of Visual C whole program optimization</a></h3>
<div class="level3">
<p>
Visual Studio versions from 2012 up produce incorrect output with default release settings on foobar2000 code - see <a href="http://www.hydrogenaud.io/forums/index.php?showtopic=108411" class="urlextern" title="http://www.hydrogenaud.io/forums/index.php?showtopic=108411" rel="nofollow">forum thread</a> for details. You can mitigate this issue by compiling all affected code (foobar2000 <acronym title="Software Development Kit">SDK</acronym> code along with everything that uses foobar2000 <acronym title="Software Development Kit">SDK</acronym> classes) with /d2notypeopt option. This is set by default on project files provided with the <acronym title="Software Development Kit">SDK</acronym>; please make sure that you set this option on any projects of your own.
</p>
<p>
If you&#039;re aware of a better workaround - such as a source code change rather than setting an obscure compiler flag - please let us know; posting on the forum is preferred for the benefit of other users of this <acronym title="Software Development Kit">SDK</acronym>.
</p>
</div>
<!-- SECTION "Ill behavior of Visual C whole program optimization" [719-1498] -->
<h3><a name="virtual_memory_range_for_pch_exceeded_error" id="virtual_memory_range_for_pch_exceeded_error">&quot;virtual memory range for PCH exceeded&quot; error</a></h3>
<div class="level3">
<p>
By convention, foobar2000 code used to #include every single <acronym title="Software Development Kit">SDK</acronym> and utility header in a precompiled header (PCH) file. This became an issue with certain Visual Studio setups, as the PCH payload became extremely large.
</p>
<p>
The <acronym title="Software Development Kit">SDK</acronym> has been changed to reduce the amount of unnecessary code shoved into #included headers; errors of this type are yet to be seen with this version of the foobar2000 <acronym title="Software Development Kit">SDK</acronym> compiled under VS2017.
</p>
<p>
If you run into this error, we recommend trimming down the #includes and only referencing specific headers from helpers instead of #including all of them (via old helpers.h).
</p>
</div>
<!-- SECTION "virtual memory range for PCH exceeded error" [1499-2150] -->
<h2><a name="version_1.6_notes" id="version_1.6_notes">Version 1.6 notes</a></h2>
<div class="level2">
</div>
<!-- SECTION "Version 1.6 notes" [2151-2180] -->
<h3><a name="windows_xp_support" id="windows_xp_support">Windows XP support</a></h3>
<div class="level3">
<p>
The <acronym title="Software Development Kit">SDK</acronym> project files are configured for targetting Windows 7 and newer, with SSE2 level instruction set.
</p>
<p>
If you really must compile components that run on 20 years old computers, you can still change relevant settings, or use an older <acronym title="Software Development Kit">SDK</acronym>. Please test your components on actual hardware if you do so, VS2017 compiler has been known to output SSE opcodes when specifically told not to.
</p>
</div>
<!-- SECTION "Windows XP support" [2181-2597] -->
<h3><a name="audio_output_api_extensions" id="audio_output_api_extensions">Audio output API extensions</a></h3>
<div class="level3">
<p>
New methods have been added to the output <acronym title="Application Programming Interface">API</acronym>, such as reporting whether your output is low-latency or high-latency, to interop with the new fading code.
</p>
<p>
foobar2000 now provides a suite of special fixes for problematic output implementations (guarenteed update() calls in regular intervals, silence injected at the end); use flag_needs_shims to enable with your output. While such feature might seem unnecessary, it allowed individual outputs to be greatly simplified, removing a lot of other special fixes implemented per output.
</p>
</div>
<!-- SECTION "Audio output API extensions" [2598-3169] -->
<h3><a name="webp_support_imageloaderlite" id="webp_support_imageloaderlite">WebP support, imageLoaderLite</a></h3>
<div class="level3">
<p>
Use fb2k::imageLoaderLite <acronym title="Application Programming Interface">API</acronym> to load a Gdiplus image from a memory block, or to extract info without actually decoding the picture. It supports WebP payload and will be updated with any formats added in the future.
</p>
</div>
<!-- SECTION "WebP support, imageLoaderLite" [3170-3426] -->
<h3><a name="file_cache_utilities" id="file_cache_utilities">File cache utilities</a></h3>
<div class="level3">
<p>
New interface has been introduced - read_ahead_tools - to access advanced playback settings for read-ahead cache; primarily needed if your decoder needs to open additional files over the internet.
</p>
</div>
<!-- SECTION "File cache utilities" [3427-3655] -->
<h3><a name="cuesheet_wrapper_fixes" id="cuesheet_wrapper_fixes">Cuesheet wrapper fixes</a></h3>
<div class="level3">
<p>
Wrapper code to support embedded cuesheets on arbitrary formats has been updated to deal with remote files gracefully, that is not present any chapters on such.
</p>
</div>
<!-- SECTION "Cuesheet wrapper fixes" [3656-3850] -->
<h3><a name="libppui" id="libppui">libPPUI</a></h3>
<div class="level3">
<p>
Notable changes: * WebP vs Gdiplus interop (in case you want to load WebP into Gdiplus in your own app - in fb2k, use imageLoaderLite) * Fixed horrible GdiplusImageFromMem() bug * Combo boxes in CListControl * CListControl graying/disabling of individual items
</p>
</div>
<!-- SECTION "libPPUI" [3851-4130] -->
<h2><a name="version_1.5_notes" id="version_1.5_notes">Version 1.5 notes</a></h2>
<div class="level2">
</div>
<!-- SECTION "Version 1.5 notes" [4131-4160] -->
<h3><a name="libppui1" id="libppui1">libPPUI</a></h3>
<div class="level3">
<p>
Various code from the helpers projects that was in no way foobar2000 specific became libPPUI. In addition, Default User Interface list control has been thrown in. libPPUI is released under a non-restrictive license. Reuse in other projects - including commercial projects - is encouraged. Credits in binary redistribution are not required.
</p>
<p>
Existing foobar2000 components that reference <acronym title="Software Development Kit">SDK</acronym> helpers/ATLHelpers will need updating to reference libPPUI instead. Separate helpers/ATLHelpers projects are no more, as all projects depend on libPPUI which requires ATL/WTL.
</p>
</div>
<!-- SECTION "libPPUI" [4161-4746] -->
<h2><a name="version_1.4_notes" id="version_1.4_notes">Version 1.4 notes</a></h2>
<div class="level2">
</div>
<!-- SECTION "Version 1.4 notes" [4747-4776] -->
<h3><a name="namespace_cleanup" id="namespace_cleanup">Namespace cleanup</a></h3>
<div class="level3">
<p>
Some very old inconsistencies in the code have been cleaned up. Various bit_array classes are now in pfc namespace where they belong. Please use pfc::bit_array and so on in new code. If you have code that references bit_array classes without the pfc:: prefix, put “using pfc::bit_array” in your headers to work around it.
</p>
</div>
<!-- SECTION "Namespace cleanup" [4777-5126] -->
<h3><a name="decoders" id="decoders">Decoders</a></h3>
<div class="level3">
</div>
<h4><a name="invoking_decoders" id="invoking_decoders">Invoking decoders</a></h4>
<div class="level4">
<p>
Each new decoder (input_entry) now provides a get_guid() and get_name() to allow user to choose the order in which they&#039;re invoked as well as disable individual installed decoders. Because of this, you are no longer supposed to walk input_entry instances in your code; however many existing components do so because this was the way things were expected to work in all past versions before 1.4.
</p>
<p>
In most cases there&#039;s nothing that you need to do about this, unless you have code that talks to input_entry instance methods directly.
</p>
</div>
<h5><a name="input_manager" id="input_manager">input_manager</a></h5>
<div class="level5">
<p>
The proper way to instantiate any input related classes is to call input_manager; it manages opening of decoders respecting user&#039;s decoder merit settings. Calling any of the helper methods to open decoders / read tags / etc in the <acronym title="Software Development Kit">SDK</acronym> will call input_manager if available (v1.4) and fall back to walking input_entry services if not (v1.3).
</p>
</div>
<h5><a name="input_entry_shim" id="input_entry_shim">input_entry shim</a></h5>
<div class="level5">
<p>
If your component targets <acronym title="Application Programming Interface">API</acronym> level lower than 79, all your attempts to walk input_entry services return a shim service that redirects all your calls to input_manager. You cannot walk actual input_entry services.
</p>
<p>
This is to keep existing components working as intended.
</p>
<p>
If your component targets <acronym title="Application Programming Interface">API</acronym> level 79 (which means it won&#039;t load on v1.3), the shim is not installed as your component is expected to be aware of the new semantics.
</p>
</div>
<h4><a name="implementing_decoders" id="implementing_decoders">Implementing decoders</a></h4>
<div class="level4">
<p>
Many new input methods have been added and some are mandatory for all code, in particular reporting of decoder name and GUID; existing code not providing these will not compile. However some of the methods now required to be provided by an input class are mundane and will be left blank in majority of implementations; an input_stubs class has been introduced to help with these. In past <acronym title="Software Development Kit">SDK</acronym> versions, your input class would not derive from another class; it is now recommended to derive from input_stubs to avoid having to supply mundane methods yourself.
</p>
</div>
<h5><a name="specify_supported_interfaces" id="specify_supported_interfaces">Specify supported interfaces</a></h5>
<div class="level5">
<p>
You can now control which level of decoder <acronym title="Application Programming Interface">API</acronym> your instance supports from your input class instead of using multi parameter input_factory classes.
</p>
<p>
The input_stubs class provides these for your convenience:
</p>
<pre class="code">
typedef input_decoder_v4 interface_decoder_t;
typedef input_info_reader interface_info_reader_t;
typedef input_info_writer interface_info_writer_t;
</pre>
<p>
Override these in your input class to indicate supported interfaces.
</p>
<p>
For an example, if your input supports remove_tags(), indicate that you implement input_info_writer_v2:
</p>
<pre class="code">
typedef input_info_writer_v2 interface_info_writer_t;
</pre>
</div>
<!-- SECTION "Decoders" [5127-7762] -->
<h3><a name="dynamic_runtime" id="dynamic_runtime">Dynamic runtime</a></h3>
<div class="level3">
<p>
As of version 1.4, foobar2000 is compiled with dynamic Visual C runtime and redistributes Visual C runtime libraries with the installer, putting them in the foobar2000 installation folder if necessary. The benefits of this are: * Smaller component DLLs * Increased limit of how many component DLLs can be loaded.
</p>
<p>
This <acronym title="Software Development Kit">SDK</acronym> comes configured for dynamic runtime by default. If you wish to support foobar2000 versions older than 1.4, change to static runtime or make sure that your users have the runtime installed.
</p>
</div>
<!-- SECTION "Dynamic runtime" [7763-8303] -->
<h3><a name="service_query" id="service_query">service_query()</a></h3>
<div class="level3">
<p>
tl;dr if you don&#039;t know what this is about you probably don&#039;t care and your component isn&#039;t in any way affected by this.
</p>
<p>
The way service_query() is implemented has been redesigned for performance reasons - the old way ( implemented per interface class via FB2K_MAKE_SERVICE_INTERFACE macro ) resulted in every single class_guid from the entire <acronym title="Software Development Kit">SDK</acronym> being included in your DLL, due to strange behaviors of Microsoft linker.
</p>
<p>
The service_query() function itself is now provided by service_impl_* classes, so it&#039;s materialized only for services that your code implements and spawns.
</p>
<p>
The default implementation calls a newly added static method of handle_service_query(), implemented in service_base to check against all supported interfaces by walking derived class chain.
</p>
<p>
If you wish to override it, create a function with a matching signature in your class and it will be called instead:
</p>
<pre class="code">
class myClass : public service_base {
public:
static bool handle_service_query(service_ptr &amp; out, const GUID &amp; guid, myClass * in) {
if ( guid == myClassGUID ) {
out = in; return true;
}
return false;
}
};
</pre>
</div>
<h4><a name="multi-inheritance" id="multi-inheritance">Multi-inheritance</a></h4>
<div class="level4">
<p>
The above change to service_query() implementation rules obviously breaks any existing code where one class inherits from multiple service classes and supplies a custom service_query().
</p>
<p>
While using multi inheritance is not recommended and very rarely done, a new template has been added to help with such cases: service_multi_inherit&lt;class1, class2&gt;.
</p>
<p>
You can use it to avoid having to supply service_query() code yourself and possibly change it if service_query() semantics change again in the future.
</p>
</div>
<!-- SECTION "service_query()" [8304-10014] -->
<h2><a name="version_1.3_notes" id="version_1.3_notes">Version 1.3 notes</a></h2>
<div class="level2">
<p>
foobar2000 version 1.3 uses different metadb behavior semantics than older versions, to greatly improve the performance of multithreaded operation by reducing the time spent within global metadb locks.
</p>
<p>
Any methods that:
</p>
<ul>
<li class="level1"><div class="li"> Lock the metadb - database_lock() etc</div>
</li>
<li class="level1"><div class="li"> Retrieve direct pointers to metadb info - get_info_locked() style</div>
</li>
</ul>
<p>
.. are now marked deprecated and implemented only for backwards compatibility; they should not be used in any new code.
</p>
<p>
It is recommended that you change your existing code using these to obtain track information using new get_info_ref() style methods for much better performance as these methods have minimal overhead and require no special care when used in multiple concurrent threads.
</p>
</div>
<!-- SECTION "Version 1.3 notes" [10015-10770] -->
<h2><a name="basic_usage" id="basic_usage">Basic usage</a></h2>
<div class="level2">
<p>
Each component must link against:
</p>
<ul>
<li class="level1"><div class="li"> foobar2000_<acronym title="Software Development Kit">SDK</acronym> project (contains declarations of services and various service-specific helper code)</div>
</li>
<li class="level1"><div class="li"> foobar2000_component_client project (contains DLL entrypoint)</div>
</li>
<li class="level1"><div class="li"> shared.dll (various helper code, mainly win32 function wrappers taking UTF-8 strings)</div>
</li>
<li class="level1"><div class="li"> PFC (non-<acronym title="Operating System">OS</acronym>-specific helper class library)</div>
</li>
</ul>
<p>
Optionally, components can use helper libraries with various non-critical code that is commonly reused across various foobar2000 components:
</p>
<ul>
<li class="level1"><div class="li"> foobar2000_<acronym title="Software Development Kit">SDK</acronym>_helpers - a library of various helper code commonly used by foobar2000 components.</div>
</li>
<li class="level1"><div class="li"> foobar2000_ATL_helpers - another library of various helper code commonly used by foobar2000 components; requires WTL.</div>
</li>
</ul>
<p>
Foobar2000_<acronym title="Software Development Kit">SDK</acronym>, foobar2000_component_client and PFC are included in sourcecode form; you can link against them by adding them to your workspace and using dependencies. To link against shared.dll, you must add “shared.lib” to linker input manually.
</p>
<p>
Component code should include the following header files:
</p>
<ul>
<li class="level1"><div class="li"> foobar2000.h from <acronym title="Software Development Kit">SDK</acronym> - do not include other headers from the <acronym title="Software Development Kit">SDK</acronym> directory directly, they&#039;re meant to be referenced by foobar2000.h only; it also includes PFC headers and shared.dll helper declaration headers.</div>
</li>
<li class="level1"><div class="li"> Necessary headers from libPPUI and helpers, which both contain various code commonly used by fb2k components.</div>
</li>
</ul>
</div>
<!-- SECTION "Basic usage" [10771-12139] -->
<h2><a name="structure_of_a_component" id="structure_of_a_component">Structure of a component</a></h2>
<div class="level2">
<p>
A component is a DLL that implements one or more entrypoint services and interacts with services provided by other components.
</p>
</div>
<!-- SECTION "Structure of a component" [12140-12306] -->
<h3><a name="services" id="services">Services</a></h3>
<div class="level3">
<p>
A service type is an interface class, deriving directly or indirectly from <code>service_base</code> class. A service type class must not have any data members; it can only provide virtual methods (to be overridden by service implementation), helper non-virtual methods built around virtual methods, static helper methods, and constants / enums. Each service interface class must have a static <code>class_guid</code> member, used for identification when enumerating services or querying for supported functionality. A service type declaration should declare a class with public virtual/helper/static methods, and use <code>FB2K_MAKE_SERVICE_INTERFACE()</code> / <code>FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT()</code> macro to implement standard service behaviors for the class; additionally, <code>class_guid</code> needs to be defined outside class declaration (e.g. <code>const GUID someclass::class_guid = {&hellip;.};</code> ). Note that most of components will not declare their own service types, they will only implement existing ones declared in the <acronym title="Software Development Kit">SDK</acronym>.
</p>
<p>
A service implementation is a class derived from relevant service type class, implementing virtual methods declared by service type class. Note that service implementation class does not implement virtual methods declared by service_base; those are implemented by service type declaration framework (<code>service_query</code>) or by instantiation framework (<code>service_add_ref</code> / <code>service_release</code>). Service implementation classes are instantiated using <code>service_factory</code> templates in case of entrypoint services (see below), or using <code>service_impl_t</code> template and operator <code>new</code>: ”<code>myserviceptr = new service_impl_t&lt;myservice_impl&gt;(params);</code>”.
</p>
<p>
Each service object provides reference counter features and (<code>service_add_ref()</code> and <code>service_release()</code> methods) as well as a method to query for extended functionality (<code>service_query()</code> method). Those methods are implemented by service framework and should be never overridden by service implementations. These methods should also never be called directly - reference counter methods are managed by relevant autopointer templates, <code>service_query_t</code> function template should be used instead of calling <code>service_query</code> directly, to ensure type safety and correct type conversions.
</p>
</div>
<!-- SECTION "Services" [12307-14572] -->
<h3><a name="entrypoint_services" id="entrypoint_services">Entrypoint services</a></h3>
<div class="level3">
<p>
An entrypoint service type is a special case of a service type that can be registered using <code>service_factory</code> templates, and then accessed from any point of service system (excluding DLL startup/shutdown code, such as code inside static object constructors/destructors). An entrypoint service type class must directly derive from <code>service_base</code>.
</p>
<p>
Registered entrypoint services can be accessed using:
</p>
<ul>
<li class="level1"><div class="li"> For services types with variable number of implementations registered: <code>service_enum_t&lt;T&gt;</code> template, <code>service_class_helper_t&lt;T&gt;</code> template, etc, e.g. <pre class="code cpp">service_enum_t&lt;someclass&gt; e; service_ptr_t&lt;someclass&gt; ptr; <span class="kw1">while</span><span class="br0">&#40;</span>e.<span class="me1">next</span><span class="br0">&#40;</span>ptr<span class="br0">&#41;</span><span class="br0">&#41;</span> ptr-&gt;dosomething<span class="br0">&#40;</span><span class="br0">&#41;</span>;</pre></div>
</li>
<li class="level1"><div class="li"> For services types with a single always-present implementation registered - such as core services like <code>playlist_manager</code> - using <code>someclass::get()</code>, e.g.: <pre class="code cpp"><span class="kw4">auto</span> api = someclass::<span class="me2">get</span><span class="br0">&#40;</span><span class="br0">&#41;</span>; api-&gt;dosomething<span class="br0">&#40;</span><span class="br0">&#41;</span>; api-&gt;dosomethingelse<span class="br0">&#40;</span><span class="br0">&#41;</span>;</pre></div>
</li>
<li class="level1"><div class="li"> Using per-service-type defined static helper functions, e.g. <code>someclass::g_dosomething()</code> - those use relevant service enumeration methods internally.</div>
</li>
</ul>
<p>
An entrypoint service type must use <code>FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT()</code> macro to implement standard entrypoint service behaviors, as opposed to all other service types that use <code>FB2K_MAKE_SERVICE_INTERFACE()</code> macro instead.
</p>
<p>
You can register your own entrypoint service implementations using either <code>service_factory_t</code> or <code>service_factory_single_t</code> template - the difference between the two is that the former instantiates the class on demand, while the latter keeps a single static instance and returns references to it when requested; the latter is faster but usable only for things that have no per-instance member data to maintain. Each <code>service_factory_t</code> / <code>service_factory_single_t</code> instance should be a static variable, such as: ”<code>static service_factory_t&lt;myclass&gt; g_myclass_factory;</code>”.
</p>
<p>
Certain service types require custom <code>service_factory</code> helper templates to be used instead of standard <code>service_factory_t</code> / <code>service_factory_single_t</code> templates; see documentation of specific service type for exact info about registering.
</p>
<p>
A typical entrypoint service implementation looks like this:
</p>
<pre class="code cpp"><span class="kw2">class</span> myservice_impl : <span class="kw2">public</span> myservice <span class="br0">&#123;</span>
<span class="kw2">public</span>:
<span class="kw4">void</span> dosomething<span class="br0">&#40;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>....<span class="br0">&#125;</span>;
<span class="kw4">void</span> dosomethingelse<span class="br0">&#40;</span><span class="kw4">int</span> meh<span class="br0">&#41;</span> <span class="br0">&#123;</span>...<span class="br0">&#125;</span>;
<span class="br0">&#125;</span>;
<span class="kw4">static</span> service_factory_single_t&lt;myservice_impl&gt; g_myservice_impl_factory;</pre>
</div>
<!-- SECTION "Entrypoint services" [14573-17030] -->
<h3><a name="service_extensions" id="service_extensions">Service extensions</a></h3>
<div class="level3">
<p>
Additional methods can be added to any service type, by declaring a new service type class deriving from service type class you want to extend. For example:
</p>
<pre class="code cpp"><span class="kw2">class</span> myservice : <span class="kw2">public</span> service_base <span class="br0">&#123;</span> <span class="kw2">public</span>: <span class="kw2">virtual</span> <span class="kw4">void</span> dosomething<span class="br0">&#40;</span><span class="br0">&#41;</span> = <span class="nu0">0</span>; FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT<span class="br0">&#40;</span>myservice<span class="br0">&#41;</span>; <span class="br0">&#125;</span>;
<span class="kw2">class</span> myservice_v2 : <span class="kw2">public</span> myservice <span class="br0">&#123;</span> <span class="kw2">public</span>: <span class="kw2">virtual</span> <span class="kw4">void</span> dosomethingelse<span class="br0">&#40;</span><span class="br0">&#41;</span> = <span class="nu0">0</span>; FB2K_MAKE_SERVICE_INTERFACE<span class="br0">&#40;</span>myservice_v2, myservice<span class="br0">&#41;</span>; <span class="br0">&#125;</span>;</pre>
<p>
In such scenario, to query whether a myservice instance is a <code>myservice_v2</code> and to retrieve <code>myservice_v2</code> pointer, use <code>service_query</code> functionality:
</p>
<pre class="code cpp">service_ptr_t&lt;myservice&gt; ptr;
<span class="br0">&#40;</span>...<span class="br0">&#41;</span>
service_ptr_t&lt;myservice_v2&gt; ptr_ex;
<span class="kw1">if</span> <span class="br0">&#40;</span>ptr-&gt;service_query_t<span class="br0">&#40;</span>ptr_ex<span class="br0">&#41;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span> <span class="coMULTI">/* ptr_ex is a valid pointer to myservice_v2 interface of our myservice instance */</span> <span class="br0">&#40;</span>...<span class="br0">&#41;</span> <span class="br0">&#125;</span>
<span class="kw1">else</span> <span class="br0">&#123;</span><span class="coMULTI">/* this myservice implementation does not implement myservice_v2 */</span> <span class="br0">&#40;</span>...<span class="br0">&#41;</span> <span class="br0">&#125;</span></pre>
</div>
<!-- SECTION "Service extensions" [17031-17970] -->
<h3><a name="autopointer_template_use" id="autopointer_template_use">Autopointer template use</a></h3>
<div class="level3">
<p>
When performing most kinds of service operations, <code>service_ptr_t&lt;T&gt;</code> template should be used rather than working with service pointers directly; it automatically manages reference counter calls, ensuring that the service object is deleted when it is no longer referenced.
</p>
<p>
For convenience, all service classes have <code>myclass::ptr</code> typedef&#039;d to <code>service_ptr_t&lt;myclass&gt;</code>.
</p>
<p>
When working with pointers to core fb2k services, just use C++11 <code>auto</code> keyword and <code>someclass::get()</code>, e.g. <code>auto myAPI = playlist_manager::get();</code>
</p>
</div>
<!-- SECTION "Autopointer template use" [17971-18538] -->
<h3><a name="exception_use" id="exception_use">Exception use</a></h3>
<div class="level3">
<p>
Most of <acronym title="Application Programming Interface">API</acronym> functions use C++ exceptions to signal failure conditions. All used exception classes must derive from <code>std::exception</code> (which <code>pfc::exception</code> is typedef&#039;d to); this design allows various instances of code to use single <code>catch()</code> line to get human-readable description of the problem to display.
</p>
<p>
Additionally, special subclasses of exceptions are defined for use in specific conditions, such as <code>exception_io</code> for I/O failures. As a result, you must provide an exception handler whenever you invoke any kind of I/O code that may fail, unless in specific case calling context already handles exceptions (e.g. input implementation code - any exceptions should be forwarded to calling context, since exceptions are a part of input <acronym title="Application Programming Interface">API</acronym>).
</p>
<p>
Implementations of global callback services such as <code>playlist_callback</code>, <code>playback_callback</code> or <code>library_callback</code> must not throw unhandled exceptions; behaviors in case they do are undefined (app termination is to be expected).
</p>
</div>
<!-- SECTION "Exception use" [18539-19556] -->
<h3><a name="storing_configuration" id="storing_configuration">Storing configuration</a></h3>
<div class="level3">
<p>
In order to create your entries in the configuration file, you must instantiate some objects that derive from <code>cfg_var</code> class. Those can be either predefined classes (<code>cfg_int</code>, <code>cfg_string</code>, etc) or your own classes implementing relevant methods.
</p>
<p>
Each <code>cfg_var</code> instance has a GUID assigned, to identify its configuration file entry. The GUID is passed to its constructor (which implementations must take care of, typically by providing a constructor that takes a GUID and forwards it to <code>cfg_var</code> constructor).
</p>
<p>
Note that <code>cfg_var</code> objects can only be instantiated statically (either directly as static objects, or as members of other static objects). Additionally, you can create configuration data objects that can be accessed by other components, by implementing <code>config_object</code> service. Some standard configuration variables can be also accessed using <code>config_object</code> interface.
</p>
</div>
<!-- SECTION "Storing configuration" [19557-20492] -->
<h3><a name="use_of_global_callback_services" id="use_of_global_callback_services">Use of global callback services</a></h3>
<div class="level3">
<p>
Multiple service classes presented by the <acronym title="Software Development Kit">SDK</acronym> allow your component to receive notifications about various events:
</p>
<ul>
<li class="level1"><div class="li"> file_operation_callback - tracking file move/copy/delete operations.</div>
</li>
<li class="level1"><div class="li"> library_callback - tracking Media Library content changes.</div>
</li>
<li class="level1"><div class="li"> metadb_io_callback - tracking tag read / write operations altering cached/displayed media information.</div>
</li>
<li class="level1"><div class="li"> play_callback - tracking playback related events.</div>
</li>
<li class="level1"><div class="li"> playback_statistics_collector - collecting information about played tracks.</div>
</li>
<li class="level1"><div class="li"> playlist_callback, playlist_callback_single - tracking playlist changes (the latter tracks only active playlist changes).</div>
</li>
<li class="level1"><div class="li"> playback_queue_callback - tracking playback queue changes.</div>
</li>
<li class="level1"><div class="li"> titleformat_config_callback - tracking changes of title formatting configuration.</div>
</li>
<li class="level1"><div class="li"> ui_drop_item_callback - filtering items dropped into the UI.</div>
</li>
</ul>
<p>
All of global callbacks operate only within main app thread, allowing easy cooperation with windows <acronym title="Graphical User Interface">GUI</acronym> - for an example, you perform playlist view window repainting directly from your playlist_callback implementation.
</p>
</div>
<h4><a name="global_callback_recursion_issues" id="global_callback_recursion_issues">Global callback recursion issues</a></h4>
<div class="level4">
<p>
There are restrictions on things that are legal to call from within global callbacks. For an example, you can&#039;t modify a playlist from inside a playlist callback, because there are other registered callbacks tracking playlist changes that haven&#039;t been notified about the change being currently processed yet.
</p>
<p>
You must not enter modal message loops from inside global callbacks, as those allow any unrelated code (queued messages, user input, etc.) to be executed, without being aware that a global callback is being processed. Certain global <acronym title="Application Programming Interface">API</acronym> methods such as metadb_io::load_info_multi or threaded_process::run_modal enter modal loops when called. Use main_thread_callback service to avoid this problem and delay execution of problematic code.
</p>
<p>
You should also avoid firing a cross-thread SendMessage() inside global callbacks as well as performing any operations that dispatch global callbacks when handling a message that was sent through a cross-thread SendMessage(). Doing so may result in rare unwanted recursions - SendMessage() call will block the calling thread and immediately process any incoming cross-thread SendMessage() messages. If you&#039;re handling a cross-thread SendMessage() and need to perform such operation, delay it using PostMessage() or main_thread_callback.
</p>
</div>
<!-- SECTION "Use of global callback services" [20493-22914] -->
<h2><a name="service_class_design_guidelines_advanced" id="service_class_design_guidelines_advanced">Service class design guidelines (advanced)</a></h2>
<div class="level2">
<p>
This chapter describes things you should keep on your mind when designing your own service type classes. Since 99% of components will only implement existing service types rather than adding their own cross-DLL-communication protocols, you can probably skip reading this chapter.
</p>
</div>
<!-- SECTION "Service class design guidelines (advanced)" [22915-23251] -->
<h3><a name="cross-dll_safety" id="cross-dll_safety">Cross-DLL safety</a></h3>
<div class="level3">
<p>
It is important that all function parameters used by virtual methods of services are cross-DLL safe (do not depend on compiler-specific or runtime-specific behaviors, so no unexpected behaviors occur when calling code is built with different compiler/runtime than callee). To achieve this, any classes passed around must be either simple objects with no structure that could possibly vary with different compilers/runtimes (i.e. make sure that any memory blocks are freed on the side that allocated them); easiest way to achieve this is to reduce all complex data objects or classes passed around to interfaces with virtual methods, with implementation details hidden from callee. For an example, use <code>pfc::string_base&amp;</code> as parameter to a function that is meant to return variable-length strings.
</p>
</div>
<!-- SECTION "Cross-DLL safety" [23252-24079] -->
<h3><a name="entrypoint_service_efficiency" id="entrypoint_service_efficiency">Entrypoint service efficiency</a></h3>
<div class="level3">
<p>
When designing an entrypoint service interface meant to have multiple different implementations, you should consider making it possible for all its implementations to use <code>service_factory_single_t</code> (i.e. no per-instance member data); by e.g. moving functionality that needs multi-instance operation to a separate service type class that is created on-demand by one of entrypoint service methods. For example:
</p>
<pre class="code cpp"><span class="kw2">class</span> myservice : <span class="kw2">public</span> service_base <span class="br0">&#123;</span>
<span class="kw2">public</span>:
<span class="co1">//this method accesses per-instance member data of the implementation class</span>
<span class="kw2">virtual</span> <span class="kw4">void</span> workerfunction<span class="br0">&#40;</span><span class="kw4">const</span> <span class="kw4">void</span> * p_databuffer,t_size p_buffersize<span class="br0">&#41;</span> = <span class="nu0">0</span>;
<span class="co1">//this method is used to determine which implementation can be used to process specific data stream.</span>
<span class="kw2">virtual</span> <span class="kw4">bool</span> queryfunction<span class="br0">&#40;</span><span class="kw4">const</span> <span class="kw4">char</span> * p_dataformat<span class="br0">&#41;</span> = <span class="nu0">0</span>;
&nbsp;
FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT<span class="br0">&#40;</span>myservice<span class="br0">&#41;</span>;
<span class="br0">&#125;</span>;
<span class="br0">&#40;</span>...<span class="br0">&#41;</span>
service_ptr_t&lt;myservice&gt; findservice<span class="br0">&#40;</span><span class="kw4">const</span> <span class="kw4">char</span> * p_dataformat<span class="br0">&#41;</span> <span class="br0">&#123;</span>
service_enum_t&lt;myservice&gt; e; service_ptr_t&lt;myservice&gt; ptr;
<span class="co1">//BOTTLENECK, this dynamically instantiates the service for each query.</span>
<span class="kw1">while</span><span class="br0">&#40;</span>e.<span class="me1">next</span><span class="br0">&#40;</span>ptr<span class="br0">&#41;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
<span class="kw1">if</span> <span class="br0">&#40;</span>ptr-&gt;queryfunction<span class="br0">&#40;</span>p_dataformat<span class="br0">&#41;</span><span class="br0">&#41;</span> <span class="kw1">return</span> ptr;
<span class="br0">&#125;</span>
throw exception_io_data<span class="br0">&#40;</span><span class="br0">&#41;</span>;
<span class="br0">&#125;</span></pre>
<p>
.. should be changed to:
</p>
<pre class="code cpp"><span class="co1">//no longer an entrypoint service - use myservice::instantiate to get an instance instead.</span>
<span class="kw2">class</span> myservice_instance : <span class="kw2">public</span> service_base <span class="br0">&#123;</span>
<span class="kw2">public</span>:
<span class="kw2">virtual</span> <span class="kw4">void</span> workerfunction<span class="br0">&#40;</span><span class="kw4">const</span> <span class="kw4">void</span> * p_databuffer,t_size p_buffersize<span class="br0">&#41;</span> = <span class="nu0">0</span>;
FB2K_MAKE_SERVICE_INTERFACE<span class="br0">&#40;</span>myservice_instance,service_base<span class="br0">&#41;</span>;
<span class="br0">&#125;</span>;
&nbsp;
<span class="kw2">class</span> myservice : <span class="kw2">public</span> service_base <span class="br0">&#123;</span>
<span class="kw2">public</span>:
<span class="co1">//this method is used to determine which implementation can be used to process specific data stream.</span>
<span class="kw2">virtual</span> <span class="kw4">bool</span> queryfunction<span class="br0">&#40;</span><span class="kw4">const</span> <span class="kw4">char</span> * p_dataformat<span class="br0">&#41;</span> = <span class="nu0">0</span>;
<span class="kw2">virtual</span> service_ptr_t&lt;myservice_instance&gt; instantiate<span class="br0">&#40;</span><span class="br0">&#41;</span> = <span class="nu0">0</span>;
FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT<span class="br0">&#40;</span>myservice<span class="br0">&#41;</span>;
<span class="br0">&#125;</span>;
&nbsp;
template&lt;typename t_myservice_instance_impl&gt;
<span class="kw2">class</span> myservice_impl_t : <span class="kw2">public</span> myservice <span class="br0">&#123;</span>
<span class="kw2">public</span>:
<span class="co1">//implementation of myservice_instance must provide static bool g_queryformatfunction(const char*);</span>
<span class="kw4">bool</span> queryfunction<span class="br0">&#40;</span><span class="kw4">const</span> <span class="kw4">char</span> * p_dataformat<span class="br0">&#41;</span> <span class="br0">&#123;</span><span class="kw1">return</span> t_myservice_instance_impl::<span class="me2">g_queryfunction</span><span class="br0">&#40;</span>p_dataformat<span class="br0">&#41;</span>;<span class="br0">&#125;</span>
service_ptr_t&lt;myservice_instance&gt; instantiate<span class="br0">&#40;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span><span class="kw1">return</span> <span class="kw3">new</span> service_impl_t&lt;t_myservice_instance_impl&gt;<span class="br0">&#40;</span><span class="br0">&#41;</span>;<span class="br0">&#125;</span>
<span class="br0">&#125;</span>;
&nbsp;
template&lt;typename t_myservice_instance_impl&gt; <span class="kw2">class</span> myservice_factory_t :
<span class="kw2">public</span> service_factory_single_t&lt;myservice_impl_t&lt;t_myservice_instance_impl&gt; &gt; <span class="br0">&#123;</span><span class="br0">&#125;</span>;
<span class="co1">//usage: static myservice_factory_t&lt;myclass&gt; g_myclass_factory;</span>
&nbsp;
<span class="br0">&#40;</span>...<span class="br0">&#41;</span>
&nbsp;
service_ptr_t&lt;myservice_instance&gt; findservice<span class="br0">&#40;</span><span class="kw4">const</span> <span class="kw4">char</span> * p_dataformat<span class="br0">&#41;</span> <span class="br0">&#123;</span>
service_enum_t&lt;myservice&gt; e; service_ptr_t&lt;myservice&gt; ptr;
<span class="co1">//no more bottleneck, enumerated service does not perform inefficient operations when requesting an instance.</span>
<span class="kw1">while</span><span class="br0">&#40;</span>e.<span class="me1">next</span><span class="br0">&#40;</span>ptr<span class="br0">&#41;</span><span class="br0">&#41;</span> <span class="br0">&#123;</span>
<span class="co1">//&quot;inefficient&quot; part is used only once, with implementation that actually supports what we request.</span>
<span class="kw1">if</span> <span class="br0">&#40;</span>ptr-&gt;queryfunction<span class="br0">&#40;</span>p_dataformat<span class="br0">&#41;</span><span class="br0">&#41;</span> <span class="kw1">return</span> ptr-&gt;instantiate<span class="br0">&#40;</span><span class="br0">&#41;</span>;
<span class="br0">&#125;</span>
throw exception_io_data<span class="br0">&#40;</span><span class="br0">&#41;</span>;
<span class="br0">&#125;</span></pre>
</div>
<!-- SECTION "Entrypoint service efficiency" [24080-] --></div>
</body>
</html>