home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2009 April / MAC_easy_04_2009.iso / Software / vlc-0.9.9a.dmg / VLC.app / Contents / MacOS / include / vlc / mediacontrol.h < prev    next >
Encoding:
C/C++ Source or Header  |  2009-04-04  |  11.3 KB  |  343 lines
  1. /*****************************************************************************
  2.  * mediacontrol.h: global header for mediacontrol
  3.  *****************************************************************************
  4.  * Copyright (C) 2005-2008 the VideoLAN team
  5.  * $Id$
  6.  *
  7.  * Authors: Olivier Aubert <olivier.aubert@liris.univ-lyon1.fr>
  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. /**
  25.  * \file
  26.  * This file defines libvlc mediacontrol_* external API
  27.  */
  28.  
  29. /**
  30.  * \defgroup mediacontrol MediaControl
  31.  * This is the MediaControl API, * intended to provide a generic API to movie players.
  32.  *
  33.  * @{
  34.  */
  35.  
  36.  
  37. #ifndef VLC_CONTROL_H
  38. #define VLC_CONTROL_H 1
  39.  
  40. # ifdef __cplusplus
  41. extern "C" {
  42. # endif
  43.  
  44. #if defined( WIN32 )
  45. #include <windows.h>
  46. typedef HWND WINDOWHANDLE;
  47. #else
  48. typedef int WINDOWHANDLE;
  49. #endif
  50.  
  51. #include <vlc/libvlc.h>
  52. #include <vlc/mediacontrol_structures.h>
  53.  
  54. /**
  55.  * mediacontrol_Instance is an opaque structure, defined in
  56.  * mediacontrol_internal.h. API users do not have to mess with it.
  57.  */
  58. typedef struct mediacontrol_Instance mediacontrol_Instance;
  59.  
  60. /**************************************************************************
  61.  *  Helper functions
  62.  ***************************************************************************/
  63.  
  64. /**
  65.  * Free a RGBPicture structure.
  66.  * \param pic: the RGBPicture structure
  67.  */
  68. VLC_PUBLIC_API void mediacontrol_RGBPicture__free( mediacontrol_RGBPicture *pic );
  69.  
  70. VLC_PUBLIC_API void mediacontrol_PlaylistSeq__free( mediacontrol_PlaylistSeq *ps );
  71.  
  72. /**
  73.  * Free a StreamInformation structure.
  74.  * \param pic: the StreamInformation structure
  75.  */
  76. VLC_PUBLIC_API void
  77. mediacontrol_StreamInformation__free( mediacontrol_StreamInformation* p_si );
  78.  
  79. /**
  80.  * Instanciate and initialize an exception structure.
  81.  * \return the exception
  82.  */
  83. VLC_PUBLIC_API mediacontrol_Exception *
  84.   mediacontrol_exception_create( void );
  85.  
  86. /**
  87.  * Initialize an existing exception structure.
  88.  * \param p_exception the exception to initialize.
  89.  */
  90. VLC_PUBLIC_API void
  91.   mediacontrol_exception_init( mediacontrol_Exception *exception );
  92.  
  93. /**
  94.  * Clean up an existing exception structure after use.
  95.  * \param p_exception the exception to clean up.
  96.  */
  97. VLC_PUBLIC_API void
  98. mediacontrol_exception_cleanup( mediacontrol_Exception *exception );
  99.  
  100. /**
  101.  * Free an exception structure created with mediacontrol_exception_create().
  102.  * \return the exception
  103.  */
  104. VLC_PUBLIC_API void mediacontrol_exception_free(mediacontrol_Exception *exception);
  105.  
  106. /*****************************************************************************
  107.  * Core functions
  108.  *****************************************************************************/
  109.  
  110. /**
  111.  * Create a MediaControl instance with parameters
  112.  * \param argc the number of arguments
  113.  * \param argv parameters
  114.  * \param exception an initialized exception pointer
  115.  * \return a mediacontrol_Instance
  116.  */
  117. VLC_PUBLIC_API mediacontrol_Instance *
  118. mediacontrol_new( int argc, char **argv, mediacontrol_Exception *exception );
  119.  
  120. /**
  121.  * Create a MediaControl instance from an existing libvlc instance
  122.  * \param p_instance the libvlc instance
  123.  * \param exception an initialized exception pointer
  124.  * \return a mediacontrol_Instance
  125.  */
  126. VLC_PUBLIC_API mediacontrol_Instance *
  127. mediacontrol_new_from_instance( libvlc_instance_t* p_instance,
  128.                 mediacontrol_Exception *exception );
  129.  
  130. /**
  131.  * Get the associated libvlc instance
  132.  * \param self: the mediacontrol instance
  133.  * \return a libvlc instance
  134.  */
  135. VLC_PUBLIC_API libvlc_instance_t*
  136. mediacontrol_get_libvlc_instance( mediacontrol_Instance* self );
  137.  
  138. /**
  139.  * Get the associated libvlc_media_player
  140.  * \param self: the mediacontrol instance
  141.  * \return a libvlc_media_player_t instance
  142.  */
  143. VLC_PUBLIC_API libvlc_media_player_t*
  144. mediacontrol_get_media_player( mediacontrol_Instance* self );
  145.  
  146. /**
  147.  * Get the current position
  148.  * \param self the mediacontrol instance
  149.  * \param an_origin the position origin
  150.  * \param a_key the position unit
  151.  * \param exception an initialized exception pointer
  152.  * \return a mediacontrol_Position
  153.  */
  154. VLC_PUBLIC_API mediacontrol_Position * mediacontrol_get_media_position(
  155.                          mediacontrol_Instance *self,
  156.                          const mediacontrol_PositionOrigin an_origin,
  157.                          const mediacontrol_PositionKey a_key,
  158.                          mediacontrol_Exception *exception );
  159.  
  160. /**
  161.  * Set the position
  162.  * \param self the mediacontrol instance
  163.  * \param a_position a mediacontrol_Position
  164.  * \param exception an initialized exception pointer
  165.  */
  166. VLC_PUBLIC_API void mediacontrol_set_media_position( mediacontrol_Instance *self,
  167.                                       const mediacontrol_Position *a_position,
  168.                                       mediacontrol_Exception *exception );
  169.  
  170. /**
  171.  * Play the movie at a given position
  172.  * \param self the mediacontrol instance
  173.  * \param a_position a mediacontrol_Position
  174.  * \param exception an initialized exception pointer
  175.  */
  176. VLC_PUBLIC_API void mediacontrol_start( mediacontrol_Instance *self,
  177.                          const mediacontrol_Position *a_position,
  178.                          mediacontrol_Exception *exception );
  179.  
  180. /**
  181.  * Pause the movie at a given position
  182.  * \param self the mediacontrol instance
  183.  * \param exception an initialized exception pointer
  184.  */
  185. VLC_PUBLIC_API void mediacontrol_pause( mediacontrol_Instance *self,
  186.                          mediacontrol_Exception *exception );
  187.  
  188. /**
  189.  * Resume the movie at a given position
  190.  * \param self the mediacontrol instance
  191.  * \param exception an initialized exception pointer
  192.  */
  193. VLC_PUBLIC_API void mediacontrol_resume( mediacontrol_Instance *self,
  194.                           mediacontrol_Exception *exception );
  195.  
  196. /**
  197.  * Stop the movie at a given position
  198.  * \param self the mediacontrol instance
  199.  * \param exception an initialized exception pointer
  200.  */
  201. VLC_PUBLIC_API void mediacontrol_stop( mediacontrol_Instance *self,
  202.                         mediacontrol_Exception *exception );
  203.  
  204. /**
  205.  * Exit the player
  206.  * \param self the mediacontrol instance
  207.  */
  208. VLC_PUBLIC_API void mediacontrol_exit( mediacontrol_Instance *self );
  209.  
  210. /**
  211.  * Set the MRL to be played.
  212.  * \param self the mediacontrol instance
  213.  * \param psz_file the MRL
  214.  * \param exception an initialized exception pointer
  215.  */
  216. VLC_PUBLIC_API void mediacontrol_set_mrl( mediacontrol_Instance *self,
  217.                                      const char* psz_file,
  218.                                      mediacontrol_Exception *exception );
  219.  
  220. /**
  221.  * Get the MRL to be played.
  222.  * \param self the mediacontrol instance
  223.  * \param exception an initialized exception pointer
  224.  */
  225. VLC_PUBLIC_API char * mediacontrol_get_mrl( mediacontrol_Instance *self,
  226.                                             mediacontrol_Exception *exception );
  227.  
  228. /*****************************************************************************
  229.  * A/V functions
  230.  *****************************************************************************/
  231. /**
  232.  * Get a snapshot
  233.  * \param self the mediacontrol instance
  234.  * \param a_position the desired position (ignored for now)
  235.  * \param exception an initialized exception pointer
  236.  * \return a RGBpicture
  237.  */
  238. VLC_PUBLIC_API mediacontrol_RGBPicture *
  239.   mediacontrol_snapshot( mediacontrol_Instance *self,
  240.                          const mediacontrol_Position *a_position,
  241.                          mediacontrol_Exception *exception );
  242.  
  243. /**
  244.  *  Displays the message string, between "begin" and "end" positions.
  245.  * \param self the mediacontrol instance
  246.  * \param message the message to display
  247.  * \param begin the begin position
  248.  * \param end the end position
  249.  * \param exception an initialized exception pointer
  250.  */
  251. VLC_PUBLIC_API void mediacontrol_display_text( mediacontrol_Instance *self,
  252.                                 const char *message,
  253.                                 const mediacontrol_Position *begin,
  254.                                 const mediacontrol_Position *end,
  255.                                 mediacontrol_Exception *exception );
  256.  
  257. /**
  258.  *  Get information about a stream
  259.  * \param self the mediacontrol instance
  260.  * \param a_key the time unit
  261.  * \param exception an initialized exception pointer
  262.  * \return a mediacontrol_StreamInformation
  263.  */
  264. VLC_PUBLIC_API mediacontrol_StreamInformation *
  265.   mediacontrol_get_stream_information( mediacontrol_Instance *self,
  266.                                        mediacontrol_PositionKey a_key,
  267.                                        mediacontrol_Exception *exception );
  268.  
  269. /**
  270.  * Get the current audio level, normalized in [0..100]
  271.  * \param self the mediacontrol instance
  272.  * \param exception an initialized exception pointer
  273.  * \return the volume
  274.  */
  275. VLC_PUBLIC_API unsigned short
  276.   mediacontrol_sound_get_volume( mediacontrol_Instance *self,
  277.                                  mediacontrol_Exception *exception );
  278. /**
  279.  * Set the audio level
  280.  * \param self the mediacontrol instance
  281.  * \param volume the volume (normalized in [0..100])
  282.  * \param exception an initialized exception pointer
  283.  */
  284. VLC_PUBLIC_API void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
  285.                                     const unsigned short volume,
  286.                                     mediacontrol_Exception *exception );
  287.  
  288. /**
  289.  * Set the video output window
  290.  * \param self the mediacontrol instance
  291.  * \param visual_id the Xid or HWND, depending on the platform
  292.  * \param exception an initialized exception pointer
  293.  */
  294. VLC_PUBLIC_API int mediacontrol_set_visual( mediacontrol_Instance *self,
  295.                                     WINDOWHANDLE visual_id,
  296.                                     mediacontrol_Exception *exception );
  297.  
  298. /**
  299.  * Get the current playing rate, in percent
  300.  * \param self the mediacontrol instance
  301.  * \param exception an initialized exception pointer
  302.  * \return the rate
  303.  */
  304. VLC_PUBLIC_API int mediacontrol_get_rate( mediacontrol_Instance *self,
  305.                mediacontrol_Exception *exception );
  306.  
  307. /**
  308.  * Set the playing rate, in percent
  309.  * \param self the mediacontrol instance
  310.  * \param rate the desired rate
  311.  * \param exception an initialized exception pointer
  312.  */
  313. VLC_PUBLIC_API void mediacontrol_set_rate( mediacontrol_Instance *self,
  314.                 const int rate,
  315.                 mediacontrol_Exception *exception );
  316.  
  317. /**
  318.  * Get current fullscreen status
  319.  * \param self the mediacontrol instance
  320.  * \param exception an initialized exception pointer
  321.  * \return the fullscreen status
  322.  */
  323. VLC_PUBLIC_API int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
  324.                  mediacontrol_Exception *exception );
  325.  
  326. /**
  327.  * Set fullscreen status
  328.  * \param self the mediacontrol instance
  329.  * \param b_fullscreen the desired status
  330.  * \param exception an initialized exception pointer
  331.  */
  332. VLC_PUBLIC_API void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
  333.                   const int b_fullscreen,
  334.                   mediacontrol_Exception *exception );
  335.  
  336. # ifdef __cplusplus
  337. }
  338. # endif
  339.  
  340. #endif
  341.  
  342. /** @} */
  343.