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 2000-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.10 2001/04/27 23:51:52 guenter Exp $
 *
 */

#ifndef HAVE_XINE_H
#define HAVE_XINE_H

#include <inttypes.h>

/** 
 * \defgroup versgroup Version constants 
 * @{
 */
/** \brief Major version constant */
#define XINE_MAJOR_VERSION @XINE_MAJOR@
/** \brief Minor version constant */
#define XINE_MINOR_VERSION @XINE_MINOR@
/** \brief Sub version constant */
#define XINE_SUB_VERSION   @XINE_SUB@
/** @} end of versgroup */

#ifndef DOC_HIDDEN
typedef void vo_driver_t;
typedef void ao_functions_t;
typedef void xine_t;
#endif

typedef struct config_values_s config_values_t;

struct config_values_s {
  /*
   * lookup config values
   */
  char* (*lookup_str) (config_values_t *this,
		       char *key, char *str_default);
  
  int (*lookup_int) (config_values_t *this,
		     char *key, int n_default);
  
  /*
   * set config values
   */
  
  void (*set_str) (config_values_t *this,
		   char *key, char *value) ;
  
  void (*set_int) (config_values_t *this,
		   char *key, int value) ;
  
  /*
   * write config file to disk
   */
  void (*save) (config_values_t *this);

  /*
   * read config file from disk, ovverriding values in memory
   * if you also want to clear values that are not in the file,
   * use _init instead!
   */
  void (*read) (config_values_t *this, char *filename);
};

/** 
 * \brief Current xine status function type
 * \param nStatus Current status
 * @see xine_init()
 *
 * This type define the callback function that
 * UI should implement.
 */
typedef void (*gui_status_callback_func_t)(int nStatus);

/**
 * \defgroup statgroup Player status constants
 * @{
 */
/** \brief Stop status 
 * @see xine_get_status()
 */
#define XINE_STOP      0
/** \brief Play status
 * @see xine_get_status()
 */
#define XINE_PLAY      1
/** \brief Pause status
 * @see xine_get_status()
 */
#define XINE_PAUSE     2
/** \brief Quit status
 * @see xine_get_status()
 */
#define XINE_QUIT      3
/** @} end of statgroup */

#define DEMUX_DEFAULT_STRATEGY    0
#define DEMUX_REVERT_STRATEGY     1
#define DEMUX_CONTENT_STRATEGY    2
#define DEMUX_EXTENSION_STRATEGY  3

/**
 * @defgroup xine_api API functions
 * @{
 */
/** @defgroup xine_init_api Init functions
 * @ingroup xine_api
 * @{
 */
/**
 * \fn config_values_t *config_file_init (char *filename)
 * \brief Configuration file initialisation.
 * \param filename Pathname of configuration file.
 * \return Current config
 *
 * Read config file and init a config object * (if it exists)
 */
config_values_t *config_file_init (char *filename);

/**
 * \fn xine_t *xine_init (vo_driver_t *vo, ao_functions_t *ao, gui_status_callback_func_t gui_status_callback, config_values_t *config)
 * \brief Initialisation of xine.
 * \param vo Video driver ( should be previously initialized by vo_init() )
 * \param ao Audio driver ( should be previously initializef by ao_init() )
 * \param gui_status_callback Pointer to UI function ( #see gui_status_callback_func_t() function type )
 * \param config Current configuration ( #see config_file_init() )
 * \return Current xine engine configuration
 * \warning This function should be called before any of xine_*() functions.
 *
 * Init of xine. It should called once at startup.
 *
 */
xine_t *xine_init (vo_driver_t *vo, 
		   ao_functions_t *ao,
		   gui_status_callback_func_t gui_status_callback,
		   config_values_t *config) ;

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

/** @} end of xine_init_api */

/**
 * @defgroup xine_management_api Engine management
 * @ingroup xine_api
 * @{
 */
/**
 * \fn void xine_play (xine_t *this, char *MRL, int pos)
 * \brief Start to play a stream
 * \param this Current xine engine configuration ( #see xine_init() )
 * \param MRL Media Resource Location to open
 * \param pos Start from position (0..65535)
 * \return Nothing
 *
 * Open a stream and play it
 *
 */
void xine_play (xine_t *this, char *MRL, int pos);


/**
 * \fn void xine_pause (xine_t *this)
 * \brief Pause toggle
 * \param this Current xine engine configuration ( #see xine_init() )
 * \return Nothing
 *
 * Toggle pause mode.
 */
void xine_pause (xine_t *this);


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

/**
 * \fn int xine_eject(xine_t *this)
 * \brief Eject media
 * \param this 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 *this);

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

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

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

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

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

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

/** @} end of xine_management_api */

/**
 * @defgroup browsegroup Browsing support
 * @ingroup xine_api
 * @{
 */
/**
 * \fn char **xine_get_browsable_input_plugin_ids (xine_t *this)
 * \brief Request list of browsable featured plugins
 * \param this 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 *this) ;

/**
 * \fn char **xine_get_browse_mrls (xine_t *this, char *plugin_id, char *start_mrl)
 * \brief Request available MRLs from plugins
 * \param this Current xine engine configuration ( #see xine_init() )
 * \param plugin_id Plugin name ( #see xine_get_browsable_input_plugin_ids() )
 * \param start_mrl MRL
 * \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.
 */

char **xine_get_browse_mrls (xine_t *this, char *plugin_id, 
			     char *start_mrl);

/** @} end of browsegroup*/

/**
 * @defgroup autoplaygroup Autoplay support
 * @{
 */
/**
 * \fn char **xine_get_autoplay_input_plugin_ids (xine_t *this)
 * \brief Request playlist from plugin
 * \param this 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 *this) ;

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

/** @} end of autoplaygroup */

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

#define VISUAL_TYPE_X11   1
#define VISUAL_TYPE_FB    2
#define VISUAL_TYPE_GTK   3

/**
 * \fn char **list_video_output_plugins (int visual_type)
 * \brief list available video output plugins
 * \return a list of available video output plugins for the specified visual type - the list is sorted by plugin priority
 */
char **xine_list_video_output_plugins (int visual_type);

/**
 * \fn vo_driver_t *load_video_output_plugin(config_values_t *config, char *id, int visual_type, void *visual)
 * \brief load a specific video output plugin
 */
vo_driver_t *xine_load_video_output_plugin(config_values_t *config,
					      char *id, int visual_type, void *visual);

/**
 * \fn char **list_audio_output_plugins ()
 * \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 ();

/**
 * \fn ao_functions_t *load_audio_output_plugin(config_values_t *config, char *id)
 * \brief load a specific audio output plugin
 */

ao_functions_t *xine_load_audio_output_plugin(config_values_t *config, char *id);

/** @} end of loadpluginsgroup */

#define XINE_PLUGINDIR  "@XINE_PLUGINPATH@"
#define XINE_SKINDIR    "@XINE_SKINPATH@"

/** @} end of xine_api */

#endif