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