Commit 8b586997 authored by sam's avatar sam

Documentation updates.

Made the Doxygen headers slightly clearer when directly read from the
header file, fixed grammar and spelling here and there, added some
missing \param and \return tags (though a lot remains to be done).
parent 4e0e4d6d
......@@ -50,24 +50,28 @@ extern "C" {
*/
/**
* Initialize an exception structure. This can be called several times to reuse
* an exception structure.
* Initialize an exception structure. This can be called several times to
* reuse an exception structure.
*
* \param p_exception the exception to initialize
*/
VLC_PUBLIC_API void libvlc_exception_init( libvlc_exception_t *p_exception );
/**
* Has an exception been raised ?
* Has an exception been raised?
*
* \param p_exception the exception to query
* \return 0 if no exception raised, 1 else
* \return 0 if the exception was raised, 1 otherwise
*/
VLC_PUBLIC_API int
libvlc_exception_raised( const libvlc_exception_t *p_exception );
/**
* Raise an exception
* Raise an exception using a user-provided message.
*
* \param p_exception the exception to raise
* \param psz_message the exception message
* \param psz_message the exception message format string
* \param ... the format string arguments
*/
VLC_PUBLIC_API void
libvlc_exception_raise( libvlc_exception_t *p_exception,
......@@ -75,16 +79,18 @@ libvlc_exception_raise( libvlc_exception_t *p_exception,
/**
* Clear an exception object so it can be reused.
* The exception object must be initialized
* The exception object must have be initialized.
*
* \param p_exception the exception to clear
*/
VLC_PUBLIC_API void libvlc_exception_clear( libvlc_exception_t * );
/**
* Get exception message
* Get an exception's message.
*
* \param p_exception the exception to query
* \return the exception message or NULL if not applicable (exception not raised
* for example)
* \return the exception message or NULL if not applicable (exception not
* raised, for example)
*/
VLC_PUBLIC_API const char *
libvlc_exception_get_message( const libvlc_exception_t *p_exception );
......@@ -102,32 +108,40 @@ libvlc_exception_get_message( const libvlc_exception_t *p_exception );
*/
/**
* Create an initialized libvlc instance.
* Create and initialize a libvlc instance.
*
* \param argc the number of arguments
* \param argv command-line-type arguments (argv[0] must be the path of calling program)
* \param exception an initialized exception pointer
* \param argv command-line-type arguments. argv[0] must be the path of the
* calling program.
* \param p_e an initialized exception pointer
* \return the libvlc instance
*/
VLC_PUBLIC_API libvlc_instance_t *
libvlc_new( int , const char *const *, libvlc_exception_t *);
/**
* Returns a libvlc instance identifier for legacy APIs. Use of this
* Return a libvlc instance identifier for legacy APIs. Use of this
* function is discouraged, you should convert your program to use the
* new API.
*
* \param p_instance the instance
* \return the instance identifier
*/
VLC_PUBLIC_API int libvlc_get_vlc_id( libvlc_instance_t *p_instance );
/**
* Decrements the reference count of a libvlc instance, and destroys it
* Decrement the reference count of a libvlc instance, and destroy it
* if it reaches zero.
*
* \param p_instance the instance to destroy
*/
VLC_PUBLIC_API void libvlc_release( libvlc_instance_t * );
/**
* Increments the reference count of a libvlc instance.
* The reference count is initially one when libvlc_new() returns.
* The initial reference count is 1 after libvlc_new() returns.
*
* \param p_instance the instance to reference
*/
VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t * );
......@@ -143,9 +157,12 @@ VLC_PUBLIC_API void libvlc_retain( libvlc_instance_t * );
*/
/**
* Create a media descriptor with the given mrl.
* Create a media descriptor with the given MRL.
*
* \param p_instance the instance
* \param psz_mrl the mrl to read
* \param psz_mrl the MRL to read
* \param p_e an initialized exception pointer
* \return the newly created media descriptor
*/
VLC_PUBLIC_API libvlc_media_descriptor_t * libvlc_media_descriptor_new(
libvlc_instance_t *p_instance,
......@@ -154,8 +171,11 @@ VLC_PUBLIC_API libvlc_media_descriptor_t * libvlc_media_descriptor_new(
/**
* Create a media descriptor as an empty node with the passed name.
*
* \param p_instance the instance
* \param psz_name the name of the node
* \param p_e an initialized exception pointer
* \return the new empty media descriptor
*/
VLC_PUBLIC_API libvlc_media_descriptor_t * libvlc_media_descriptor_new_as_node(
libvlc_instance_t *p_instance,
......@@ -163,14 +183,17 @@ VLC_PUBLIC_API libvlc_media_descriptor_t * libvlc_media_descriptor_new_as_node(
libvlc_exception_t *p_e );
/**
* Add an option to the media descriptor,
* Add an option to the media descriptor.
*
* This option will be used to determine how the media_instance will
* read the media_descriptor. This allow to use VLC advanced
* reading/streaming options in a per-media basis.
* read the media_descriptor. This allows to use VLC's advanced
* reading/streaming options on a per-media basis.
*
* The options are detailed in vlc --long-help, for instance "--sout-all"
*
* The options are detailled in vlc --long-help, for instance "--sout-all"
* \param p_instance the instance
* \param psz_mrl the mrl to read
* \param psz_mrl the MRL to read
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_media_descriptor_add_option(
libvlc_media_descriptor_t * p_md,
......@@ -190,8 +213,11 @@ VLC_PUBLIC_API libvlc_media_descriptor_t * libvlc_media_descriptor_duplicate( li
/**
* Read the meta of the media descriptor.
*
* \param p_meta_desc the media descriptor to read
* \param p_meta_desc the meta to read
* \param p_e an initialized exception pointer
* \return the media descriptor's meta
*/
VLC_PUBLIC_API char * libvlc_media_descriptor_get_meta(
libvlc_media_descriptor_t *p_meta_desc,
......@@ -260,106 +286,139 @@ VLC_PUBLIC_API void *
*/
/**
* Set loop variable
* Set the playlist's loop attribute. If set, the playlist runs continuously
* and wraps around when it reaches the end.
*
* \param p_instance the playlist instance
* \param loop the loop attribute. 1 sets looping, 0 disables it
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_playlist_loop( libvlc_instance_t* , int,
libvlc_exception_t * );
/**
* Start playing. You can give some additionnal playlist item options
* that will be added to the item before playing it.
* \param p_instance the instance
* Start playing.
*
* Additionnal playlist item options can be specified for addition to the
* item before it is played.
*
* \param p_instance the playlist instance
* \param i_id the item to play. If this is a negative number, the next
* item will be selected. Else, the item with the given ID will be played
* item will be selected. Otherwise, the item with the given ID will be
* played
* \param i_options the number of options to add to the item
* \param ppsz_options the options to add to the item
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_playlist_play( libvlc_instance_t*, int, int, char **,
libvlc_exception_t * );
VLC_PUBLIC_API void libvlc_playlist_play( libvlc_instance_t*, int, int,
char **, libvlc_exception_t * );
/**
* Pause a running playlist, resume if it was stopped
* \param p_instance the instance to pause
* \param p_exception an initialized exception
* Toggle the playlist's pause status.
*
* If the playlist was running, it is paused. If it was paused, it is resumed.
*
* \param p_instance the playlist instance to pause
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_playlist_pause( libvlc_instance_t *, libvlc_exception_t * );
VLC_PUBLIC_API void libvlc_playlist_pause( libvlc_instance_t *,
libvlc_exception_t * );
/**
* Checks if the playlist is running
* \param p_instance the instance
* \param p_exception an initialized exception
* Checks whether the playlist is running
*
* \param p_instance the playlist instance
* \param p_e an initialized exception pointer
* \return 0 if the playlist is stopped or paused, 1 if it is running
*/
VLC_PUBLIC_API int libvlc_playlist_isplaying( libvlc_instance_t *, libvlc_exception_t * );
VLC_PUBLIC_API int libvlc_playlist_isplaying( libvlc_instance_t *,
libvlc_exception_t * );
/**
* Get the number of items in the playlist
* \param p_instance the instance
* \param p_exception an initialized exception
*
* \param p_instance the playlist instance
* \param p_e an initialized exception pointer
* \return the number of items
*/
VLC_PUBLIC_API int libvlc_playlist_items_count( libvlc_instance_t *, libvlc_exception_t * );
VLC_PUBLIC_API int libvlc_playlist_items_count( libvlc_instance_t *,
libvlc_exception_t * );
/**
* Lock the playlist instance
* \param p_instance the instance
* Lock the playlist.
*
* \param p_instance the playlist instance
*/
VLC_PUBLIC_API void libvlc_playlist_lock( libvlc_instance_t * );
/**
* Unlock the playlist instance
* \param p_instance the instance
* Unlock the playlist.
*
* \param p_instance the playlist instance
*/
VLC_PUBLIC_API void libvlc_playlist_unlock( libvlc_instance_t * );
/**
* Stop playing
* \param p_instance the instance to stop
* \param p_exception an initialized exception
* Stop playing.
*
* \param p_instance the playlist instance to stop
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_playlist_stop( libvlc_instance_t *, libvlc_exception_t * );
VLC_PUBLIC_API void libvlc_playlist_stop( libvlc_instance_t *,
libvlc_exception_t * );
/**
* Go to next playlist item (starts playback if it was stopped)
* \param p_instance the instance to use
* \param p_exception an initialized exception
* Go to the next playlist item. If the playlist was stopped, playback
* is started.
*
* \param p_instance the playlist instance
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_playlist_next( libvlc_instance_t *, libvlc_exception_t * );
VLC_PUBLIC_API void libvlc_playlist_next( libvlc_instance_t *,
libvlc_exception_t * );
/**
* Go to previous playlist item (starts playback if it was stopped)
* \param p_instance the instance to use
* \param p_exception an initialized exception
* Go to the previous playlist item. If the playlist was stopped, playback
* is started.
*
* \param p_instance the playlist instance
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_playlist_prev( libvlc_instance_t *, libvlc_exception_t * );
VLC_PUBLIC_API void libvlc_playlist_prev( libvlc_instance_t *,
libvlc_exception_t * );
/**
* Remove all playlist items
* \param p_instance the instance
* \param p_exception an initialized exception
* Empty a playlist. All items in the playlist are removed.
*
* \param p_instance the playlist instance
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_playlist_clear( libvlc_instance_t *, libvlc_exception_t * );
VLC_PUBLIC_API void libvlc_playlist_clear( libvlc_instance_t *,
libvlc_exception_t * );
/**
* Add an item at the end of the playlist
* If you need more advanced options, \see libvlc_playlist_add_extended
* \param p_instance the instance
* Append an item to the playlist. The item is added at the end. If more
* advanced options are required, \see libvlc_playlist_add_extended instead.
*
* \param p_instance the playlist instance
* \param psz_uri the URI to open, using VLC format
* \param psz_name a name that you might want to give or NULL
* \param p_e an initialized exception pointer
* \return the identifier of the new item
*/
VLC_PUBLIC_API int libvlc_playlist_add( libvlc_instance_t *, const char *, const char *,
libvlc_exception_t * );
VLC_PUBLIC_API int libvlc_playlist_add( libvlc_instance_t *, const char *,
const char *, libvlc_exception_t * );
/**
* Add an item at the end of the playlist, with additional input options
* \param p_instance the instance
* Append an item to the playlist. The item is added at the end, with
* additional input options.
*
* \param p_instance the playlist instance
* \param psz_uri the URI to open, using VLC format
* \param psz_name a name that you might want to give or NULL
* \param i_options the number of options to add
* \param ppsz_options strings representing the options to add
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
* \return the identifier of the new item
*/
VLC_PUBLIC_API int libvlc_playlist_add_extended( libvlc_instance_t *, const char *,
......@@ -368,18 +427,20 @@ VLC_PUBLIC_API int libvlc_playlist_add_extended( libvlc_instance_t *, const char
/**
* Delete the playlist item with the given ID.
* \param p_instance the instance
*
* \param p_instance the playlist instance
* \param i_id the id to remove
* \param p_exception an initialized exception
* \return
* \param p_e an initialized exception pointer
* \return 0 in case of success, a non-zero value otherwise
*/
VLC_PUBLIC_API int libvlc_playlist_delete_item( libvlc_instance_t *, int,
libvlc_exception_t * );
/** Get the input that is currently being played by the playlist
* \param p_instance the instance to use
* \param p_exception an initialized excecption
* \return an input object
/** Get the input that is currently being played by the playlist.
*
* \param p_instance the playlist instance to use
* \param p_e an initialized exception pointern
* \return a media instance object
*/
VLC_PUBLIC_API libvlc_media_instance_t * libvlc_playlist_get_media_instance(
libvlc_instance_t *, libvlc_exception_t * );
......@@ -404,14 +465,17 @@ VLC_PUBLIC_API int libvlc_media_instance_can_pause(
*/
/** Create an empty Media Instance object
*
* \param p_libvlc_instance the libvlc instance in which the Media Instance
* should be (not used for now).
* should be (unused for now).
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API libvlc_media_instance_t * libvlc_media_instance_new( libvlc_instance_t *, libvlc_exception_t * );
/** Create a Media Instance object from a Media Descriptor
* \param p_md the media descriptor. Afterwards the p_md can safely be
* destroyed.
* \param p_md the media descriptor. Afterwards the p_md can be safely
* destroyed.
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API libvlc_media_instance_t * libvlc_media_instance_new_from_media_descriptor( libvlc_media_descriptor_t *, libvlc_exception_t * );
......@@ -423,20 +487,26 @@ VLC_PUBLIC_API void libvlc_media_instance_retain( libvlc_media_instance_t * );
/** Set the media descriptor that will be used by the media_instance. If any,
* previous md will be released.
*
* \param p_mi the Media Instance
* \param p_md the Media Descriptor. Afterwards the p_md can safely be
* destroyed.
* \param p_md the Media Descriptor. Afterwards the p_md can be safely
* destroyed.
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_media_instance_set_media_descriptor( libvlc_media_instance_t *, libvlc_media_descriptor_t *, libvlc_exception_t * );
/** Get the media descriptor used by the media_instance (if any). A copy of
* the md is returned. NULL is returned if no media instance is associated.
*
* \param p_mi the Media Instance
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API libvlc_media_descriptor_t * libvlc_media_instance_get_media_descriptor( libvlc_media_instance_t *, libvlc_exception_t * );
/** Get the Event Manager from which the media instance send event.
*
* \param p_mi the Media Instance
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API libvlc_event_manager_t * libvlc_media_instance_event_manager ( libvlc_media_instance_t *, libvlc_exception_t * );
......@@ -463,9 +533,10 @@ VLC_PUBLIC_API void libvlc_media_instance_set_rate ( libvlc_media
VLC_PUBLIC_API libvlc_state_t libvlc_media_instance_get_state ( libvlc_media_instance_t *, libvlc_exception_t *);
/**
* Does this input have a video output ?
* Does this input have a video output?
*
* \param p_input the input
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API int libvlc_media_instance_has_vout( libvlc_media_instance_t *, libvlc_exception_t *);
VLC_PUBLIC_API float libvlc_media_instance_get_fps( libvlc_media_instance_t *, libvlc_exception_t *);
......@@ -776,191 +847,219 @@ VLC_PUBLIC_API void
*/
/**
* Toggle fullscreen status on video output
* Toggle fullscreen status on video output.
*
* \param p_input the input
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_toggle_fullscreen( libvlc_media_instance_t *, libvlc_exception_t * );
/**
* Enable or disable fullscreen on a video output
* Enable or disable fullscreen on a video output.
*
* \param p_input the input
* \param b_fullscreen boolean for fullscreen status
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_set_fullscreen( libvlc_media_instance_t *, int, libvlc_exception_t * );
/**
* Get current fullscreen status
* Get current fullscreen status.
*
* \param p_input the input
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
* \return the fullscreen status (boolean)
*/
VLC_PUBLIC_API int libvlc_get_fullscreen( libvlc_media_instance_t *, libvlc_exception_t * );
/**
* Get current video height
* Get current video height.
*
* \param p_input the input
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
* \return the video height
*/
VLC_PUBLIC_API int libvlc_video_get_height( libvlc_media_instance_t *, libvlc_exception_t * );
/**
* Get current video width
* Get current video width.
*
* \param p_input the input
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
* \return the video width
*/
VLC_PUBLIC_API int libvlc_video_get_width( libvlc_media_instance_t *, libvlc_exception_t * );
/**
* Get current video aspect ratio
* Get current video aspect ratio.
*
* \param p_input the input
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
* \return the video aspect ratio
*/
VLC_PUBLIC_API char *libvlc_video_get_aspect_ratio( libvlc_media_instance_t *, libvlc_exception_t * );
/**
* Set new video aspect ratio
* Set new video aspect ratio.
*
* \param p_input the input
* \param psz_aspect new video aspect-ratio
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_video_set_aspect_ratio( libvlc_media_instance_t *, char *, libvlc_exception_t * );
/**
* Get current video subtitle
* Get current video subtitle.
*
* \param p_input the input
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
* \return the video subtitle selected
*/
VLC_PUBLIC_API int libvlc_video_get_spu( libvlc_media_instance_t *, libvlc_exception_t * );
/**
* Set new video subtitle
* Set new video subtitle.
*
* \param p_input the input
* \param i_spu new video subtitle to select
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_video_set_spu( libvlc_media_instance_t *, int , libvlc_exception_t * );
/**
* Get current crop filter geometry
* Get current crop filter geometry.
*
* \param p_input the input
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
* \return the crop filter geometry
*/
VLC_PUBLIC_API char *libvlc_video_get_crop_geometry( libvlc_media_instance_t *, libvlc_exception_t * );
/**
* Set new crop filter geometry
* Set new crop filter geometry.
*
* \param p_input the input
* \param psz_geometry new crop filter geometry
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_video_set_crop_geometry( libvlc_media_instance_t *, char *, libvlc_exception_t * );
/**
* Toggle teletext transparent status on video output
* Toggle teletext transparent status on video output.
*
* \param p_input the input
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_toggle_teletext( libvlc_media_instance_t *, libvlc_exception_t * );
/**
* Get current teletext page requested.
*
* \param p_input the input
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
* \return the current teletext page requested.
*/
VLC_PUBLIC_API int libvlc_video_get_teletext( libvlc_media_instance_t *, libvlc_exception_t * );
/**
* Set new teletext page to retrieve
* Set new teletext page to retrieve.
*
* \param p_input the input
* \param i_page teletex page number requested
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_video_set_teletext( libvlc_media_instance_t *, int, libvlc_exception_t * );
/**
* Take a snapshot of the current video window
* If i_width AND i_height is 0, original size is used
* if i_width XOR i_height is 0, original aspect-ratio is preserved
* Take a snapshot of the current video window.
*
* If i_width AND i_height is 0, original size is used.
* If i_width XOR i_height is 0, original aspect-ratio is preserved.
*
* \param p_input the input
* \param psz_filepath the path where to save the screenshot to
* \param i_width the snapshot's width
* \param i_height the snapshot's height
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_video_take_snapshot( libvlc_media_instance_t *, char *,unsigned int, unsigned int, libvlc_exception_t * );
VLC_PUBLIC_API int libvlc_video_destroy( libvlc_media_instance_t *, libvlc_exception_t *);
/**
* Resize the current video output window
* Resize the current video output window.
*
* \param p_instance libvlc instance
* \param width new width for video output window
* \param height new height for video output window
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
* \return the success status (boolean)
*/
VLC_PUBLIC_API void libvlc_video_resize( libvlc_media_instance_t *, int, int, libvlc_exception_t *);
/**
* change the parent for the current the video output
* Change the parent for the current the video output.
*
* \param p_instance libvlc instance
* \param drawable the new parent window (Drawable on X11, CGrafPort on MacOSX, HWND on Win32)
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
* \return the success status (boolean)
*/
VLC_PUBLIC_API int libvlc_video_reparent( libvlc_media_instance_t *, libvlc_drawable_t, libvlc_exception_t * );
/**
* Tell windowless video output to redraw rectangular area (MacOS X only)
* Tell windowless video output to redraw rectangular area (MacOS X only).
*
* \param p_instance libvlc instance
* \param area coordinates within video drawable
* \param p_exception an initialized exception
* \param p_e an initialized exception pointer
*/
VLC_PUBLIC_API void libvlc_video_redraw_rectangle( libvlc_media_instance_t *, const libvlc_rectangle_t *, libvlc_exception_t * );
/**