/***************************************************************************** * vlc_playlist.h : Playlist functions ***************************************************************************** * Copyright (C) 1999-2004 the VideoLAN team * $Id: 49372b288904b4aae1976cc4705254615bca5243 $ * * Authors: Samuel Hocevar <sam@zoy.org> * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. *****************************************************************************/#ifndef VLC_PLAYLIST_H_#define VLC_PLAYLIST_H_# ifdef __cplusplusextern "C" {# endif#include <vlc_input.h>#include <vlc_events.h>#include <vlc_services_discovery.h>#include <stdio.h>#include <stdlib.h>TYPEDEF_ARRAY(playlist_item_t*, playlist_item_array_t);/** * \file * This file contain structures and function prototypes related * to the playlist in vlc * * \defgroup vlc_playlist Playlist * * The VLC playlist system has a tree structure. This allows advanced * categorization, like for SAP streams (which are grouped by "sap groups"). * * The base structure for all playlist operations is the input_item_t. This * contains all information needed to play a stream and get info, ie, mostly, * mrl and metadata. This structure contains a unique i_id field. ids are * not recycled when an item is destroyed. * * Input items are not used directly, but through playlist items. * The playlist items are themselves in a tree structure. They only contain * a link to the input item, a unique id and a few flags. the playlist * item id is NOT the same as the input item id. * Several playlist items can be attached to a single input item. The input * item is refcounted and is automatically destroyed when it is not used * anymore. * * In the playlist itself, there are two trees, that should always be kept * in sync. The "category" tree contains the whole tree structure with * several levels, while the onelevel tree contains only one level :), ie * it only contains "real" items, not nodes * For example, if you open a directory, you will have *\verbatim * Category tree:               Onelevel tree: * Playlist                     Playlist *  - Dir                         - item1 *    - Subdir                    - item2 *      - item1 *      - item2 *\endverbatim * The top-level items of both tree are the same, and they are reproduced * in the left-part of the playlist GUIs, they are the "sources" from the * source selectors. Top-level items include: playlist, media library, SAP, * Shoutcast, devices, ... * * It is envisioned that a third tree will appear: VLM, but it's not done yet * * The playlist also stores, for utility purposes, an array of all input * items, an array of all playlist items and an array of all playlist items * and nodes (both are represented by the same structure). * * So, here is an example: * \verbatim * Inputs array *  - input 1 -> name = foo 1 uri = ... *  - input 2 -> name = foo 2 uri = ... * * Category tree                        Onelevel tree * - playlist (id 1)                    - playlist (id 3) *    - category 1 (id 2)                - foo 2 (id 8 - input 2) *      - foo 2 (id 6 - input 2)       - media library (id 4) * - media library (id 2)                - foo 1 (id6 - input 1) *    - foo 1 (id 5 - input 1) * \endverbatim * Sometimes, an item must be transformed to a node. This happens for the * directory access for example. In that case, the item is removed from * the onelevel tree, as it is not a real item anymore. * * For "standard" item addition, you can use playlist_Add, playlist_AddExt * (more options) or playlist_AddInput if you already created your input * item. This will add the item at the root of "Playlist" or of "Media library" * in each of the two trees. * * If you want more control (like, adding the item as the child of a given * node in the category tree, use playlist_BothAddInput. You'll have to provide * the node in the category tree. The item will be added as a child of * this node in the category tree, and as a child of the matching top-level * node in the onelevel tree. (Nodes are created with playlist_NodeCreate) * * Generally speaking, playlist_NodeAddInput should not be used in newer code, it * will maybe become useful again when we merge VLM; * * To delete an item, use playlist_DeleteFromInput( input_id ) which will * remove all occurrences of the input in both trees * * @{ *//** Helper structure to export to file part of the playlist */struct playlist_export_t{    char *psz_filename;    FILE *p_file;    playlist_item_t *p_root;};/** playlist item / node */struct playlist_item_t{    input_item_t           *p_input;    /**< Linked input item */    /** Number of children, -1 if not a node */    int                    i_children;    playlist_item_t      **pp_children; /**< Children nodes/items */    playlist_item_t       *p_parent;    /**< Item parent */    int                    i_id;        /**< Playlist item specific id */    uint8_t                i_flags;     /**< Flags */    playlist_t            *p_playlist;  /**< Parent playlist */};#define PLAYLIST_SAVE_FLAG      0x0001    /**< Must it be saved */#define PLAYLIST_SKIP_FLAG      0x0002    /**< Must playlist skip after it ? */#define PLAYLIST_DBL_FLAG       0x0004    /**< Is it disabled ? */#define PLAYLIST_RO_FLAG        0x0008    /**< Write-enabled ? */#define PLAYLIST_REMOVE_FLAG    0x0010    /**< Remove this item at the end */#define PLAYLIST_EXPANDED_FLAG  0x0020    /**< Expanded node *//** Playlist status */typedef enum{ PLAYLIST_STOPPED,PLAYLIST_RUNNING,PLAYLIST_PAUSED } playlist_status_t;/** Structure containing information about the playlist */struct playlist_t{    VLC_COMMON_MEMBERS    playlist_item_array_t items; /**< Arrays of items */    playlist_item_array_t all_items; /**< Array of items and nodes */    playlist_item_array_t current; /**< Items currently being played */    int                   i_current_index; /**< Index in current array */    /* Predefined items */    playlist_item_t *     p_root_category; /**< Root of category tree */    playlist_item_t *     p_root_onelevel; /**< Root of onelevel tree */    playlist_item_t *     p_local_category; /** < "Playlist" in CATEGORY view */    playlist_item_t *     p_ml_category; /** < "Library" in CATEGORY view */    playlist_item_t *     p_local_onelevel; /** < "Playlist" in ONELEVEL view */    playlist_item_t *     p_ml_onelevel; /** < "Library" in ONELEVEL view */};/** Helper to add an item */struct playlist_add_t{    int i_node;    int i_item;    int i_position;};#define SORT_ID 0#define SORT_TITLE 1#define SORT_TITLE_NODES_FIRST 2#define SORT_ARTIST 3#define SORT_GENRE 4#define SORT_RANDOM 5#define SORT_DURATION 6#define SORT_TITLE_NUMERIC 7#define SORT_ALBUM 8#define SORT_TRACK_NUMBER 9#define SORT_DESCRIPTION 10#define SORT_RATING 11#define SORT_URI 12#define ORDER_NORMAL 0#define ORDER_REVERSE 1