path: root/include/xine.h.tmpl.in

/**
 * \file xine.h
 * \author Guenter Bartsch <guenter@users.sourceforge.net>
 * \author Siegfried Langauf <siggi@users.sourceforge.net>
 * \author Daniel Caujolle-Bert <f1rmb@users.sourceforge.net>
 * \date 25/07/2001
 *
 * API of XINE library.
 \verbatim
   Copyright (C) 2000-2001 the xine project
 
   This file is part of xine, a unix video player.
 
   xine 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.
 
   xine 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., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA
 
 \endverbatim
 */
/*
 * $Id: xine.h.tmpl.in,v 1.40 2001/09/01 14:32:59 guenter Exp $
 *
 */

#ifndef HAVE_XINE_H
#define HAVE_XINE_H

#ifdef __cplusplus
extern "C" {
#endif

#include <inttypes.h>
#include <unistd.h>
#include <sys/types.h>

#ifndef XINE_COMPILE
#include <xine/video_out.h>
#endif

#ifndef DOC_HIDDEN
#include <xine/events.h>
#endif

/**
 * \def XINE_SKINDIR
 * Skin file location
 */
#define XINE_SKINDIR    "@XINE_SKINPATH@"

     /**
      * \defgroup build_info Build informations
      * @{
      */

/**
 * \def XINE_BUILD_CC
 * Compiler used to build xine-lib
 */
#define XINE_BUILD_CC      "@XINE_BUILD_CC@"
/** \def XINE_BUILD_OS
 * OS used to build xine-lib
 */
#define XINE_BUILD_OS      "@XINE_BUILD_OS@"
/** \def XINE_BUILD_DATE
 * Build time
 */
#define XINE_BUILD_DATE    "@XINE_BUILD_DATE@"

     /** @} end of build_info */

     /**
      * \defgroup xine_api API functions
      * @{
      */

          /**
	   * \defgroup status_group Player status constants
	   * @{
	   */

/** 
 * \def XINE_STOP
 * Stop status.
 * \sa xine_get_status()
 */
#define XINE_STOP      0
/**
 * \def XINE_PLAY
 * Play status.
 * \sa xine_get_status()
 */
#define XINE_PLAY      1
/** 
 * \def XINE_QUIT
 * Quit status.
 * \sa xine_get_status()
 */
#define XINE_QUIT      2

          /** @} end of status_group */

          /** 
	   * \defgroup version_group Version constants 
	   * @{
	   */

/**
 * \def XINE_MAJOR_VERSION
 * Major version constant.
 */
#define XINE_MAJOR_VERSION @XINE_MAJOR@
/**
 * \def XINE_MINOR_VERSION
 * Minor version constant.
 */
#define XINE_MINOR_VERSION @XINE_MINOR@
/**
 * \def XINE_SUB_VERSION
 * Sub version constant.
 */
#define XINE_SUB_VERSION   @XINE_SUB@

          /** @} end of version_group */

          /**
	   * \defgroup xine_version Version functions
	   * @{
	   */

/**
 * \fn char *xine_get_str_version(void);
 * \brief return string version, like "0.5.0"
 * \param None.
 * \return string version
 *
 */
char *xine_get_str_version(void);

/**
 * \fn int xine_get_major_version(void);
 * \brief return version information
 * \param None.
 * \return major version.
 *
 */
int xine_get_major_version(void);

/**
 * \fn int xine_get_minor_version(void);
 * \brief return version information
 * \param None.
 * \return minor version.
 *
 */
int xine_get_minor_version(void);

/**
 * \fn int xine_get_sub_version(void);
 * \brief return version information
 * \param None.
 * \return sub version.
 *
 */
int xine_get_sub_version(void);

/**
 * \fn int xine_check_version(int major, int minor, int sub);
 * \brief check minimal version.
 * \param major major version wanted.
 * \param minorr minor version wanted.
 * \param sub sub version wanted.
 * \return 1 if installed version is >= to desired, otherwise 0
 *
 * Compare version numbers with xine installed version.
 */
int xine_check_version(int major, int minor, int sub);

          /** @} end of xine_version */

          /** 
	   * \defgroup video_group Video.
	   * @{
	   */

                /**
		 * 
		 * \defgroup video_cap video driver capabilities
		 * @{
		 */
/** 
 * \def VO_CAP_HUE
 * Driver can set HUE value.
 */
#define VO_CAP_HUE          0x00000010
/** 
 * \def VO_CAP_SATURATION
 * Driver can set SATURATION value.
 */
#define VO_CAP_SATURATION   0x00000020
/**
 * \def VO_CAP_BRIGHTNESS
 * Driver can set BRIGHTNESS value.
 */
#define VO_CAP_BRIGHTNESS   0x00000040
/**
 * \def VO_CAP_CONTRAST
 * Driver can set CONTRAST value.
 */
#define VO_CAP_CONTRAST     0x00000080
/**
 * \def VO_CAP_COLORKEY
 * Driver can set COLORKEY value.
 */
#define VO_CAP_COLORKEY     0x00000100

               /** @} end of video_cap */

               /**
		* 
		* \defgroup video_prop Constants for the get/set properties functions.
		* @{
		*/
/**
 * \def VO_PROP_INTERLACED
 * Interleave property.
 * \sa vo_driver_t
 */
#define VO_PROP_INTERLACED      0
/**
 * \def VO_PROP_ASPECT_RATIO
 * Aspect ratio property.
 * \sa vo_driver_t, video_ratio
 */
#define VO_PROP_ASPECT_RATIO    1
/**
 * \def VO_PROP_HUE
 * Hue property.
 * \sa vo_driver_t
 */
#define VO_PROP_HUE             2
/**
 * \def VO_PROP_SATURATION
 * Saturation property.
 * \sa vo_driver_t
 */
#define VO_PROP_SATURATION      3
/**
 * \def VO_PROP_CONTRAST
 * Contrast property.
 * \sa vo_driver_t
 */
#define VO_PROP_CONTRAST        4
/**
 * \def VO_PROP_BRIGHTNESS
 * Brightness property.
 * \sa vo_driver_t
 */
#define VO_PROP_BRIGHTNESS      5
/**
 * \def VO_PROP_COLORKEY
 * Colorkey property.
 * \sa vo_driver_t
 */
#define VO_PROP_COLORKEY        6
/**
 * \def VO_NUM_PROPERTIES
 * Number of available properties property.
 * \sa vo_driver_t
 */
#define VO_NUM_PROPERTIES       7

               /** @} end of video_prop */

               /**
		* \defgroup video_ratio Possible ratios for the VO_PROP_ASPECT_RATIO call
		* \sa VO_PROP_ASPECT_RATIO, vo_driver_t
		* @{
		*/

/**
 * \def ASPECT_AUTO
 * Let video driver guessing aspect ratio.
 * \sa VO_PROP_ASPECT_RATIO
 */
#define ASPECT_AUTO        0
/**
 * \def ASPECT_ANAMORPHIC
 * Set aspect ration to 16:9.
 * \sa VO_PROP_ASPECT_RATIO
 */
#define ASPECT_ANAMORPHIC  1
/**
 * \def ASPECT_FULL
 * Set aspect ration to 4:3.
 * \sa VO_PROP_ASPECT_RATIO
 */
#define ASPECT_FULL        2
/**
 * \def ASPECT_DVB
 * Set aspect ration to 1:2.
 * \sa VO_PROP_ASPECT_RATIO
 */
#define ASPECT_DVB         3

               /** @} end of video_ratio */

#ifdef DOC_HIDDEN
/**
 * \struct vo_frame_t
 * Opaque data type.
 * \sa vo_driver_t
 */
typedef void vo_frame_t;
/**
 * \struct vo_overlay_t
 * Opaque data type.
 * \sa vo_driver_t
 */
typedef void vo_overlay_t;

/**
 * \struct vo_driver_t
 * \brief Data type of structure vo_driver_s.
 * \sa structure vo_driver_s.
 */
typedef struct vo_driver_s vo_driver_t;

/**
 * \struct vo_driver_s
 * Video driver fonctions.
 */
struct vo_driver_s {
  /**
   * Get capabilities of video driver.
   * \sa video_cap
   */
  uint32_t (*get_capabilities) (vo_driver_t *self);
  /**
   * Allocate an vo_frame_t struct,
   * the driver must supply the copy, field and dispose functions
   */
  vo_frame_t* (*alloc_frame) (vo_driver_t *self);
  /**
   * Check if the given image fullfills the format specified
   * (re-)allocate memory if necessary
   */
  void (*update_frame_format) (vo_driver_t *self, vo_frame_t *img,
			       uint32_t width, uint32_t height, 
			       int ratio_code, int format);
  /**
   * Display a given frame
   */
  void (*display_frame) (vo_driver_t *self, vo_frame_t *vo_img);
  /**
   * Overlay functions
   */
  void (*overlay_blend) (vo_driver_t *self, vo_frame_t *vo_img, vo_overlay_t *overlay);
  /**
   * These can be used by the gui directly:
   */
  /**
   * Get value if property.
   * \sa video_prop
   */
  int (*get_property) (vo_driver_t *self, int property);
  /**
   * Set value of property.
   * \sa video_prop
   */
  int (*set_property) (vo_driver_t *self, 
		       int property, int value);
  /**
   * Get min/max values of property.
   * \sa video_prop
   */
  void (*get_property_min_max) (vo_driver_t *self,
				int property, int *min, int *max);
  /** 
   * General purpose communication channel between gui and driver
   *
   * this should be used to propagate events, display data, window sizes
   * etc. to the driver
   */
  int (*gui_data_exchange) (vo_driver_t *self, int data_type,
			    void *data);
  /**
   * Leaving video driver.
   */
  void (*exit) (vo_driver_t *self);

};
#endif
          /** @} end of video_group */

          /** 
	   * \defgroup xine_init Init functions
	   * @{
	   */

               /** 
		* \defgroup config_group Configuration structure type.
		* @{
		*/

/**
 * \struct xine_t
 * Opaque data type.
 * \sa xine_load_audio_output_plugin
 */
typedef void xine_t;
/**
 * \struct ao_driver_t 
 * Opaque data type.
 */
typedef void ao_driver_t;
/**
 * \struct cfg_data_t
 * Opaque data type.
 */

#ifdef DOC_HIDDEN
typedef void cfg_data_t;
/**
 * \struct config_values_t
 * \brief Data type of structure config_values_s.
 * \sa config_values_s.
 */
typedef struct config_values_s config_values_t;
/**
 * \struct config_values_s
 * Configuration file manipulation.
 * \sa config_file_init()
 */
struct config_values_s {
  /**
   * Lookup string values in configuration file.
   */
  char* (*lookup_str) (config_values_t *self,
		       char *key, char *str_default);
  /**
   * Lookup integer values in configuration file.
   */
  int (*lookup_int) (config_values_t *self,
		     char *key, int n_default);
  /**
   * Set string values in configuration file.
   */
  void (*set_str) (config_values_t *self,
		   char *key, char *value) ;
  /**
   * Set integer values in configuration file.
   */
  void (*set_int) (config_values_t *self,
		   char *key, int value) ;
  /**
   * Write configuration file to disk.
   */
  void (*save) (config_values_t *self);
  /**
   * Read configuration file from disk, overriding values in memory.
   * If you also want to clear values that are not in the file,
   * use config_file_init() instead!
   */
  void (*read) (config_values_t *self, char *filename);
  /** 
   * Contains private data of this configuration file.
   */
  cfg_data_t *data;
};
#endif
               /** @} end of config_group */
  

/**
 * \fn config_values_t *config_file_init (char *filename)
 * \brief Configuration file initialisation.
 * \param filename Pathname of configuration file.
 * \return Current config
 * \sa config_values_t
 * \warning This function should be called at least one time before xine_init() call.
 *
 * Read config file and init a config object of config_values_t type (if it exists)
 */
config_values_t *config_file_init (char *filename);

               /** 
		* \defgroup ui_callbacks UI communication callbacks.
		* @{
		*
		*/

/**
 * Notify UI when the stream is finished.
 * \sa xine_init()
 */
typedef void (*gui_stream_end_cb_t) (int nStatus);
/**
 * Called when xine tries to branch seamlessly to the next mrl.
 * \sa xine_init()
 */
typedef char* (*gui_get_next_mrl_cb_t) (void);
/**
 * Called when xine branched successfully to the next mrl.
 * \sa xine_init()
 */
typedef void (*gui_branched_cb_t) (void);

               /** @} end of ui_callbacks */

               /**
		* \defgroup demux_strategy Possible demuxer guessing strategy.
		* "demux_strategy" should be set to one of these value in configuration file ( #see @ref config_group) before xine_init() call.
		* \sa config_values_t
		* @{
		*/

/**
 * \def DEMUX_DEFAULT_STRATEGY
 * Recognize by content then by extension.
 * \sa config_values_t
 */
#define DEMUX_DEFAULT_STRATEGY    0
/**
 * \def DEMUX_REVERT_STRATEGY
 * Recognize by extension then by content.
 * \sa config_values_t
 */
#define DEMUX_REVERT_STRATEGY     1
/**
 * \def DEMUX_CONTENT_STRATEGY
 * Recognize by content only.
 * \sa config_values_t
 */
#define DEMUX_CONTENT_STRATEGY    2
/**
 * \def DEMUX_EXTENSION_STRATEGY
 * Recognize by extension only.
 * \sa config_values_t
 */
#define DEMUX_EXTENSION_STRATEGY  3

               /** @} end of demux_strategy */

/**
 * \fn xine_t *xine_init (vo_driver_t *vo, ao_driver_t *ao, config_values_t *config, gui_stream_end_cb_t stream_end_cb, gui_get_next_mrl_cb_t get_next_mrl_cb, gui_branched_cb_t branched_cb);
 * \brief Initialisation of xine.
 * \param vo video driver ( #see @ref xine_load_video_output_plugin() )
 * \param ao audio driver ( #see @ref xine_load_audio_output_plugin() )
 * \param config current configuration ( #see config_file_init() )
 * \param stream_end cb called on stream end 
 * \param get_next_mrl_cb called to find out next mrl for seamless branching
 * \param branched_cb called if seamless branch was taken
 * \return Current xine engine configuration
 * \sa vo_driver_t, ao_driver_t, config_values_t, gui_stream_end_cb_t, gui_get_next_mrl_cb_t, gui_branched_cb_t
 * \warning This function should be called before any other xine_*() function.
 *
 * Init of xine. It should called once at startup.
 * all callbacks may be NULL if ui is not interested in them for whatever reason
 * ao may be NULL for no audio playback
 *
 */
xine_t *xine_init (vo_driver_t *vo, 
		   ao_driver_t *ao,
		   config_values_t *config,
		   gui_stream_end_cb_t stream_end_cb,
		   gui_get_next_mrl_cb_t get_next_mrl_cb,
		   gui_branched_cb_t branched_cb);

/**
 * \fn void xine_exit (xine_t *self)
 * \brief De-initialisation of xine
 * \param self Current xine engine configuration.
 * \return Nothing
 * \sa xine_init()
 *
 * De-init xine engine.
 */
void xine_exit (xine_t *self);

          /** @} end of xine_init */

          /**
	   * \defgroup xine_management Engine management
	   * @{
	   */
/**
 * \fn void xine_play (xine_t *self, char *MRL, int pos)
 * \brief Start to play a stream
 * \param self Current xine engine configuration ( #see xine_init() )
 * \param MRL Media Resource Location to open
 * \param start_pos position in input source (0..65535)
 * \param start_time position measured in seconds from stream start
 * \return Nothing
 *
 * Open a stream and play it.  If both start position parameters 
 * are !=0 start_pos will be used
 * for non-seekable streams both values will be ignored
 *
 */
void xine_play (xine_t *self, char *MRL, int start_pos, int start_time);

/*
 * set playback speed
 *
 * constants see below
 */

void xine_set_speed (xine_t *this, int speed);
int xine_get_speed (xine_t *this);

#define SPEED_PAUSE   0
#define SPEED_SLOW_4  1
#define SPEED_SLOW_2  2
#define SPEED_NORMAL  4
#define SPEED_FAST_2  8
#define SPEED_FAST_4 16

/*
 * manually adjust a/v sync
 */

void xine_set_av_offset (xine_t *this, int offset_pts);
int xine_get_av_offset (xine_t *this);

/**
 * \fn void xine_stop (xine_t *self)
 * \brief Stop playing
 * \param self Current xine engine configuration ( #see xine_init() )
 * \return Nothing
 *
 * Stop the playback.
 */
void xine_stop (xine_t *self);

/**
 * \fn int xine_eject(xine_t *self)
 * \brief Eject media
 * \param self Current xine engine configuration ( #see xine_init() )
 * \return 1 on success, 0 on failure.
 *
 * Tell current input plugin to eject media.
 */
int xine_eject(xine_t *self);

/**
 * \fn int xine_get_status (xine_t *self)
 * \brief Get current xine status
 * \param self Current xine engine configuration ( #see xine_init() )
 * \return Current status ( #see @ref status_group )
 *
 * Return the current state of xine engine.
 */
int xine_get_status (xine_t *self);

/**
 * \fn int xine_get_current_position (xine_t *self)
 * \brief Get current position
 * \param self Current xine engine configuration ( #see xine_init() )
 * \return Current position ( 0..65535 )
 *
 * Get current position in stream.
 */
int xine_get_current_position (xine_t *self);

/**
 * \fn int xine_get_current_time (xine_t *self)
 * \brief get current pos in seconds
 * \param self Current xine engine configuration ( #see xine_init() )
 * \return current position measured in seconds from the beginning of the stream
 *
 * get current position measured in seconds from the beginning of the stream
 */
int xine_get_current_time (xine_t *self);

/**
 * \fn int xine_get_stream_length (xine_t *self);
 * \brief estimate length of input stream in seconds
 * \param self Current xine engine configuration ( #see xine_init() )
 * \return length of input stream in seconds or 0 if stream is not seekable
 *
 * estimate length of input stream in seconds
 */
int xine_get_stream_length (xine_t *self);

/**
 * \fn int xine_get_audio_channel (xine_t *self)
 * \brief Get current audio channel
 * \param self Current xine engine configuration ( #see xine_init() )
 * \return Current audio chennel
 *
 * Get current audio channel.
 */
int xine_get_audio_channel (xine_t *self);

/**
 * \fn void xine_select_audio_channel (xine_t *self, int channel)
 * \brief Set audio channel
 * \param self Current xine engine configuration ( #see xine_init() )
 * \return Nothing
 *
 * Set desired audio channel.
 */
void xine_select_audio_channel (xine_t *self, int channel);

/**
 * \fn int xine_get_spu_channel (xine_t *self)
 * \brief Get current sub-title channel.
 * \param self Current xine engine configuration ( #see xine_init() )
 * \return Current sub-title channel
 *
 * Get current sub-title channel.
 */
int xine_get_spu_channel (xine_t *self);

/**
 * \fn void xine_select_spu_channel (xine_t *self, int channel)
 * \brief Set sub-title channel
 * \param self Current xine engine configuration ( #see xine_init() )
 * \return Nothing
 *
 * Set desired sub-title channel.
 */
void xine_select_spu_channel (xine_t *self, int channel);

         /** @} end of xine_management */

         /**
	  * \defgroup browse_group Browsing support
	  * @{
	  */

/**
 * \fn char **xine_get_browsable_input_plugin_ids (xine_t *self)
 * \brief Request list of browsable featured plugins
 * \param self Current xine engine configuration ( #see xine_init() )
 * \return List of plugins
 *
 * Some input plugins are browseable, 
 * get the list of ids of these plugins.
 */
char **xine_get_browsable_input_plugin_ids (xine_t *self) ;

               /**
		* \defgroup mrl_types Types of available mrls
		* These types are bit field, can be used ORed/ANDed.
		* \sa mrl_t
		* @{
		*/

/**
 * \def mrl_unknown
 * Unknow mrl type.
 * \sa mrl_t
 */
#define mrl_unknown        (0 << 0)
/**
 * \def mrl_dvd
 * DVD mrl type.
 * \sa mrl_t
 */
#define mrl_dvd            (1 << 0)
/**
 * \def mrl_vcd
 * VCD mrl type.
 * \sa mrl_t
 */
#define mrl_vcd            (1 << 1)
/**
 * \def mrl_net
 * Network mrl type.
 * \sa mrl_t
 */
#define mrl_net            (1 << 2)
/**
 * \def mrl_rtp
 * Multicast mrl type.
 * \sa mrl_t
 */
#define mrl_rtp            (1 << 3)
/**
 * \def mrl_stdin
 * Standart input mrl type.
 * \sa mrl_t
 */
#define mrl_stdin          (1 << 4)
/**
 * \def mrl_file
 * File mrl type.
 * \sa mrl_t
 */
#define mrl_file           (1 << 5)
/**
 * \def mrl_file_fifo
 * Fifo file mrl type.
 * \sa mrl_t
 */
#define mrl_file_fifo      (1 << 6)
/**
 * \def mrl_file_chardev
 * Char device file mrl type.
 * \sa mrl_t
 */
#define mrl_file_chardev   (1 << 7)
/**
 * \def mrl_file_directory
 * Directory file mrl type.
 * \sa mrl_t
 */
#define mrl_file_directory (1 << 8)
/**
 * \def mrl_file_blockdev
 * Block device file mrl type.
 * \sa mrl_t
 */
#define mrl_file_blockdev  (1 << 9)
/**
 * \def mrl_file_normal
 * Normal file mrl type.
 * \sa mrl_t
 */
#define mrl_file_normal    (1 << 10)
/**
 * \def mrl_file_symlink
 * Soft link file mrl type.
 * \sa mrl_t
 */
#define mrl_file_symlink   (1 << 11)
/**
 * \def mrl_file_sock
 * Socket file mrl type.
 * \sa mrl_t
 */
#define mrl_file_sock      (1 << 12)
/**
 * \def mrl_file_exec
 * Executable file mrl type.
 * \sa mrl_t
 */
#define mrl_file_exec      (1 << 13)
/**
 * \def mrl_file_backup
 * Backup file mrl type.
 * \sa mrl_t
 */
#define mrl_file_backup    (1 << 14)
/**
 * \def mrl_file_hidden
 * Hidden file mrl type.
 * \sa mrl_t
 */
#define mrl_file_hidden    (1 << 15)

               /** @} end of mrl_types */

/**
 * \def MRL_ZERO(m)
 * Freeing/zeroing all of entries of given mrl.
 * \sa mrl_t, xine_get_browse_mrls()
 */
#define MRL_ZERO(m) {                                                         \
  if((m)) {                                                                   \
    if((m)->origin)                                                           \
      free((m)->origin);                                                      \
    if((m)->mrl)                                                              \
      free((m)->mrl);                                                         \
    if((m)->link)                                                             \
      free((m)->link);                                                        \
    (m)->origin = NULL;                                                       \
    (m)->mrl    = NULL;                                                       \
    (m)->link   = NULL;                                                       \
    (m)->type   = 0;                                                          \
    (m)->size   = (off_t) 0;                                                  \
  }                                                                           \
}

