From: Sam Hocevar Date: Thu, 20 Mar 2008 17:43:48 +0000 (+0000) Subject: Documentation updates. X-Git-Tag: 0.9.0-test0~1973 X-Git-Url: https://git.sesse.net/?a=commitdiff_plain;h=8b5869976eae2be0bee9e9c9d0ab4f8d7a258bc0;p=vlc 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). --- diff --git a/include/vlc/libvlc.h b/include/vlc/libvlc.h index 88ecc4af27..5235c1f35d 100644 --- a/include/vlc/libvlc.h +++ b/include/vlc/libvlc.h @@ -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 * ); /** - * Set the default video output parent - * this settings will be used as default for all video outputs + * Set the default video output's parent. + * + * This setting will be used as default for all video outputs. + * * \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 */ VLC_PUBLIC_API void libvlc_video_set_parent( libvlc_instance_t *, libvlc_drawable_t, libvlc_exception_t * ); /** - * Set the default video output parent - * this settings will be used as default for all video outputs + * Set the default video output parent. + * + * This setting will be used as default for all video outputs. + * * \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 */ VLC_PUBLIC_API libvlc_drawable_t libvlc_video_get_parent( libvlc_instance_t *, libvlc_exception_t * ); /** - * Set the default video output size - * this settings will be used as default for all video outputs + * Set the default video output size. + * + * This setting will be used as default for all video outputs. + * * \param p_instance libvlc instance * \param width new width for video drawable * \param height new height for video drawable - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_video_set_size( libvlc_instance_t *, int, int, libvlc_exception_t * ); /** - * Set the default video output viewport for a windowless video output (MacOS X only) - * this settings will be used as default for all video outputs + * Set the default video output viewport for a windowless video output + * (MacOS X only). + * + * This setting will be used as default for all video outputs. + * * \param p_instance libvlc instance * \param view coordinates within video drawable * \param clip coordinates within video drawable - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_video_set_viewport( libvlc_instance_t *, const libvlc_rectangle_t *, const libvlc_rectangle_t *, libvlc_exception_t * ); @@ -973,48 +1072,52 @@ VLC_PUBLIC_API void libvlc_video_set_viewport( libvlc_instance_t *, const libvlc */ /** - * Toggle mute status + * Toggle mute status. + * * \param p_instance libvlc instance - * \param p_exception an initialized exception - * \return void + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_audio_toggle_mute( libvlc_instance_t *, libvlc_exception_t * ); /** - * Get current mute status + * Get current mute status. + * * \param p_instance libvlc instance - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer * \return the mute status (boolean) */ VLC_PUBLIC_API int libvlc_audio_get_mute( libvlc_instance_t *, libvlc_exception_t * ); /** - * Set mute status + * Set mute status. + * * \param p_instance libvlc instance * \param status If status is VLC_TRUE then mute, otherwise unmute - * \param p_exception an initialized exception - * \return void + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_audio_set_mute( libvlc_instance_t *, int , libvlc_exception_t * ); /** - * Get current audio level + * Get current audio level. + * * \param p_instance libvlc instance - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer * \return the audio level (int) */ VLC_PUBLIC_API int libvlc_audio_get_volume( libvlc_instance_t *, libvlc_exception_t * ); /** - * Set current audio level + * Set current audio level. + * * \param p_instance libvlc instance * \param i_volume the volume (int) - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_audio_set_volume( libvlc_instance_t *, int, libvlc_exception_t *); /** - * Get number of available audio tracks + * Get number of available audio tracks. + * * \param p_mi media instance * \param p_e an initialized exception * \return the number of available audio tracks (int) @@ -1022,34 +1125,38 @@ VLC_PUBLIC_API void libvlc_audio_set_volume( libvlc_instance_t *, int, libvlc_ex VLC_PUBLIC_API int libvlc_audio_get_track_count( libvlc_media_instance_t *, libvlc_exception_t * ); /** -+ * Get current audio track -+ * \param p_input input instance -+ * \param p_exception an initialized exception -+ * \return the audio track (int) -+ */ + * Get current audio track. + * + * \param p_input input instance + * \param p_e an initialized exception pointer + * \return the audio track (int) + */ VLC_PUBLIC_API int libvlc_audio_get_track( libvlc_media_instance_t *, libvlc_exception_t * ); /** - * Set current audio track + * Set current audio track. + * * \param p_input input instance * \param i_track the track (int) - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_audio_set_track( libvlc_media_instance_t *, int, libvlc_exception_t * ); /** - * Get current audio channel + * Get current audio channel. + * * \param p_instance input instance - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer * \return the audio channel (int) */ VLC_PUBLIC_API int libvlc_audio_get_channel( libvlc_instance_t *, libvlc_exception_t * ); /** - * Set current audio channel + * Set current audio channel. + * * \param p_instance input instance * \param i_channel the audio channel (int) - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_audio_set_channel( libvlc_instance_t *, int, libvlc_exception_t * ); @@ -1091,7 +1198,8 @@ VLC_PUBLIC_API int */ /** - * Add a broadcast, with one input + * Add a broadcast, with one input. + * * \param p_instance the instance * \param psz_name the name of the new broadcast * \param psz_input the input MRL @@ -1100,35 +1208,38 @@ VLC_PUBLIC_API int * \param ppsz_options additional options * \param b_enabled boolean for enabling the new broadcast * \param b_loop Should this broadcast be played in loop ? - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_vlm_add_broadcast( libvlc_instance_t *, char *, char *, char* , int, char **, int, int, libvlc_exception_t * ); /** - * Delete a media (vod or broadcast) + * Delete a media (VOD or broadcast). + * * \param p_instance the instance * \param psz_name the media to delete - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_vlm_del_media( libvlc_instance_t *, char *, libvlc_exception_t * ); /** - * Enable or disable a media (vod or broadcast) + * Enable or disable a media (VOD or broadcast). + * * \param p_instance the instance * \param psz_name the media to work on * \param b_enabled the new status - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_vlm_set_enabled( libvlc_instance_t *, char *, int, libvlc_exception_t *); /** - * Set the output for a media + * Set the output for a media. + * * \param p_instance the instance * \param psz_name the media to work on * \param psz_output the output MRL (the parameter to the "sout" variable) - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_vlm_set_output( libvlc_instance_t *, char *, char*, libvlc_exception_t *); @@ -1136,29 +1247,32 @@ VLC_PUBLIC_API void libvlc_vlm_set_output( libvlc_instance_t *, char *, char*, /** * Set a media's input MRL. This will delete all existing inputs and * add the specified one. + * * \param p_instance the instance * \param psz_name the media to work on * \param psz_input the input MRL - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_vlm_set_input( libvlc_instance_t *, char *, char*, libvlc_exception_t *); /** * Add a media's input MRL. This will add the specified one. + * * \param p_instance the instance * \param psz_name the media to work on * \param psz_input the input MRL - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_vlm_add_input( libvlc_instance_t *, char *, char *, libvlc_exception_t *p_exception ); /** - * Set output for a media + * Set a media's loop status. + * * \param p_instance the instance * \param psz_name the media to work on * \param b_loop the new status - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_vlm_set_loop( libvlc_instance_t *, char *, int, libvlc_exception_t *); @@ -1166,6 +1280,7 @@ VLC_PUBLIC_API void libvlc_vlm_set_loop( libvlc_instance_t *, char *, int, /** * Edit the parameters of a media. This will delete all existing inputs and * add the specified one. + * * \param p_instance the instance * \param psz_name the name of the new broadcast * \param psz_input the input MRL @@ -1174,50 +1289,55 @@ VLC_PUBLIC_API void libvlc_vlm_set_loop( libvlc_instance_t *, char *, int, * \param ppsz_options additional options * \param b_enabled boolean for enabling the new broadcast * \param b_loop Should this broadcast be played in loop ? - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_vlm_change_media( libvlc_instance_t *, char *, char *, char* , int, char **, int, int, libvlc_exception_t * ); /** - * Plays the named broadcast. + * Play the named broadcast. + * * \param p_instance the instance * \param psz_name the name of the broadcast - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_vlm_play_media ( libvlc_instance_t *, char *, libvlc_exception_t * ); /** - * Stops the named broadcast. + * Stop the named broadcast. + * * \param p_instance the instance * \param psz_name the name of the broadcast - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_vlm_stop_media ( libvlc_instance_t *, char *, libvlc_exception_t * ); /** - * Pauses the named broadcast. + * Pause the named broadcast. + * * \param p_instance the instance * \param psz_name the name of the broadcast - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_vlm_pause_media( libvlc_instance_t *, char *, libvlc_exception_t * ); /** - * Seeks in the named broadcast. + * Seek in the named broadcast. + * * \param p_instance the instance * \param psz_name the name of the broadcast * \param f_percentage the percentage to seek to - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_vlm_seek_media( libvlc_instance_t *, char *, float, libvlc_exception_t * ); /** - * Return information of the named broadcast. + * Return information about the named broadcast. + * * \param p_instance the instance * \param psz_name the name of the broadcast - * \param p_exception an initialized exception + * \param p_e an initialized exception pointer */ VLC_PUBLIC_API char* libvlc_vlm_show_media( libvlc_instance_t *, char *, libvlc_exception_t * ); @@ -1248,7 +1368,8 @@ VLC_PUBLIC_API LIBVLC_VLM_GET_MEDIA_ATTRIBUTE( seekable, int, Bool, 0); */ /** - * Returns the VLC messaging verbosity level + * Return the VLC messaging verbosity level. + * * \param p_instance libvlc instance * \param exception an initialized exception pointer */ @@ -1256,7 +1377,8 @@ VLC_PUBLIC_API unsigned libvlc_get_log_verbosity( const libvlc_instance_t *p_ins libvlc_exception_t *p_e ); /** - * Set the VLC messaging verbosity level + * Set the VLC messaging verbosity level. + * * \param p_log libvlc log instance * \param exception an initialized exception pointer */ @@ -1264,58 +1386,69 @@ VLC_PUBLIC_API void libvlc_set_log_verbosity( libvlc_instance_t *p_instance, uns libvlc_exception_t *p_e ); /** - * Open an instance to VLC message log + * Open a VLC message log instance. + * * \param p_instance libvlc instance * \param exception an initialized exception pointer */ VLC_PUBLIC_API libvlc_log_t *libvlc_log_open( libvlc_instance_t *, libvlc_exception_t *); /** - * Close an instance of VLC message log + * Close a VLC message log instance. + * * \param p_log libvlc log instance * \param exception an initialized exception pointer */ VLC_PUBLIC_API void libvlc_log_close( libvlc_log_t *, libvlc_exception_t *); /** - * Returns the number of messages in log + * Returns the number of messages in a log instance. + * * \param p_log libvlc log instance * \param exception an initialized exception pointer */ VLC_PUBLIC_API unsigned libvlc_log_count( const libvlc_log_t *, libvlc_exception_t *); /** - * Clear all messages in log - * the log should be cleared on a regular basis to avoid clogging + * Clear a log instance. + * + * All messages in the log are removed. The log should be cleared on a + * regular basis to avoid clogging. + * * \param p_log libvlc log instance * \param exception an initialized exception pointer */ VLC_PUBLIC_API void libvlc_log_clear( libvlc_log_t *, libvlc_exception_t *); /** - * Allocate and returns a new iterator to messages in log + * Allocate and returns a new iterator to messages in log. + * * \param p_log libvlc log instance * \param exception an initialized exception pointer */ VLC_PUBLIC_API libvlc_log_iterator_t *libvlc_log_get_iterator( const libvlc_log_t *, libvlc_exception_t *); /** - * Releases a previoulsy allocated iterator + * Release a previoulsy allocated iterator. + * * \param p_log libvlc log iterator * \param exception an initialized exception pointer */ VLC_PUBLIC_API void libvlc_log_iterator_free( libvlc_log_iterator_t *p_iter, libvlc_exception_t *p_e ); /** - * Returns whether log iterator has more messages + * Return whether log iterator has more messages. + * * \param p_log libvlc log iterator * \param exception an initialized exception pointer */ VLC_PUBLIC_API int libvlc_log_iterator_has_next( const libvlc_log_iterator_t *p_iter, libvlc_exception_t *p_e ); /** - * Returns next log message - * the content of message must not be freed + * Return the next log message. + * + * The message contents must not be freed + * * \param p_log libvlc log iterator * \param exception an initialized exception pointer */ @@ -1336,10 +1469,11 @@ VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterat */ /** - * Register for an event notification - * \param p_event_manager the event manager to which you want to attach to - * Generally it is obtained by vlc_my_object_event_manager() where my_object - * Is the object you want to listen to. + * Register for an event notification. + * + * \param p_event_manager the event manager to which you want to attach to. + * Generally it is obtained by vlc_my_object_event_manager() where + * my_object is the object you want to listen to. * \param i_event_type the desired event to which we want to listen * \param f_callback the function to call when i_event_type occurs * \param user_data user provided data to carry with the event @@ -1352,7 +1486,8 @@ VLC_PUBLIC_API void libvlc_event_attach( libvlc_event_manager_t *p_event_manager libvlc_exception_t *p_e ); /** - * Unregister an event notification + * Unregister an event notification. + * * \param p_event_manager the event manager * \param i_event_type the desired event to which we want to unregister * \param f_callback the function to call when i_event_type occurs @@ -1365,7 +1500,8 @@ VLC_PUBLIC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager libvlc_exception_t *p_e ); /** - * Get an event type name + * Get an event's type name. + * * \param i_event_type the desired event */ VLC_PUBLIC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );