Mercurial > foo_out_sdl

comparison foosdk/sdk/foobar2000/SDK/metadb_index.h @ 1:20d02a178406 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
*: check in everything else yay
author Paper <paper@tflc.us>
date Mon, 05 Jan 2026 02:15:46 -0500
parents
children
comparison
equal deleted inserted replaced
0:e9bb126753e7 1:20d02a178406
1 #pragma once
2 #include "mem_block_container.h"
3
4
5 //! \since 1.1
6 //! metadb_index_manager hash, currently a 64bit int, typically made from halving MD5 hash.
7 typedef t_uint64 metadb_index_hash;
8
9
10 //! \since 1.1
11 //! A class that transforms track information (location+metadata) to a hash for metadb_index_manager. \n
12 //! You need to implement your own when using metadb_index_manager to pin your data to user's tracks. \n
13 //! Possible routes to take when implementing: \n
14 //! Rely on location only - pinning lost when user moves, but survives editing tags\n
15 //! Rely on metadata - pinning survives moving files, but lost when editing tags\n
16 //! If you do the latter, you can implement metadb_io_edit_callback to respond to tag edits and avoid data loss.
17 class NOVTABLE metadb_index_client : public service_base {
18 FB2K_MAKE_SERVICE_INTERFACE(metadb_index_client, service_base)
19 public:
20 virtual metadb_index_hash transform(const file_info& info, const playable_location& location) = 0;
21
22 bool hashHandle(metadb_handle_ptr const& h, metadb_index_hash& out) {
23 metadb_info_container::ptr info;
24 if (!h->get_info_ref(info)) return false;
25 out = transform(info->info(), h->get_location());
26 return true;
27 }
28
29 static metadb_index_hash from_md5(hasher_md5_result const& in) { return in.xorHalve(); }
30 };
31
32 //! \since 1.1
33 //! This service lets you pin your data to user's music library items, typically to be presented as title formatting %fields% via metadb_display_field_provider. \n
34 //! Implement metadb_index_client to define how your data gets pinned to the songs.
35 class NOVTABLE metadb_index_manager : public service_base {
36 FB2K_MAKE_SERVICE_COREAPI(metadb_index_manager)
37 public:
38 //! Install a metadb_index_client. \n
39 //! This is best done from init_stage_callback::on_init_stage(init_stages::before_config_read) to avoid hammering already loaded UI & playlists with refresh requests. \n
40 //! If you provide your own title formatting fields, call dispatch_global_refresh() after a successful add() to signal all components to refresh all tracks \n
41 //! - which is expensive, hence it should be done in early app init phase for minimal performance penalty. \n
42 //! Always put a try/catch around add() as it may fail with an exception in an unlikely scenario of corrupted files holding your previously saved data. \n
43 //! @param client your metadb_index_client object.
44 //! @param index_id Your GUID that you will pass to other methods when referring to your index.
45 //! @param userDataRetentionPeriod Time for which the data should be retained if no matching tracks are present. \n
46 //! If this was set to zero, the data could be lost immediately if a library folder disappers for some reason. \n
47 //! Hint: use system_time_periods::* constants, for an example, system_time_periods::week.
48 virtual void add(metadb_index_client::ptr client, const GUID& index_id, t_filetimestamp userDataRetentionPeriod) = 0;
49 //! Uninstalls a previously installed index.
50 virtual void remove(const GUID& index_id) = 0;
51 //! Sets your data for the specified index+hash.
52 virtual void set_user_data(const GUID& index_id, const metadb_index_hash& hash, const void* data, t_size dataSize) = 0;
53 //! Gets your data for the specified index+hash.
54 virtual void get_user_data(const GUID& index_id, const metadb_index_hash& hash, mem_block_container& out) = 0;
55
56
57 //! Helper
58 template<typename t_array> void get_user_data_t(const GUID& index_id, const metadb_index_hash& hash, t_array& out) {
59 mem_block_container_ref_impl<t_array> ref(out);
60 get_user_data(index_id, hash, ref);
61 }
62
63 //! Helper
64 t_size get_user_data_here(const GUID& index_id, const metadb_index_hash& hash, void* out, t_size outSize) {
65 mem_block_container_temp_impl ref(out, outSize);
66 get_user_data(index_id, hash, ref);
67 return ref.get_size();
68 }
69
70 //! Signals all components that your data for the tracks matching the specified hashes has been altered; this will redraw the affected tracks in playlists and such.
71 virtual void dispatch_refresh(const GUID& index_id, const pfc::list_base_const_t<metadb_index_hash>& hashes) = 0;
72
73 //! Helper
74 void dispatch_refresh(const GUID& index_id, const metadb_index_hash& hash) {
75 pfc::list_single_ref_t<metadb_index_hash> l(hash);
76 dispatch_refresh(index_id, l);
77 }
78
79 //! Dispatches a global refresh, asks all components to refresh all tracks. To be calling after adding/removing indexes. Expensive!
80 virtual void dispatch_global_refresh() = 0;
81
82 //! Efficiently retrieves metadb_handles of items present in the Media Library matching the specified index value. \n
83 //! This can be called from the app main thread only (interfaces with the library_manager API).
84 virtual void get_ML_handles(const GUID& index_id, const metadb_index_hash& hash, metadb_handle_list_ref out) = 0;
85
86 //! Retrieves all known hash values for this index.
87 virtual void get_all_hashes(const GUID& index_id, pfc::list_base_t<metadb_index_hash>& out) = 0;
88
89 //! Determines whether a no longer needed user data file for this index exists. \n
90 //! For use with index IDs that are not currently registered only.
91 virtual bool have_orphaned_data(const GUID& index_id) = 0;
92
93 //! Deletes no longer needed index user data files. \n
94 //! For use with index IDs that are not currently registered only.
95 virtual void erase_orphaned_data(const GUID& index_id) = 0;
96
97 //! Saves index user data file now. You normally don't need to call this; it's done automatically when saving foobar2000 configuration. \n
98 //! This will throw exceptions in case of a failure (out of disk space etc).
99 virtual void save_index_data(const GUID& index_id) = 0;
100 };
101
102 //! \since 2.0
103 //! Call this instead of metadb_index_manager::set_user_data() for many updates in a row
104 class NOVTABLE metadb_index_transaction : public service_base {
105 FB2K_MAKE_SERVICE_INTERFACE(metadb_index_transaction, service_base)
106 public:
107 virtual void set_user_data(const GUID& index_id, const metadb_index_hash& hash, const void* data, t_size dataSize) = 0;
108 virtual void commit() = 0;
109 };
110
111 //! \since 2.0
112 class NOVTABLE metadb_index_manager_v2 : public metadb_index_manager {
113 FB2K_MAKE_SERVICE_COREAPI_EXTENSION(metadb_index_manager_v2, metadb_index_manager)
114 public:
115 //! Call this instead of metadb_index_manager::set_user_data() for many updates in a row
116 virtual metadb_index_transaction::ptr begin_transaction() = 0;
117 };