/**
 * \def MRL_DUPLICATE(s, d)
 * Duplicate two mrls entries (s = source, d = destination).
 * \sa mrl_t, xine_get_browse_mrls()
 */
#define MRL_DUPLICATE(s, d) {                                                 \
  assert((s) != NULL);                                                        \
  assert((d) != NULL);                                                        \
                                                                              \
  if((s)->origin) {                                                           \
    if((d)->origin) {                                                         \
      (d)->origin = (char *) realloc((d)->origin, strlen((s)->origin) + 1);   \
      sprintf((d)->origin, "%s", (s)->origin);                                \
    }                                                                         \
    else                                                                      \
      (d)->origin = strdup((s)->origin);                                      \
  }                                                                           \
  else                                                                        \
    (d)->origin = NULL;                                                       \
                                                                              \
  if((s)->mrl) {                                                              \
    if((d)->mrl) {                                                            \
      (d)->mrl = (char *) realloc((d)->mrl, strlen((s)->mrl) + 1);            \
      sprintf((d)->mrl, "%s", (s)->mrl);                                      \
    }                                                                         \
    else                                                                      \
      (d)->mrl = strdup((s)->mrl);                                            \
  }                                                                           \
  else                                                                        \
    (d)->mrl = NULL;                                                          \
                                                                              \
  if((s)->link) {                                                             \
    if((d)->link) {                                                           \
      (d)->link = (char *) realloc((d)->link, strlen((s)->link) + 1);         \
      sprintf((d)->link, "%s", (s)->link);                                    \
    }                                                                         \
    else                                                                      \
      (d)->link = strdup((s)->link);                                          \
  }                                                                           \
  else                                                                        \
    (d)->link = NULL;                                                         \
                                                                              \
  (d)->type = (s)->type;                                                      \
  (d)->size = (s)->size;                                                      \
}

