include/vlc/libvlc_media_list_player.h

   1 /*****************************************************************************
   2  * libvlc_media_list_player.h:  libvlc_media_list API
   3  *****************************************************************************
   4  * Copyright (C) 1998-2008 VLC authors and VideoLAN
   5  * $Id$
   6  *
   7  * Authors: Pierre d'Herbemont
   8  *
   9  * This program is free software; you can redistribute it and/or modify it
  10  * under the terms of the GNU Lesser General Public License as published by
  11  * the Free Software Foundation; either version 2.1 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with this program; if not, write to the Free Software Foundation,
  21  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  22  *****************************************************************************/
  23
  24 #ifndef LIBVLC_MEDIA_LIST_PLAYER_H
  25 #define LIBVLC_MEDIA_LIST_PLAYER_H 1
  26
  27 # ifdef __cplusplus
  28 extern "C" {
  29 # endif
  30
  31 /** \defgroup libvlc_media_list_player LibVLC media list player
  32  * \ingroup libvlc
  33  * The LibVLC media list player plays a @ref libvlc_media_list_t list of media,
  34  * in a certain order.
  35  * This is required to especially support playlist files.
  36  * The normal @ref libvlc_media_player_t LibVLC media player can only play a
  37  * single media, and does not handle playlist files properly.
  38  * @{
  39  * \file
  40  * LibVLC media list player external API
  41  */
  42
  43 typedef struct libvlc_media_list_player_t libvlc_media_list_player_t;
  44
  45 /**
  46  *  Defines playback modes for playlist.
  47  */
  48 typedef enum libvlc_playback_mode_t
  49 {
  50     libvlc_playback_mode_default,
  51     libvlc_playback_mode_loop,
  52     libvlc_playback_mode_repeat
  53 } libvlc_playback_mode_t;
  54
  55 /**
  56  * Create new media_list_player.
  57  *
  58  * \param p_instance libvlc instance
  59  * \return media list player instance or NULL on error
  60  */
  61 LIBVLC_API libvlc_media_list_player_t *
  62     libvlc_media_list_player_new( libvlc_instance_t * p_instance );
  63
  64 /**
  65  * Release a media_list_player after use
  66  * Decrement the reference count of a media player object. If the
  67  * reference count is 0, then libvlc_media_list_player_release() will
  68  * release the media player object. If the media player object
  69  * has been released, then it should not be used again.
  70  *
  71  * \param p_mlp media list player instance
  72  */
  73 LIBVLC_API void
  74     libvlc_media_list_player_release( libvlc_media_list_player_t * p_mlp );
  75
  76 /**
  77  * Retain a reference to a media player list object. Use
  78  * libvlc_media_list_player_release() to decrement reference count.
  79  *
  80  * \param p_mlp media player list object
  81  */
  82 LIBVLC_API void
  83     libvlc_media_list_player_retain( libvlc_media_list_player_t *p_mlp );
  84
  85 /**
  86  * Return the event manager of this media_list_player.
  87  *
  88  * \param p_mlp media list player instance
  89  * \return the event manager
  90  */
  91 LIBVLC_API libvlc_event_manager_t *
  92     libvlc_media_list_player_event_manager(libvlc_media_list_player_t * p_mlp);
  93
  94 /**
  95  * Replace media player in media_list_player with this instance.
  96  *
  97  * \param p_mlp media list player instance
  98  * \param p_mi media player instance
  99  */
 100 LIBVLC_API void
 101     libvlc_media_list_player_set_media_player(
 102                                      libvlc_media_list_player_t * p_mlp,
 103                                      libvlc_media_player_t * p_mi );
 104
 105 /**
 106  * Get media player of the media_list_player instance.
 107  *
 108  * \param p_mlp media list player instance
 109  * \return media player instance
 110  * \note the caller is responsible for releasing the returned instance
 111  */
 112 LIBVLC_API libvlc_media_player_t *
 113     libvlc_media_list_player_get_media_player(libvlc_media_list_player_t * p_mlp);
 114
 115 /**
 116  * Set the media list associated with the player
 117  *
 118  * \param p_mlp media list player instance
 119  * \param p_mlist list of media
 120  */
 121 LIBVLC_API void
 122     libvlc_media_list_player_set_media_list(
 123                                      libvlc_media_list_player_t * p_mlp,
 124                                      libvlc_media_list_t * p_mlist );
 125
 126 /**
 127  * Play media list
 128  *
 129  * \param p_mlp media list player instance
 130  */
 131 LIBVLC_API
 132 void libvlc_media_list_player_play(libvlc_media_list_player_t * p_mlp);
 133
 134 /**
 135  * Toggle pause (or resume) media list
 136  *
 137  * \param p_mlp media list player instance
 138  */
 139 LIBVLC_API
 140 void libvlc_media_list_player_pause(libvlc_media_list_player_t * p_mlp);
 141
 142 /**
 143  * Is media list playing?
 144  *
 145  * \param p_mlp media list player instance
 146  * \return true for playing and false for not playing
 147  *
 148  * \libvlc_return_bool
 149  */
 150 LIBVLC_API int
 151     libvlc_media_list_player_is_playing( libvlc_media_list_player_t * p_mlp );
 152
 153 /**
 154  * Get current libvlc_state of media list player
 155  *
 156  * \param p_mlp media list player instance
 157  * \return libvlc_state_t for media list player
 158  */
 159 LIBVLC_API libvlc_state_t
 160     libvlc_media_list_player_get_state( libvlc_media_list_player_t * p_mlp );
 161
 162 /**
 163  * Play media list item at position index
 164  *
 165  * \param p_mlp media list player instance
 166  * \param i_index index in media list to play
 167  * \return 0 upon success -1 if the item wasn't found
 168  */
 169 LIBVLC_API
 170 int libvlc_media_list_player_play_item_at_index(libvlc_media_list_player_t * p_mlp,
 171                                                 int i_index);
 172
 173 /**
 174  * Play the given media item
 175  *
 176  * \param p_mlp media list player instance
 177  * \param p_md the media instance
 178  * \return 0 upon success, -1 if the media is not part of the media list
 179  */
 180 LIBVLC_API
 181 int libvlc_media_list_player_play_item(libvlc_media_list_player_t * p_mlp,
 182                                        libvlc_media_t * p_md);
 183
 184 /**
 185  * Stop playing media list
 186  *
 187  * \param p_mlp media list player instance
 188  */
 189 LIBVLC_API void
 190     libvlc_media_list_player_stop( libvlc_media_list_player_t * p_mlp);
 191
 192 /**
 193  * Play next item from media list
 194  *
 195  * \param p_mlp media list player instance
 196  * \return 0 upon success -1 if there is no next item
 197  */
 198 LIBVLC_API
 199 int libvlc_media_list_player_next(libvlc_media_list_player_t * p_mlp);
 200
 201 /**
 202  * Play previous item from media list
 203  *
 204  * \param p_mlp media list player instance
 205  * \return 0 upon success -1 if there is no previous item
 206  */
 207 LIBVLC_API
 208 int libvlc_media_list_player_previous(libvlc_media_list_player_t * p_mlp);
 209
 210
 211
 212 /**
 213  * Sets the playback mode for the playlist
 214  *
 215  * \param p_mlp media list player instance
 216  * \param e_mode playback mode specification
 217  */
 218 LIBVLC_API
 219 void libvlc_media_list_player_set_playback_mode(libvlc_media_list_player_t * p_mlp,
 220                                                 libvlc_playback_mode_t e_mode );
 221
 222 /** @} media_list_player */
 223
 224 # ifdef __cplusplus
 225 }
 226 # endif
 227
 228 #endif /* LIBVLC_MEDIA_LIST_PLAYER_H */