Mercurial > foo_out_sdl

comparison foosdk/sdk/foobar2000/SDK/autoplaylist.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 "playlist.h"
3 /*
4 Autoplaylist APIs
5 These APIs were introduced in foobar2000 0.9.5, to reduce amount of code required to create your own autoplaylists. Creation of autoplaylists is was also possible before through playlist lock APIs.
6 In most cases, you'll want to turn regular playlists into autoplaylists using the following code:
7 autoplaylist_manager::get()->add_client_simple(querypattern, sortpattern, playlistindex, forceSort ? autoplaylist_flag_sort : 0);
8 If you require more advanced functionality, such as using your own code to filter which part of user's Media Library should be placed in specific autoplaylist, you must implement autoplaylist_client (to let autoplaylist manager invoke your handlers when needed) / autoplaylist_client_factory (to re-instantiate your autoplaylist_client after a foobar2000 restart cycle).
9 */
10
11 enum {
12 //! When set, core will keep the autoplaylist sorted and prevent user from reordering it.
13 autoplaylist_flag_sort = 1 << 0,
14 };
15 //! Main class controlling autoplaylist behaviors. Implemented by autoplaylist client in scenarios where simple query/sort strings are not enough (core provides a standard implementation for simple queries).
16 class NOVTABLE autoplaylist_client : public service_base {
17 FB2K_MAKE_SERVICE_INTERFACE(autoplaylist_client,service_base)
18 public:
19 virtual GUID get_guid() = 0;
20 //! Provides a boolean mask of which items from the specified list should appear in this autoplaylist.
21 virtual void filter(metadb_handle_list_cref data, bool * out) = 0;
22 //! Return true when you have filled p_orderbuffer with a permutation to apply to p_items, false when you don't support sorting (core's own sort scheme will be applied).
23 virtual bool sort(metadb_handle_list_cref p_items,t_size * p_orderbuffer) = 0;
24 //! Retrieves your configuration data to be used later when re-instantiating your autoplaylist_client after a restart.
25 virtual void get_configuration(stream_writer * p_stream,abort_callback & p_abort) = 0;
26
27 virtual void show_ui(t_size p_source_playlist) = 0;
28
29 //! See: autoplaylist_client_v3::supports_async()
30 bool supports_async_();
31
32 //! See: autoplaylist_client_v3::supports_get_contents()
33 bool supports_get_contents_();
34
35 //! Helper.
36 template<typename t_array> void get_configuration(t_array & p_out) {
37 PFC_STATIC_ASSERT( sizeof(p_out[0]) == 1 );
38 typedef pfc::array_t<t_uint8,pfc::alloc_fast_aggressive> t_temp; t_temp temp;
39 {
40 stream_writer_buffer_append_ref_t<t_temp> writer(temp);
41 get_configuration(&writer,fb2k::noAbort);
42 }
43 p_out = temp;
44 }
45 };
46
47 typedef service_ptr_t<autoplaylist_client> autoplaylist_client_ptr;
48
49 //! \since 0.9.5.3
50 class NOVTABLE autoplaylist_client_v2 : public autoplaylist_client {
51 FB2K_MAKE_SERVICE_INTERFACE(autoplaylist_client_v2, autoplaylist_client);
52 public:
53 //! Sets a completion_notify object that the autoplaylist_client implementation should call when its filtering behaviors have changed so the whole playlist needs to be rebuilt. \n
54 //! completion_notify::on_completion() status parameter meaning: \n
55 //! 0.9.5.3 : ignored. \n
56 //! 0.9.5.4 and newer: set to 1 to indicate that your configuration has changed as well (for an example as a result of user edits) to get a get_configuration() call as well as cause the playlist to be rebuilt; set to zero otherwise - when the configuration hasn't changed but the playlist needs to be rebuilt as a result of some other event.
57 virtual void set_full_refresh_notify(completion_notify::ptr notify) = 0;
58
59 //! Returns whether the show_ui() method is available / does anything useful with our implementation (not everyone implements show_ui).
60 virtual bool show_ui_available() = 0;
61
62 //! Returns a human-readable autoplaylist implementer's label to display in playlist's context menu / description / etc.
63 virtual void get_display_name(pfc::string_base & out) = 0;
64 };
65
66 //! \since 2.0
67 class NOVTABLE autoplaylist_client_v3 : public autoplaylist_client_v2 {
68 FB2K_MAKE_SERVICE_INTERFACE(autoplaylist_client_v3, autoplaylist_client_v2);
69 public:
70 //! Returns true if this object supports off-main-thread filter() and sort().
71 virtual bool supports_async() = 0;
72
73 //! Provides a boolean mask of which items from the specified list should appear in this autoplaylist.
74 virtual void filter_v2(metadb_handle_list_cref items, metadb_io_callback_v2_data* dataIfAvailable, bool* out, abort_callback & abort) = 0;
75 //! Return true when you have filled p_orderbuffer with a permutation to apply to p_items, false when you don't support sorting (core's own sort scheme will be applied).
76 virtual bool sort_v2(metadb_handle_list_cref p_items, t_size* p_orderbuffer, abort_callback & abort) = 0;
77
78 virtual bool supports_get_contents() = 0;
79 virtual fb2k::arrayRef get_contents(abort_callback & a) = 0;
80
81 void filter(metadb_handle_list_cref data, bool * out) override;
82 bool sort(metadb_handle_list_cref p_items,t_size * p_orderbuffer) override;
83 };
84
85 //! Class needed to re-instantiate autoplaylist_client after a restart. Not directly needed to set up an autoplaylist_client, but without it, your autoplaylist will be lost after a restart.
86 class NOVTABLE autoplaylist_client_factory : public service_base {
87 FB2K_MAKE_SERVICE_INTERFACE_ENTRYPOINT(autoplaylist_client_factory)
88 public:
89 //! Must return same GUID as your autoplaylist_client::get_guid()
90 virtual GUID get_guid() = 0;
91 //! Instantiates your autoplaylist_client with specified configuration.
92 virtual autoplaylist_client_ptr instantiate(stream_reader * p_stream,t_size p_sizehint,abort_callback & p_abort) = 0;
93 };
94
95 PFC_DECLARE_EXCEPTION(exception_autoplaylist,pfc::exception,"Autoplaylist error")
96
97 PFC_DECLARE_EXCEPTION(exception_autoplaylist_already_owned,exception_autoplaylist,"This playlist is already an autoplaylist")
98 PFC_DECLARE_EXCEPTION(exception_autoplaylist_not_owned,exception_autoplaylist,"This playlist is not an autoplaylist")
99 PFC_DECLARE_EXCEPTION(exception_autoplaylist_lock_failure,exception_autoplaylist,"Playlist could not be locked")
100
101
102 //! Primary class for managing autoplaylists. Implemented by core, do not reimplement; instantiate using autoplaylist_manager::get().
103 class NOVTABLE autoplaylist_manager : public service_base {
104 FB2K_MAKE_SERVICE_COREAPI(autoplaylist_manager)
105 public:
106 //! Throws exception_autoplaylist or one of its subclasses on failure.
107 //! @param p_flags See autoplaylist_flag_* constants.
108 virtual void add_client(autoplaylist_client_ptr p_client,t_size p_playlist,t_uint32 p_flags) = 0;
109 virtual bool is_client_present(t_size p_playlist) = 0;
110 //! Throws exception_autoplaylist or one of its subclasses on failure (eg. not an autoplaylist).
111 virtual autoplaylist_client_ptr query_client(t_size p_playlist) = 0;
112 virtual void remove_client(t_size p_playlist) = 0;
113 //! Helper; sets up an autoplaylist using standard autoplaylist_client implementation based on simple query/sort strings. When using this, you don't need to maintain own autoplaylist_client/autoplaylist_client_factory implementations, and autoplaylists that you create will not be lost when your DLL is removed, as opposed to using add_client() directly.
114 //! Throws exception_autoplaylist or one of its subclasses on failure.
115 //! @param p_flags See autoplaylist_flag_* constants.
116 virtual void add_client_simple(const char * p_query,const char * p_sort,t_size p_playlist,t_uint32 p_flags) = 0;
117 };
118
119 //! \since 0.9.5.4
120 //! Extended version of autoplaylist_manager, available from 0.9.5.4 up, with methods allowing modification of autoplaylist flags.
121 class NOVTABLE autoplaylist_manager_v2 : public autoplaylist_manager {
122 FB2K_MAKE_SERVICE_COREAPI_EXTENSION(autoplaylist_manager_v2, autoplaylist_manager)
123 public:
124 virtual t_uint32 get_client_flags(t_size playlist) = 0;
125 virtual void set_client_flags(t_size playlist, t_uint32 newFlags) = 0;
126
127 //! For use with autoplaylist client configuration dialogs. It's recommended not to call this from anything else.
128 virtual t_uint32 get_client_flags(autoplaylist_client::ptr client) = 0;
129 //! For use with autoplaylist client configuration dialogs. It's recommended not to call this from anything else.
130 virtual void set_client_flags(autoplaylist_client::ptr client, t_uint32 newFlags) = 0;
131 };