/**
 * \def MRLS_DUPLICATE(s, d)
 * Duplicate two arrays of mrls (s = source, d = destination).
 * \sa mrl_t, xine_get_browse_mrls()
 */
#define MRLS_DUPLICATE(s, d) {                                                \
  int i = 0;                                                                  \
                                                                              \
  assert((s) != NULL);                                                        \
  assert((d) != NULL);                                                        \
                                                                              \
  while((s) != NULL) {                                                        \
    d[i] = (mrl_t *) malloc(sizeof(mrl_t));                                   \
    MRL_DUPLICATE(s[i], d[i]);                                                \
    i++;                                                                      \
  }                                                                           \
}

/**
 * \struct mrl_t
 * mrl type.
 * \sa xine_get_browse_mrls(), MRL_ZERO, MRL_DUPLICATE, MRLS_DUPLICATE, mrl_types
 */
typedef struct {
  /** Origin of grabbed mrls (eg: path for file plugin */
  char         *origin;
  /** <type>://<location> */
  char         *mrl;
  /** name of link, if exist, otherwise NULL */
  char         *link;
  /** match to mrl_type enum */
  uint32_t      type;
  /** size of this source, may be 0 */
  off_t         size;
} mrl_t;

/**
 * \fn mrl_t **xine_get_browse_mrls (xine_t *self, char *plugin_id, char *start_mrl, int *num_mrls)
 *  \brief Request available MRLs from plugins
 * \param self Current xine engine configuration ( #see xine_init() )
 * \param plugin_id Plugin name ( #see xine_get_browsable_input_plugin_ids() )
 * \param start_mrl MRL
 * \param num_mrl how many mrls was found
 * \return start_mrl on success, NULL on failure.
 *
 * Asks input plugin named <plugin_id> to return
 * a list of available MRLs in domain/directory <start_mrl>.
 * 
 * <start_mrl> may be NULL indicating the toplevel domain/dir
 * returns <start_mrl> if <start_mrl> is a valid MRL, not a directory
 * returns NULL if <start_mrl> is an invalid MRL, not even a directory.
 */

