1 /*	$Id: playlist.h 15788 2009-03-17 18:20:58Z moritz $	*/
2 /*
3  * Copyright (c) 2007 Moritz Grimm <mdgrimm@gmx.net>
4  *
5  * Permission to use, copy, modify, and distribute this software for any
6  * purpose with or without fee is hereby granted, provided that the above
7  * copyright notice and this permission notice appear in all copies.
8  *
9  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16  */
17 
18 #ifndef __PLAYLIST_H__
19 #define __PLAYLIST_H__
20 
21 typedef struct playlist playlist_t;
22 
23 /*
24  * Initialize the playlist routines. Should be called before any of the other
25  * playlist functions.
26  */
27 void		playlist_init(void);
28 
29 /*
30  * Clean up for clean shutdowns. No-op at the moment.
31  */
32 void		playlist_shutdown(void);
33 
34 /*
35  * Read a playlist file (in .M3U format), and return a new playlist handler
36  * on success, or NULL on failure.
37  */
38 playlist_t *	playlist_read(const char * /* filename */);
39 
40 /*
41  * For each call to playlist_get_next(), the specified program is run. This
42  * program is supposed to print one line to standard output, containing the
43  * path and filename of a media file.
44  */
45 playlist_t *	playlist_program(const char * /* program name */);
46 
47 /*
48  * Free all memory used by a playlist handler that was created with
49  * playlist_read().
50  */
51 void		playlist_free(playlist_t **);
52 
53 /*
54  * Get the next item in the playlist. Returns a NUL-terminated string of a
55  * playlist entry, or NULL if the end of the list has been reached.
56  */
57 const char *	playlist_get_next(playlist_t *);
58 
59 /*
60  * The functions below work on playlist handlers obtained with playlist_read()
61  * and are no-ops (i.e. return failure) for playlists from playlist_program().
62  */
63 
64 /*
65  * Get the next item in the playlist without moving on to the following entry.
66  * Returns a NUL-terminated string of the next playlist entry, or NULL if the
67  * currently playing song is the last one in the list.
68  */
69 const char *	playlist_peek_next(playlist_t *);
70 
71 /*
72  * Skip the playlist item that would be played next.
73  */
74 void		playlist_skip_next(playlist_t *);
75 
76 /*
77  * Get the number of items in the playlist.
78  */
79 unsigned long	playlist_get_num_items(playlist_t *);
80 
81 /*
82  * Get the current position in the playlist.
83  */
84 unsigned long	playlist_get_position(playlist_t *);
85 
86 /*
87  * Set a position in the playlist. Returns 1 on success, and 0 on failure.
88  */
89 int		playlist_set_position(playlist_t *, unsigned long /* index */);
90 
91 /*
92  * Search for a given entry in the playlist and reposition to it. Returns 1 on
93  * success and 0 on failure. A subsequent call to playlist_get_next() will
94  * return this list item again.
95  */
96 int		playlist_goto_entry(playlist_t *, const char * /* name */);
97 
98 /*
99  * Rewind the playlist to the beginning, so that it can be replayed. Does
100  * not reread the playlist file.
101  */
102 void		playlist_rewind(playlist_t *);
103 
104 /*
105  * Reread the playlist file and rewind to the beginning. Equivalent to calling
106  * playlist_free() and playlist_read(). Entries will no longer be shuffled
107  * after calling this function.
108  * Returns 1 on success, and 0 on error.
109  */
110 int		playlist_reread(playlist_t **);
111 
112 /*
113  * Shuffle the entries of the playlist randomly.
114  */
115 void		playlist_shuffle(playlist_t *);
116 
117 #endif /* __PLAYLIST_H__ */
118