git.sesse.net Git - vlc/blob - include/vlc/libvlc_media_list.h

   1 /*****************************************************************************
   2  * libvlc_media_list.h:  libvlc_media_list API
   3  *****************************************************************************
   4  * Copyright (C) 1998-2008 the VideoLAN team
   5  * $Id$
   6  *
   7  * Authors: Pierre d'Herbemont
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 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 General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  22  *****************************************************************************/
  23
  24 #ifndef LIBVLC_MEDIA_LIST_H
  25 #define LIBVLC_MEDIA_LIST_H 1
  26
  27 /**
  28  * \file
  29  * This file defines libvlc_media_list API
  30  */
  31
  32 # ifdef __cplusplus
  33 extern "C" {
  34 # endif
  35
  36 /*****************************************************************************
  37  * Media List
  38  *****************************************************************************/
  39 /** \defgroup libvlc_media_list libvlc_media_list
  40  * \ingroup libvlc
  41  * LibVLC Media List, a media list holds multiple media descriptors
  42  * @{
  43  */
  44
  45 /**
  46  * Create an empty media list.
  47  *
  48  * \param p_libvlc libvlc instance
  49  * \param p_e an initialized exception pointer
  50  * \return empty media list
  51  */
  52 VLC_PUBLIC_API libvlc_media_list_t *
  53     libvlc_media_list_new( libvlc_instance_t *, libvlc_exception_t * );
  54
  55 /**
  56  * Release media list created with libvlc_media_list_new().
  57  *
  58  * \param p_ml a media list created with libvlc_media_list_new()
  59  */
  60 VLC_PUBLIC_API void
  61     libvlc_media_list_release( libvlc_media_list_t * );
  62
  63 /**
  64  * Retain reference to a media list
  65  *
  66  * \param p_ml a media list created with libvlc_media_list_new()
  67  */
  68 VLC_PUBLIC_API void
  69     libvlc_media_list_retain( libvlc_media_list_t * );
  70
  71 VLC_DEPRECATED_API void
  72     libvlc_media_list_add_file_content( libvlc_media_list_t * p_mlist,
  73                                         const char * psz_uri,
  74                                         libvlc_exception_t * p_e );
  75
  76 /**
  77  * Associate media instance with this media list instance.
  78  * If another media instance was present it will be released.
  79  * The libvlc_media_list_lock should NOT be held upon entering this function.
  80  *
  81  * \param p_ml a media list instance
  82  * \param p_mi media instance to add
  83  * \param p_e initialized exception object
  84  */
  85 VLC_PUBLIC_API void
  86     libvlc_media_list_set_media( libvlc_media_list_t *,
  87                                             libvlc_media_t *,
  88                                             libvlc_exception_t *);
  89
  90 /**
  91  * Get media instance from this media list instance. This action will increase
  92  * the refcount on the media instance.
  93  * The libvlc_media_list_lock should NOT be held upon entering this function.
  94  *
  95  * \param p_ml a media list instance
  96  * \param p_e initialized exception object
  97  * \return media instance
  98  */
  99 VLC_PUBLIC_API libvlc_media_t *
 100     libvlc_media_list_media( libvlc_media_list_t *,
 101                                         libvlc_exception_t *);
 102
 103 /**
 104  * Add media instance to media list
 105  * The libvlc_media_list_lock should be held upon entering this function.
 106  *
 107  * \param p_ml a media list instance
 108  * \param p_mi a media instance
 109  * \param p_e initialized exception object
 110  */
 111 VLC_PUBLIC_API void
 112     libvlc_media_list_add_media( libvlc_media_list_t *,
 113                                             libvlc_media_t *,
 114                                             libvlc_exception_t * );
 115
 116 /**
 117  * Insert media instance in media list on a position
 118  * The libvlc_media_list_lock should be held upon entering this function.
 119  *
 120  * \param p_ml a media list instance
 121  * \param p_mi a media instance
 122  * \param i_pos position in array where to insert
 123  * \param p_e initialized exception object
 124  */
 125 VLC_PUBLIC_API void
 126     libvlc_media_list_insert_media( libvlc_media_list_t *,
 127                                                libvlc_media_t *,
 128                                                int,
 129                                                libvlc_exception_t * );
 130 /**
 131  * Remove media instance from media list on a position
 132  * The libvlc_media_list_lock should be held upon entering this function.
 133  *
 134  * \param p_ml a media list instance
 135  * \param i_pos position in array where to insert
 136  * \param p_e initialized exception object
 137  */
 138 VLC_PUBLIC_API void
 139     libvlc_media_list_remove_index( libvlc_media_list_t *, int,
 140                                     libvlc_exception_t * );
 141
 142 /**
 143  * Get count on media list items
 144  * The libvlc_media_list_lock should be held upon entering this function.
 145  *
 146  * \param p_ml a media list instance
 147  * \param p_e initialized exception object
 148  * \return number of items in media list
 149  */
 150 VLC_PUBLIC_API int
 151     libvlc_media_list_count( libvlc_media_list_t * p_mlist,
 152                              libvlc_exception_t * p_e );
 153
 154 /**
 155  * List media instance in media list at a position
 156  * The libvlc_media_list_lock should be held upon entering this function.
 157  *
 158  * \param p_ml a media list instance
 159  * \param i_pos position in array where to insert
 160  * \param p_e initialized exception object
 161  * \return media instance at position i_pos and libvlc_media_retain() has been called to increase the refcount on this object.
 162  */
 163 VLC_PUBLIC_API libvlc_media_t *
 164     libvlc_media_list_item_at_index( libvlc_media_list_t *, int,
 165                                      libvlc_exception_t * );
 166 /**
 167  * Find index position of List media instance in media list.
 168  * Warning: the function will return the first matched position.
 169  * The libvlc_media_list_lock should be held upon entering this function.
 170  *
 171  * \param p_ml a media list instance
 172  * \param p_mi media list instance
 173  * \param p_e initialized exception object
 174  * \return position of media instance
 175  */
 176 VLC_PUBLIC_API int
 177     libvlc_media_list_index_of_item( libvlc_media_list_t *,
 178                                      libvlc_media_t *,
 179                                      libvlc_exception_t * );
 180
 181 /**
 182  * This indicates if this media list is read-only from a user point of view
 183  *
 184  * \param p_ml media list instance
 185  * \return 0 on readonly, 1 on readwrite
 186  */
 187 VLC_PUBLIC_API int
 188     libvlc_media_list_is_readonly( libvlc_media_list_t * p_mlist );
 189
 190 /**
 191  * Get lock on media list items
 192  *
 193  * \param p_ml a media list instance
 194  */
 195 VLC_PUBLIC_API void
 196     libvlc_media_list_lock( libvlc_media_list_t * );
 197
 198 /**
 199  * Release lock on media list items
 200  * The libvlc_media_list_lock should be held upon entering this function.
 201  *
 202  * \param p_ml a media list instance
 203  */
 204 VLC_PUBLIC_API void
 205     libvlc_media_list_unlock( libvlc_media_list_t * );
 206
 207 /**
 208  * Get a flat media list view of media list items
 209  *
 210  * \param p_ml a media list instance
 211  * \param p_ex an excpetion instance
 212  * \return flat media list view instance
 213  */
 214 VLC_PUBLIC_API libvlc_media_list_view_t *
 215     libvlc_media_list_flat_view( libvlc_media_list_t *,
 216                                  libvlc_exception_t * );
 217
 218 /**
 219  * Get a hierarchical media list view of media list items
 220  *
 221  * \param p_ml a media list instance
 222  * \param p_ex an excpetion instance
 223  * \return hierarchical media list view instance
 224  */
 225 VLC_PUBLIC_API libvlc_media_list_view_t *
 226     libvlc_media_list_hierarchical_view( libvlc_media_list_t *,
 227                                          libvlc_exception_t * );
 228
 229 VLC_PUBLIC_API libvlc_media_list_view_t *
 230     libvlc_media_list_hierarchical_node_view( libvlc_media_list_t *,
 231                                               libvlc_exception_t * );
 232
 233 /**
 234  * Get libvlc_event_manager from this media list instance.
 235  * The p_event_manager is immutable, so you don't have to hold the lock
 236  *
 237  * \param p_ml a media list instance
 238  * \param p_ex an excpetion instance
 239  * \return libvlc_event_manager
 240  */
 241 VLC_PUBLIC_API libvlc_event_manager_t *
 242     libvlc_media_list_event_manager( libvlc_media_list_t *,
 243                                      libvlc_exception_t * );
 244
 245 /*****************************************************************************
 246  * Media List View
 247  *****************************************************************************/
 248 /** \defgroup libvlc_media_list_view libvlc_media_list_view
 249  * \ingroup libvlc_media_list
 250  * LibVLC Media List View, represent a media_list using a different layout
 251  * @{ */
 252
 253 /**
 254  * Retain reference to a media list view
 255  *
 256  * \param p_mlv a media list view created with libvlc_media_list_view_new()
 257  */
 258 VLC_PUBLIC_API void
 259     libvlc_media_list_view_retain( libvlc_media_list_view_t * p_mlv );
 260
 261 /**
 262  * Release reference to a media list view. If the refcount reaches 0, then
 263  * the object will be released.
 264  *
 265  * \param p_mlv a media list view created with libvlc_media_list_view_new()
 266  */
 267 VLC_PUBLIC_API void
 268     libvlc_media_list_view_release( libvlc_media_list_view_t * p_mlv );
 269
 270 /**
 271  * Get libvlc_event_manager from this media list view instance.
 272  * The p_event_manager is immutable, so you don't have to hold the lock
 273  *
 274  * \param p_mlv a media list view instance
 275  * \return libvlc_event_manager
 276  */
 277 VLC_PUBLIC_API libvlc_event_manager_t *
 278     libvlc_media_list_view_event_manager( libvlc_media_list_view_t * p_mlv );
 279
 280 /**
 281  * Get count on media list view items
 282  *
 283  * \param p_mlv a media list view instance
 284  * \param p_e initialized exception object
 285  * \return number of items in media list view
 286  */
 287 VLC_PUBLIC_API int
 288     libvlc_media_list_view_count(  libvlc_media_list_view_t * p_mlv,
 289                                    libvlc_exception_t * p_e );
 290
 291 /**
 292  * List media instance in media list view at an index position
 293  *
 294  * \param p_mlv a media list view instance
 295  * \param i_index index position in array where to insert
 296  * \param p_e initialized exception object
 297  * \return media instance at position i_pos and libvlc_media_retain() has been called to increase the refcount on this object.
 298  */
 299 VLC_PUBLIC_API libvlc_media_t *
 300     libvlc_media_list_view_item_at_index(  libvlc_media_list_view_t * p_mlv,
 301                                            int i_index,
 302                                            libvlc_exception_t * p_e );
 303
 304 VLC_PUBLIC_API libvlc_media_list_view_t *
 305     libvlc_media_list_view_children_at_index(  libvlc_media_list_view_t * p_mlv,
 306                                            int index,
 307                                            libvlc_exception_t * p_e );
 308
 309 VLC_PUBLIC_API libvlc_media_list_view_t *
 310     libvlc_media_list_view_children_for_item(  libvlc_media_list_view_t * p_mlv,
 311                                            libvlc_media_t * p_md,
 312                                            libvlc_exception_t * p_e );
 313
 314 /**
 315  * Get index position of media instance in media list view.
 316  * The function will return the first occurence.
 317  *
 318  * \param p_mlv a media list view instance
 319  * \param p_md media instance
 320  * \param p_e initialized exception object
 321  * \return index position in array of p_md
 322  */
 323 VLC_PUBLIC_API int
 324     libvlc_media_list_view_index_of_item(  libvlc_media_list_view_t * p_mlv,
 325                                            libvlc_media_t * p_md,
 326                                            libvlc_exception_t * p_e );
 327
 328 /**
 329  * Insert media instance in media list view at index position
 330  *
 331  * \param p_mlv a media list view instance
 332  * \param p_md media instance
 333  * \param index position in array where to insert
 334  * \param p_e initialized exception object
 335  */
 336 VLC_PUBLIC_API void
 337     libvlc_media_list_view_insert_at_index(  libvlc_media_list_view_t * p_mlv,
 338                                              libvlc_media_t * p_md,
 339                                              int index,
 340                                              libvlc_exception_t * p_e );
 341
 342 /**
 343  * Remove media instance in media list view from index position
 344  *
 345  * \param p_mlv a media list view instance
 346  * \param index position in array of media instance to remove
 347  * \param p_e initialized exception object
 348  */
 349 VLC_PUBLIC_API void
 350     libvlc_media_list_view_remove_at_index(  libvlc_media_list_view_t * p_mlv,
 351                                              int index,
 352                                              libvlc_exception_t * p_e );
 353
 354 VLC_PUBLIC_API void
 355     libvlc_media_list_view_add_item(  libvlc_media_list_view_t * p_mlv,
 356                                       libvlc_media_t * p_md,
 357                                       libvlc_exception_t * p_e );
 358
 359 VLC_PUBLIC_API libvlc_media_list_t *
 360     libvlc_media_list_view_parent_media_list(  libvlc_media_list_view_t * p_mlv,
 361                                                libvlc_exception_t * p_e );
 362
 363 /** @} media_list_view */
 364
 365 /*****************************************************************************
 366  * Media List Player
 367  *****************************************************************************/
 368 /** \defgroup libvlc_media_list_player libvlc_media_list_player
 369  * \ingroup libvlc_media_list_player
 370  * LibVLC Media List Player, play a media_list. You can see that as a media
 371  * instance subclass
 372  * @{
 373  */
 374
 375 /**
 376  * Create new media_list_player.
 377  *
 378  * \param p_instance libvlc instance
 379  * \param p_e initialized exception instance
 380  * \return media list player instance
 381  */
 382 VLC_PUBLIC_API libvlc_media_list_player_t *
 383     libvlc_media_list_player_new( libvlc_instance_t * p_instance,
 384                                   libvlc_exception_t * p_e );
 385
 386 /**
 387  * Release media_list_player.
 388  *
 389  * \param p_mlp media list player instance
 390  */
 391 VLC_PUBLIC_API void
 392     libvlc_media_list_player_release( libvlc_media_list_player_t * p_mlp );
 393
 394 /**
 395  * Replace media player in media_list_player with this instance.
 396  *
 397  * \param p_mlp media list player instance
 398  * \param p_mi media player instance
 399  * \param p_e initialized exception instance
 400  */
 401 VLC_PUBLIC_API void
 402     libvlc_media_list_player_set_media_player(
 403                                      libvlc_media_list_player_t * p_mlp,
 404                                      libvlc_media_player_t * p_mi,
 405                                      libvlc_exception_t * p_e );
 406
 407 VLC_PUBLIC_API void
 408     libvlc_media_list_player_set_media_list(
 409                                      libvlc_media_list_player_t * p_mlp,
 410                                      libvlc_media_list_t * p_mlist,
 411                                      libvlc_exception_t * p_e );
 412
 413 /**
 414  * Play media list
 415  *
 416  * \param p_mlp media list player instance
 417  * \param p_e initialized exception instance
 418  */
 419 VLC_PUBLIC_API void
 420     libvlc_media_list_player_play( libvlc_media_list_player_t * p_mlp,
 421                                    libvlc_exception_t * p_e );
 422
 423 /**
 424  * Pause media list
 425  *
 426  * \param p_mlp media list player instance
 427  * \param p_e initialized exception instance
 428  */
 429 VLC_PUBLIC_API void
 430     libvlc_media_list_player_pause( libvlc_media_list_player_t * p_mlp,
 431                                    libvlc_exception_t * p_e );
 432
 433 /**
 434  * Is media list playing?
 435  *
 436  * \param p_mlp media list player instance
 437  * \param p_e initialized exception instance
 438  * \return true for playing and false for not playing
 439  */
 440 VLC_PUBLIC_API int
 441     libvlc_media_list_player_is_playing( libvlc_media_list_player_t * p_mlp,
 442                                          libvlc_exception_t * p_e );
 443
 444 /**
 445  * Get current libvlc_state of media list player
 446  *
 447  * \param p_mlp media list player instance
 448  * \param p_e initialized exception instance
 449  * \return libvlc_state_t for media list player
 450  */
 451 VLC_PUBLIC_API libvlc_state_t
 452     libvlc_media_list_player_get_state( libvlc_media_list_player_t * p_mlp,
 453                                         libvlc_exception_t * p_e );
 454
 455 /**
 456  * Play media list item at position index
 457  *
 458  * \param p_mlp media list player instance
 459  * \param i_index index in media list to play
 460  * \param p_e initialized exception instance
 461  */
 462 VLC_PUBLIC_API void
 463     libvlc_media_list_player_play_item_at_index(
 464                                    libvlc_media_list_player_t * p_mlp,
 465                                    int i_index,
 466                                    libvlc_exception_t * p_e );
 467
 468 VLC_PUBLIC_API void
 469     libvlc_media_list_player_play_item(
 470                                    libvlc_media_list_player_t * p_mlp,
 471                                    libvlc_media_t * p_md,
 472                                    libvlc_exception_t * p_e );
 473
 474 /**
 475  * Stop playing media list
 476  *
 477  * \param p_mlp media list player instance
 478  * \param p_e initialized exception instance
 479  */
 480 VLC_PUBLIC_API void
 481     libvlc_media_list_player_stop( libvlc_media_list_player_t * p_mlp,
 482                                    libvlc_exception_t * p_e );
 483
 484 /**
 485  * Play next item from media list
 486  *
 487  * \param p_mlp media list player instance
 488  * \param p_e initialized exception instance
 489  */
 490 VLC_PUBLIC_API void
 491     libvlc_media_list_player_next( libvlc_media_list_player_t * p_mlp,
 492                                    libvlc_exception_t * p_e );
 493
 494 /* NOTE: shouldn't there also be a libvlc_media_list_player_prev() */
 495
 496 /** @} media_list_player */
 497
 498 /** @} media_list */
 499
 500 # ifdef __cplusplus
 501 }
 502 # endif
 503
 504 #endif /* _LIBVLC_MEDIA_LIST_H */