mrl_t **xine_get_browse_mrls (xine_t *self, char *plugin_id, char *start_mrl, int *num_mrls);

          /** @} end of browse_group */

          /**
	   * \defgroup autoplay_group Autoplay support
	   * @{
	   */
/**
 * \fn char **xine_get_autoplay_input_plugin_ids (xine_t *self)
 * \brief Request playlist from plugin
 * \param self Current xine engine configuration ( #see xine_init() )
 * \return Playlist.
 *
 * Some input plugins can generate autoplay lists
 * returns a list of ids of these plugins.
 */
char **xine_get_autoplay_input_plugin_ids (xine_t *self) ;

/**
 * \fn char **xine_get_autoplay_mrls (xine_t *self, char *plugin_id, int *num_mrls)
 * \brief Request MRL list from plugin
 * \param self Current xine engine configuration ( #see xine_init() )
 * \param plugin_id Plugin name ( #see xine_get_autoplay_input_plugin_ids() )
 * \param num_mrls Entries in return array.
 * \return MRL list.
 *
 * Get autoplay MRL list for input plugin named <plugin_id>.
   */
char **xine_get_autoplay_mrls (xine_t *self, char *plugin_id, int *num_mrls);

          /** @} end of autoplay_group */

          /**
	   * \defgroup loadplugins_group Loading plugins
	   * output plugin load support functions
	   * @{
	   */

