|
1
|
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 };
|
