VLC  4.0.0-dev
vlc_playlist_legacy.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * vlc_playlist_legacy.h : Legacy playlist functions
3  *****************************************************************************
4  * Copyright (C) 1999-2004 VLC authors and VideoLAN
5  *
6  * Authors: Samuel Hocevar <sam@zoy.org>
7  *
8  * This program is free software; you can redistribute it and/or modify it
9  * under the terms of the GNU Lesser General Public License as published by
10  * the Free Software Foundation; either version 2.1 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  * GNU Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public License
19  * along with this program; if not, write to the Free Software Foundation,
20  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21  *****************************************************************************/
22 
23 #ifndef VLC_PLAYLIST_LEGACY_H_
24 #define VLC_PLAYLIST_LEGACY_H_
25 
26 # ifdef __cplusplus
27 extern "C" {
28 # endif
29 
30 #include <vlc_events.h>
31 
33 
34 struct intf_thread_t;
35 
36 /**
37  * \defgroup playlist_legacy VLC playlist legacy
38  * \ingroup interface
39  * VLC playlist controls
40  * @{
41  * \file
42  * VLC playlist control interface
43  *
44  * The VLC playlist system has a tree structure. This allows advanced
45  * categorization, like for SAP streams (which are grouped by "sap groups").
46  *
47  * The base structure for all playlist operations is the playlist_item_t.
48  * This is essentially a node within the playlist tree. Each playlist item
49  * references an input_item_t which contains the input stream info, such as
50  * location, name and meta-data.
51  *
52  * A playlist item is uniquely identified by its input item:
53  * \ref playlist_ItemGetByInput(). A single input item cannot be used by more
54  * than one playlist item at a time; if necessary, a copy of the input item can
55  * be made instead.
56  *
57  * The same playlist tree is visible to all user interfaces. To arbitrate
58  * access, a lock is used, see \ref playlist_Lock() and \ref playlist_Unlock().
59  *
60  * Under the playlist root item node, the top-level items are the main
61  * media sources and include:
62  * - the actual playlist,
63  * - the service discovery root node, whose children are services discovery
64  * module instances.
65  *
66  * So, here is an example:
67  * \verbatim
68  * Inputs array
69  * - input 1 -> name = foo 1 uri = ...
70  * - input 2 -> name = foo 2 uri = ...
71  *
72  * Playlist items tree
73  * - playlist (id 1)
74  * - category 1 (id 2)
75  * - foo 2 (id 6 - input 2)
76  * \endverbatim
77  *
78  * Sometimes, an item creates subitems. This happens for the directory access
79  * for example. In that case, if the item is under the "playlist" top-level
80  * item and playlist is configured to be flat then the item will be deleted and
81  * replaced with new subitems. If the item is under another top-level item, it
82  * will be transformed to a node and removed from the list of all items without
83  * nodes.
84  *
85  * For "standard" item addition, you can use playlist_Add(), playlist_AddExt()
86  * (more options) or playlist_AddInput() if you already created your input
87  * item. This will add the item at the root of "Playlist" in each of the two trees.
88  *
89  * You can create nodes with playlist_NodeCreate() and can create items from
90  * existing input items to be placed under any node with
91  * playlist_NodeAddInput().
92  *
93  * To delete an item, use playlist_NodeDelete( p_item ).
94  *
95  * The playlist defines the following event variables:
96  *
97  * - "item-change": It will contain a pointer to the input_item_t of a
98  * changed input item monitored by the playlist.
99  *
100  * - "playlist-item-append": It will contain a pointer to a playlist_item_t.
101  * - "playlist-item-deleted": It will contain a pointer to the playlist_item_t
102  * about to be deleted.
103  *
104  * - "leaf-to-parent": It will contain the playlist_item_t->i_id of an item that is transformed
105  * into a node.
106  *
107  * The playlist contains rate-variable which is propagated to current input if
108  * available also rate-slower/rate-faster is in use.
109  */
110 
111 /** Helper structure to export to file part of the playlist */
112 typedef struct playlist_export_t
113 {
114  struct vlc_object_t obj;
115  char *base_url;
116  FILE *p_file;
119 
120 /** playlist item / node */
121 struct playlist_item_t
122 {
123  input_item_t *p_input; /**< Linked input item */
125  playlist_item_t **pp_children; /**< Children nodes/items */
126  playlist_item_t *p_parent; /**< Item parent */
127  int i_children; /**< Number of children, -1 if not a node */
128  unsigned i_nb_played; /**< Times played */
130  int i_id; /**< Playlist item specific id */
131  uint8_t i_flags; /**< Flags \see playlist_item_flags_e */
132 };
133 
134 typedef enum {
135  PLAYLIST_DBL_FLAG = 0x04, /**< Is it disabled ? */
136  PLAYLIST_RO_FLAG = 0x08, /**< Write-enabled ? */
137  PLAYLIST_SUBITEM_STOP_FLAG = 0x40, /**< Must playlist stop if the item gets subitems ?*/
138  PLAYLIST_NO_INHERIT_FLAG = 0x80, /**< Will children inherit flags the R/O flag ? */
140 
141 /** Playlist status */
142 typedef enum
145 /** Structure containing information about the playlist */
146 struct playlist_t
147 {
148  struct vlc_object_t obj;
150  playlist_item_array_t items; /**< Arrays of items */
152  playlist_item_array_t current; /**< Items currently being played */
153  int i_current_index; /**< Index in current array */
155  /* Predefined items */
156  playlist_item_t root;
157  playlist_item_t *p_playing;
158 };
159 
160 /* A bit of macro magic to generate an enum out of the following list,
161  * and later, to generate a list of static functions out of the same list.
162  * There is also SORT_RANDOM, which is always last and handled specially.
163  */
164 #define VLC_DEFINE_SORT_FUNCTIONS \
165  DEF( SORT_ID )\
166  DEF( SORT_TITLE )\
167  DEF( SORT_TITLE_NODES_FIRST )\
168  DEF( SORT_ARTIST )\
169  DEF( SORT_GENRE )\
170  DEF( SORT_DURATION )\
171  DEF( SORT_TITLE_NUMERIC )\
172  DEF( SORT_ALBUM )\
173  DEF( SORT_TRACK_NUMBER )\
174  DEF( SORT_DESCRIPTION )\
175  DEF( SORT_RATING )\
176  DEF( SORT_URI )\
177  DEF( SORT_DISC_NUMBER )\
178  DEF( SORT_DATE )
179 
180 #define DEF( s ) s,
181 enum
182 {
186 };
187 #undef DEF
188 #ifndef VLC_INTERNAL_PLAYLIST_SORT_FUNCTIONS
189 #undef VLC_DEFINE_SORT_FUNCTIONS
190 #endif
191 
192 enum
193 {
194  ORDER_NORMAL = 0,
196 };
197 
198 #define PLAYLIST_END -1
200 enum pl_locked_state
201 {
202  pl_Locked = true,
203  pl_Unlocked = false
204 };
205 
206 /*****************************************************************************
207  * Prototypes
208  *****************************************************************************/
209 
210 /* Helpers */
211 #define PL_LOCK playlist_Lock( p_playlist )
212 #define PL_UNLOCK playlist_Unlock( p_playlist )
213 #define PL_ASSERT_LOCKED assert(playlist_Locked(p_playlist))
215 /** Playlist commands */
216 enum {
217  PLAYLIST_PLAY, /**< No arg. res=can fail*/
218  PLAYLIST_VIEWPLAY, /**< arg1= playlist_item_t*,*/
219  /** arg2 = playlist_item_t* , res=can fail */
220  PLAYLIST_TOGGLE_PAUSE, /**< No arg res=can fail */
221  PLAYLIST_STOP, /**< No arg res=can fail*/
222  PLAYLIST_SKIP, /**< arg1=int, res=can fail*/
223  PLAYLIST_PAUSE, /**< No arg */
224  PLAYLIST_RESUME, /**< No arg */
225 };
226 
227 #define playlist_Play(p) playlist_Control(p,PLAYLIST_PLAY, pl_Unlocked )
228 #define playlist_TogglePause(p) \
229  playlist_Control(p, PLAYLIST_TOGGLE_PAUSE, pl_Unlocked)
230 #define playlist_Stop(p) playlist_Control(p,PLAYLIST_STOP, pl_Unlocked )
231 #define playlist_Next(p) playlist_Control(p,PLAYLIST_SKIP, pl_Unlocked, 1)
232 #define playlist_Prev(p) playlist_Control(p,PLAYLIST_SKIP, pl_Unlocked, -1)
233 #define playlist_Skip(p,i) playlist_Control(p,PLAYLIST_SKIP, pl_Unlocked, (i) )
234 #define playlist_Pause(p) \
235  playlist_Control(p, PLAYLIST_PAUSE, pl_Unlocked)
236 #define playlist_Resume(p) \
237  playlist_Control(p, PLAYLIST_RESUME, pl_Unlocked)
238 
239 /**
240  * Locks the playlist.
241  *
242  * This function locks the playlist. While the playlist is locked, no other
243  * thread can modify the playlist tree layout or current playing item and node.
244  *
245  * Locking the playlist is necessary before accessing, either for reading or
246  * writing, any playlist item.
247  *
248  * \note Because of the potential for lock inversion / deadlocks, locking the
249  * playlist shall not be attemped while holding an input item lock. An input
250  * item lock can be acquired while holding the playlist lock.
251  *
252  * While holding the playlist lock, a thread shall not attempt to:
253  * - probe, initialize or deinitialize a module or a plugin,
254  * - install or deinstall a variable or event callback,
255  * - set a variable or trigger a variable callback, with the sole exception
256  * of the playlist core triggering add/remove/leaf item callbacks,
257  * - invoke a module/plugin callback other than:
258  * - playlist export,
259  * - logger message callback.
260  */
262 
263 /**
264  * Unlocks the playlist.
265  *
266  * This function unlocks the playlist, allowing other threads to lock it. The
267  * calling thread must have called playlist_Lock() before.
268  *
269  * This function invalidates all or any playlist item pointers.
270  * There are no ways to ensure that playlist items are not modified or deleted
271  * by another thread past this function call.
272  *
273  * To retain a reference to a playlist item while not holding the playlist
274  * lock, a thread should take a reference to the input item within the
275  * playlist item before unlocking. If this is not practical, then the thread
276  * can store the playlist item ID (i_id) before unlocking.
277  * Either way, this will not ensure that the playlist item is not deleted, so
278  * the thread must be ready to handle that case later when calling
279  * playlist_ItemGetByInput() or playlist_ItemGetById().
280  *
281  * Furthermore, if ID is used, then the playlist item might be deleted, and
282  * another item could be assigned the same ID. To avoid that problem, use
283  * the input item instead of the ID.
284  */
286 
287 VLC_API bool playlist_Locked( const playlist_t * );
288 #define playlist_AssertLocked(pl) (assert(playlist_Locked(pl)), pl)
291 
292 /**
293  * Do a playlist action.
294  * If there is something in the playlist then you can do playlist actions.
295  * Possible queries are listed in vlc_common.h
296  * \param p_playlist the playlist to do the command on
297  * \param i_query the command to do
298  * \param b_locked TRUE if playlist is locked when entering this function
299  * \param variable number of arguments
300  */
301 VLC_API void playlist_Control( playlist_t *p_playlist, int i_query, int b_locked, ... );
302 
303 static inline void playlist_ViewPlay(playlist_t *pl, playlist_item_t *node,
305 {
306  playlist_Control(pl, PLAYLIST_VIEWPLAY, pl_Locked, node, item);
307 }
308 
309 /** Get current playing input. The object is retained.
310  */
313 
314 /** Get the duration of all items in a node.
315  */
317 
318 /** Clear the playlist
319  * \param b_locked TRUE if playlist is locked when entering this function
320  */
321 VLC_API void playlist_Clear( playlist_t *, bool );
322 
323 /* Playlist sorting */
327 
330 
331 /**
332  * Export a node of the playlist to a certain type of playlistfile
333  * \param psz_filename the location where the exported file will be saved
334  * \param psz_type the type of playlist file to create (m3u, pls, ..)
335  * \return VLC_SUCCESS on success
336  */
337 VLC_API int playlist_Export( playlist_t *p_playlist, const char *psz_name,
338  const char *psz_type );
339 
340 /**
341  * Open a playlist file, add its content to the current playlist
342  */
343 VLC_API int playlist_Import( playlist_t *p_playlist, const char *psz_file );
344 
345 /********************** Services discovery ***********************/
346 
347 /** Add a service discovery module */
349 /** Remove a services discovery module by name */
351 /** Check whether a given SD is loaded */
353 /** Query a services discovery */
354 VLC_API int playlist_ServicesDiscoveryControl( playlist_t *, const char *, int, ... );
355 
356 /********************** Renderer ***********************/
357 /**
358  * Sets a renderer or remove the current one
359  * @param p_item The renderer item to be used, or NULL to disable the current
360  * one. If a renderer is provided, its reference count will be
361  * incremented.
362  */
364 
365 
366 /********************************************************
367  * Item management
368  ********************************************************/
369 
370 /******************** Item addition ********************/
371 VLC_API int playlist_Add( playlist_t *, const char *, bool );
372 VLC_API int playlist_AddExt( playlist_t *, const char *, const char *, bool, int, const char *const *, unsigned );
376 
377 /********************************** Item search *************************/
380  const input_item_t * )
381 VLC_USED;
382 
383 VLC_API int playlist_LiveSearchUpdate(playlist_t *, playlist_item_t *, const char *, bool );
384 
385 /********************************************************
386  * Tree management
387  ********************************************************/
388 /* Node management */
392 
393 /**************************
394  * Audio output management
395  **************************/
396 
398 
400 VLC_API int playlist_VolumeSet( playlist_t *, float );
401 VLC_API int playlist_VolumeUp( playlist_t *, int, float * );
402 #define playlist_VolumeDown(a, b, c) playlist_VolumeUp(a, -(b), c)
405 
406 static inline int playlist_MuteToggle( playlist_t *pl )
407 {
408  int val = playlist_MuteGet( pl );
409  if (val >= 0)
410  val = playlist_MuteSet( pl, !val );
411  return val;
412 }
413 
414 VLC_API void playlist_EnableAudioFilter( playlist_t *, const char *, bool );
415 
416 /** Tell if the playlist is empty */
417 #define playlist_IsEmpty(p_playlist) \
418  (playlist_AssertLocked(p_playlist)->items.i_size == 0)
419 
420 /** Tell the number of items in the current playing context */
421 #define playlist_CurrentSize(p_playlist) \
422  (playlist_AssertLocked(p_playlist)->current.i_size)
423 
424 /** @} */
425 # ifdef __cplusplus
426 }
427 # endif
428 
429 #endif
arg1=int, res=can fail
Definition: vlc_playlist_legacy.h:223
int playlist_LiveSearchUpdate(playlist_t *, playlist_item_t *, const char *, bool)
Launch the recursive search in the playlist.
Definition: search.c:118
int playlist_VolumeSet(playlist_t *, float)
Definition: aout.c:59
Must playlist stop if the item gets subitems ?
Definition: vlc_playlist_legacy.h:138
playlist_status_t
Playlist status.
Definition: vlc_playlist_legacy.h:143
int playlist_TreeMove(playlist_t *, playlist_item_t *, playlist_item_t *, int)
Moves an item.
Definition: item.c:631
int playlist_AddInput(playlist_t *, input_item_t *, bool)
Add an input item to the playlist node.
Definition: item.c:496
int playlist_MuteGet(playlist_t *)
Definition: aout.c:90
Describes an input and is used to spawn input_thread_t objects.
Definition: vlc_input_item.h:77
playlist_item_flags_e
Definition: vlc_playlist_legacy.h:135
int playlist_AddExt(playlist_t *, const char *, const char *, bool, int, const char *const *, unsigned)
Add a MRL into the playlist or the media library, duration and options given.
Definition: item.c:473
int playlist_ServicesDiscoveryAdd(playlist_t *, const char *)
Add a service discovery module.
Definition: services_discovery.c:118
No arg.
Definition: vlc_playlist_legacy.h:218
Definition: vlc_playlist_legacy.h:196
uint8_t i_flags
Flags.
Definition: vlc_playlist_legacy.h:132
Definition: vlc_playlist_legacy.h:203
#define VLC_DEPRECATED
Deprecated functions or compound members annotation.
Definition: vlc_common.h:119
int playlist_VolumeUp(playlist_t *, int, float *)
Raises the volume.
Definition: aout.c:77
int i_children
Number of children, -1 if not a node.
Definition: vlc_playlist_legacy.h:128
Definition: vlc_playlist_legacy.h:204
Helper structure to export to file part of the playlist.
Definition: vlc_playlist_legacy.h:113
input_item_t * p_input
Linked input item.
Definition: vlc_playlist_legacy.h:124
playlist_item_t * playlist_CurrentPlayingItem(playlist_t *)
Definition: engine.c:482
int playlist_RecursiveNodeSort(playlist_t *, playlist_item_t *, int, int)
Sort a node recursively.
Definition: sort.c:191
Will children inherit flags the R/O flag ?
Definition: vlc_playlist_legacy.h:139
Definition: renderer_discovery.c:34
void playlist_EnableAudioFilter(playlist_t *, const char *, bool)
Definition: aout.c:116
Definition: vlc_playlist_legacy.h:144
playlist_item_t * p_parent
Item parent.
Definition: vlc_playlist_legacy.h:127
bool playlist_Locked(const playlist_t *)
Definition: control.c:46
int64_t vlc_tick_t
High precision date or time interval.
Definition: vlc_tick.h:45
static int playlist_MuteToggle(playlist_t *pl)
Definition: vlc_playlist_legacy.h:407
playlist_item_t * playlist_ItemGetById(playlist_t *, int)
Finds a playlist item by ID.
Definition: item.c:389
Definition: vlc_playlist_legacy.h:144
float playlist_VolumeGet(playlist_t *)
Definition: aout.c:46
playlist_item_t * playlist_NodeAddInput(playlist_t *, input_item_t *, playlist_item_t *, int)
Add an input item to a given node.
Definition: item.c:521
playlist item / node
Definition: vlc_playlist_legacy.h:122
int playlist_TreeMoveMany(playlist_t *, int, playlist_item_t **, playlist_item_t *, int)
Moves an array of items.
Definition: item.c:666
int playlist_ServicesDiscoveryRemove(playlist_t *, const char *)
Remove a services discovery module by name.
Definition: services_discovery.c:171
vlc_tick_t playlist_GetNodeDuration(playlist_item_t *)
Get the duration of all items in a node.
Definition: item.c:716
No arg.
Definition: vlc_playlist_legacy.h:224
int playlist_Status(playlist_t *)
Definition: engine.c:489
int i_id
Playlist item specific id.
Definition: vlc_playlist_legacy.h:131
input_thread_t * playlist_CurrentInput(playlist_t *p_playlist)
Get current playing input.
Definition: engine.c:363
struct audio_output * playlist_GetAout(playlist_t *)
Definition: aout.c:36
pl_locked_state
Definition: vlc_playlist_legacy.h:201
playlist_item_t * playlist_ItemGetByInput(playlist_t *, const input_item_t *)
Finds a playlist item by input item.
Definition: item.c:412
Describe all interface-specific data of the interface thread.
Definition: vlc_interface.h:48
Definition: vlc_playlist_legacy.h:195
int playlist_Add(playlist_t *, const char *, bool)
Playlist add.
Definition: item.c:455
#define TYPEDEF_ARRAY(type, name)
Definition: vlc_arrays.h:187
No arg.
Definition: vlc_playlist_legacy.h:225
void playlist_NodeDelete(playlist_t *, playlist_item_t *)
Remove all the children of a node and removes the node.
Definition: tree.c:91
static void playlist_ViewPlay(playlist_t *pl, playlist_item_t *node, playlist_item_t *item)
Definition: vlc_playlist_legacy.h:304
int playlist_ServicesDiscoveryControl(playlist_t *, const char *, int,...)
Query a services discovery.
Definition: services_discovery.c:214
#define VLC_API
Definition: fourcc_gen.c:31
Audio output object.
Definition: vlc_aout.h:139
int playlist_SetRenderer(playlist_t *p_pl, vlc_renderer_item_t *p_item)
Sets a renderer or remove the current one.
Definition: renderer.c:33
Main structure representing an input thread.
Definition: vlc_input.h:226
Definition: vlc_playlist_legacy.h:33
const char * psz_name
Definition: vlc_codecs.h:313
Definition: vlc_playlist_legacy.h:185
#define VLC_DEFINE_SORT_FUNCTIONS
Definition: vlc_playlist_legacy.h:165
int playlist_NodeAddCopy(playlist_t *, playlist_item_t *, playlist_item_t *, int)
Copy an item (and all its children, if any) into another node.
Definition: item.c:555
unsigned i_nb_played
Times played.
Definition: vlc_playlist_legacy.h:129
void playlist_Lock(playlist_t *)
Locks the playlist.
Definition: control.c:36
arg2 = playlist_item_t* , res=can fail
Definition: vlc_playlist_legacy.h:221
playlist_item_t * playlist_ChildSearchName(playlist_item_t *, const char *)
Search a child of a node by its name.
Definition: tree.c:176
Definition: vlc_playlist_legacy.h:144
No arg res=can fail.
Definition: vlc_playlist_legacy.h:222
arg1= playlist_item_t*,
Definition: vlc_playlist_legacy.h:219
Write-enabled ?
Definition: vlc_playlist_legacy.h:137
input_thread_t * playlist_CurrentInputLocked(playlist_t *p_playlist)
Get current playing input.
Definition: engine.c:350
Definition: vlc_playlist_legacy.h:186
int playlist_MuteSet(playlist_t *, bool)
Definition: aout.c:103
bool playlist_IsServicesDiscoveryLoaded(playlist_t *, const char *)
Check whether a given SD is loaded.
Definition: services_discovery.c:196
Is it disabled ?
Definition: vlc_playlist_legacy.h:136
int playlist_Export(playlist_t *p_playlist, const char *psz_name, const char *psz_type)
Export a node of the playlist to a certain type of playlistfile.
Definition: loadsave.c:40
void playlist_Control(playlist_t *p_playlist, int i_query, int b_locked,...)
Do a playlist action.
Definition: control.c:140
VLC object common members.
Definition: vlc_objects.h:43
int playlist_Import(playlist_t *p_playlist, const char *psz_file)
Open a playlist file, add its content to the current playlist.
Definition: loadsave.c:47
struct playlist_export_t playlist_export_t
Helper structure to export to file part of the playlist.
void playlist_Clear(playlist_t *, bool)
Clear the playlist.
Definition: item.c:431
playlist_item_t ** pp_children
Children nodes/items.
Definition: vlc_playlist_legacy.h:126
#define VLC_USED
Definition: fourcc_gen.c:32
playlist_item_t * playlist_NodeCreate(playlist_t *, const char *, playlist_item_t *p_parent, int i_pos, int i_flags)
Create a playlist node.
Definition: tree.c:57
void playlist_Deactivate(playlist_t *)
Stops the playlist forever (but do not destroy it yet).
Definition: thread.c:68
Structure containing information about the playlist.
Definition: vlc_playlist_legacy.h:147
void playlist_Unlock(playlist_t *)
Unlocks the playlist.
Definition: control.c:41
This file is the interface definition for events (implementation in src/misc/events.c)