/**
 * \def XINE_PLUGINDIR
 * Plugin files location.
 * \ingroup loadplugins_group
 */
#define XINE_PLUGINDIR  "@XINE_PLUGINPATH@"

                /**
		 * \defgroup visual_types Valid visual types
		 * @{
		 */

/**
 * \def VISUAL_TYPE_X11
 * X11 visual type.
 * \sa xine_list_video_output_plugins, xine_load_video_output_plugin
*/
#define VISUAL_TYPE_X11   1
/**
 * \def VISUAL_TYPE_AA
 * Asci Art visual type.
 * \sa xine_list_video_output_plugins, xine_load_video_output_plugin
 */
#define VISUAL_TYPE_AA    2
/**
 * \def VISUAL_TYPE_FB
 * Framebuffer visual type
 * \sa xine_list_video_output_plugins, xine_load_video_output_plugin
 */
#define VISUAL_TYPE_FB    3
/**
 * \def VISUAL_TYPE_GTK
 * GTK visual type
 * \sa xine_list_video_output_plugins, xine_load_video_output_plugin
 */
#define VISUAL_TYPE_GTK   4

               /** @} end of visual_types */

/**
 * \fn char **xine_list_video_output_plugins (int visual_type)
 * \brief list available video output plugins
 * \param visual_type #see @ref visual_types
 * \return a list of available video output plugins for the specified visual type - the list is sorted by plugin priority
 * \sa visual_types
 */
