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.30 2001/07/18 21:38:16 f1rmb Exp $
 *
 */

#ifndef HAVE_XINE_H
#define HAVE_XINE_H

#ifdef __cplusplus
extern "C" {
#endif

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

#include <xine/events.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 */

#define XINE_BUILD_CC "@XINE_BUILD_CC@"
#define XINE_BUILD_OS "@XINE_BUILD_OS@"
#define XINE_BUILD_DATE "@XINE_BUILD_DATE@"

#ifndef DOC_HIDDEN
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);
};

/*
 * video driver capabilities
 */
/* driver can set HUE value */
#define VO_CAP_HUE          0x00000010 /* driver can set HUE value */
#define VO_CAP_SATURATION   0x00000020 /* driver can set SATURATION value */
#define VO_CAP_BRIGHTNESS   0x00000040 /* driver can set BRIGHTNESS value */
#define VO_CAP_CONTRAST     0x00000080 /* driver can set CONTRAST value */
#define VO_CAP_COLORKEY     0x00000100 /* driver can set COLORKEY value */

/*
 * constants for the get/set property functions
 */
#define VO_PROP_INTERLACED      0
#define VO_PROP_ASPECT_RATIO    1
#define VO_PROP_HUE             2
#define VO_PROP_SATURATION      3
#define VO_PROP_CONTRAST        4
#define VO_PROP_BRIGHTNESS      5 
#define VO_PROP_COLORKEY        6 
#define VO_NUM_PROPERTIES       7

/* possible ratios for the VO_PROP_ASPECT_RATIO call */

#define ASPECT_AUTO        0
#define ASPECT_ANAMORPHIC  1 /* 16:9 */
#define ASPECT_FULL        2 /* 4:3  */
#define ASPECT_DVB         3 /* 1:2  */

typedef struct vo_driver_s vo_driver_t;
typedef void vo_frame_t;
typedef void vo_overlay_t;

struct vo_driver_s {

  uint32_t (*get_capabilities) (vo_driver_t *this); /* for constants see above */

  /* 
   * allocate an vo_frame_t struct,
   * the driver must supply the copy, field and dispose functions
   */
  vo_frame_t* (*alloc_frame) (vo_driver_t *this);


  /* 
   * check if the given image fullfills the format specified
   * (re-)allocate memory if necessary
   */
  void (*update_frame_format) (vo_driver_t *this, 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 *this, vo_frame_t *vo_img);

  /* overlay functions */
  void (*overlay_blend) (vo_driver_t *this, vo_frame_t *vo_img, vo_overlay_t *overlay);

  /*
   * these can be used by the gui directly:
   */
  
  int (*get_property) (vo_driver_t *this, int property);
  int (*set_property) (vo_driver_t *this, 
		       int property, int value);
  void (*get_property_min_max) (vo_driver_t *this,
				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 *this, int data_type,
			    void *data);

  void (*exit) (vo_driver_t *this);

};

/** 
 * \brief xine ui callback function pointer types
 * @see xine_init()
 *
 */
typedef void (*gui_stream_end_cb_t)(int nStatus);
typedef char* (*gui_get_next_mrl_cb_t) (void);
typedef void (*gui_branched_cb_t) (void);

/**
 * \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_version API functions
 * @ingroup xine_api
 * @{
 */
/**
 * \fn *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 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 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
 * \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_functions_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 *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);


/**
 * @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) ;

/* Types of mrls returned by get_dir() */
#define mrl_unknown        (0 << 0)
#define mrl_dvd            (1 << 0)
#define mrl_vcd            (1 << 1)
#define mrl_net            (1 << 2)
#define mrl_rtp            (1 << 3)
#define mrl_stdin          (1 << 4)
#define mrl_file           (1 << 5)
#define mrl_file_fifo      (1 << 6)
#define mrl_file_chardev   (1 << 7)
#define mrl_file_directory (1 << 8)
#define mrl_file_blockdev  (1 << 9)
#define mrl_file_normal    (1 << 10)
#define mrl_file_symlink   (1 << 11)
#define mrl_file_sock      (1 << 12)
#define mrl_file_exec      (1 << 13)
#define mrl_file_backup    (1 << 14)
#define mrl_file_hidden    (1 << 15)

/*
 * Freeing/zeroing all of entries of given mrl.
 */
#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;                                                  \
  }                                                                           \
}

/*
 * Duplicate two mrls entries (s = source, d = destination).
 */
#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;                                                      \
}

/*
 * Duplicate two arrays of mrls (s = source, d = destination).
 */
#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++;                                                                      \
  }                                                                           \
}

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

/**
 * \fn mrl_t **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.
 */

mrl_t **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_AA    2
#define VISUAL_TYPE_FB    3
#define VISUAL_TYPE_GTK   4

/**
 * \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 (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_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 */

/**
 * @defgroup eventgroup Sending events
 * Event dispatcher mechanism
 * @{
 */

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

/**
 * \fn xine_register_event_listener(event_listener_t *listener)
 * \brief registers an event listener callback.
 * \return 0 if the listener was registerd, non-zero if it could not.
 */

int xine_register_event_listener(xine_t *this, event_listener_t *listener);

/**
 * \fn xine_remove_event_listener(event_listener_t *listener)
 * \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).
 */

int xine_remove_event_listener(xine_t *this, event_listener_t *listener);

/**
 * \fn xine_send_event(event_t *event)
 * \brief sends an event to all listeners.
 */

void xine_send_event(xine_t *this, event_t *event, void *data);

/** @} end of eventgroup */

#ifdef __cplusplus
}
#endif

#endif