char **xine_list_video_output_plugins (int visual_type);

/**
 * \fn vo_driver_t *xine_load_video_output_plugin(config_values_t *config, char *id, int visual_type, void *visual)
 * \param config current configuration ( #see config_file_init() )
 * \param id driver name.
 * \param visual_type #see @ref visual_types
 * \param visual visual type dependant data pointer.
 * \brief load a specific video output plugin
 * \sa vo_driver_t, visual_types
 */
vo_driver_t *xine_load_video_output_plugin(config_values_t *config,
					   char *id, int visual_type, void *visual);

/**
 * \fn char **xine_list_audio_output_plugins (void)
 * \brief generate a list of all available audio output plugins
 * \return a list of available audio output plugins  the list returned is sorted by plugin priority
 */
char **xine_list_audio_output_plugins (void);

/**
 * \fn ao_driver_t *xine_load_audio_output_plugin(config_values_t *config, char *id)
 * \param config current configuration ( #see config_file_init() )
 * \param id driver name.
 * \brief load a specific audio output plugin.
 * \sa ao_driver_t
 */
ao_driver_t *xine_load_audio_output_plugin(config_values_t *config, char *id);

          /** @} end of loadplugins_group */

          /**
	   * \defgroup event_group Sending events
	   * Event dispatcher mechanism
	   * @{
	   */

#ifdef DOC_HIDDEN
/**
 * Opaque data type.
 * \sa event_listener_t, xine_send_event
 */
typedef void event_t;
#endif

/**
 * Event listener callback.
 * \sa xine_register_event_listener, xine_remove_event_listener
 */
typedef void (*event_listener_t) (xine_t *xine, event_t *event, void *data);

/**
 * \fn int xine_register_event_listener(xine_t *self, event_listener_t listener)
 * \param self Current xine engine configuration ( #see xine_init() )
 * \param listener callback function.
 * \brief registers an event listener callback.
 * \return 0 if the listener was registerd, non-zero if it could not.
 * \sa event_listener_t
 */
int xine_register_event_listener(xine_t *self, event_listener_t listener);

/**
 * \fn int xine_remove_event_listener(xine_t *self, event_listener_t listener)
 * \param self Current xine engine configuration ( #see xine_init() )
 * \param listener callback function.
 * \brief Attempts to remove a registered event listener.
 * \return 0 if the listener was removes, non-zero if it wasn't (e.g. not found).
 * \sa event_listener_t
 */
int xine_remove_event_listener(xine_t *self, event_listener_t listener);

/**
 * \fn void xine_send_event(xine_t *self, event_t *event, void *data)
 * \param self Current xine engine configuration ( #see xine_init() )
 * \param event FILLME
 * \param data FILLME.
 * \brief sends an event to all listeners.
 * \sa event_t
 */
void xine_send_event(xine_t *self, event_t *event, void *data);

          /** @} end of event_group */

     /** @} end of xine_api */

#ifdef __cplusplus
}
#endif

#endif