X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc_media.h;h=f8b267d7f43e2456af3e761fb1c1999d1b96ad88;hb=978d581b98c07bab07f3e200226fbb29469b9209;hp=ccdaeaedab70cb76e67be25004d4af9113157716;hpb=8ff2e66fced4218dcd523c65567c8262d88e88b4;p=vlc diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h index ccdaeaedab..f8b267d7f4 100644 --- a/include/vlc/libvlc_media.h +++ b/include/vlc/libvlc_media.h @@ -1,26 +1,26 @@ /***************************************************************************** - * libvlc.h: libvlc external API + * libvlc_media.h: libvlc external API ***************************************************************************** - * Copyright (C) 1998-2009 the VideoLAN team + * Copyright (C) 1998-2009 VLC authors and VideoLAN * $Id$ * * Authors: Clément Stenac * Jean-Paul Saman * Pierre d'Herbemont * - * This program 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 + * This program is free software; you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as published by + * the Free Software Foundation; either version 2.1 of the License, or * (at your option) any later version. * * This program 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. + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser 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., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. + * You should have received a copy of the GNU Lesser General Public License + * along with this program; if not, write to the Free Software Foundation, + * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. *****************************************************************************/ /** @@ -185,7 +185,7 @@ typedef struct libvlc_media_track_info_t * \param psz_mrl the media location * \return the newly created media or NULL on error */ -VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_location( +LIBVLC_API libvlc_media_t *libvlc_media_new_location( libvlc_instance_t *p_instance, const char * psz_mrl ); @@ -198,7 +198,7 @@ VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_location( * \param path local filesystem path * \return the newly created media or NULL on error */ -VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_path( +LIBVLC_API libvlc_media_t *libvlc_media_new_path( libvlc_instance_t *p_instance, const char *path ); @@ -226,7 +226,7 @@ VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_path( * \param fd open file descriptor * \return the newly created media or NULL on error */ -VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_fd( +LIBVLC_API libvlc_media_t *libvlc_media_new_fd( libvlc_instance_t *p_instance, int fd ); @@ -240,7 +240,7 @@ VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_fd( * \param psz_name the name of the node * \return the new empty media or NULL on error */ -VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_as_node( +LIBVLC_API libvlc_media_t *libvlc_media_new_as_node( libvlc_instance_t *p_instance, const char * psz_name ); @@ -251,12 +251,16 @@ VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_as_node( * read the media. 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 detailed in vlc --long-help, for instance + * "--sout-all". Note that all options are not usable on medias: + * specifically, due to architectural issues, video-related options + * such as text renderer options cannot be set on a single media. They + * must be set on the whole libvlc instance instead. * * \param p_md the media descriptor * \param ppsz_options the options (as a string) */ -VLC_PUBLIC_API void libvlc_media_add_option( +LIBVLC_API void libvlc_media_add_option( libvlc_media_t *p_md, const char * ppsz_options ); @@ -267,13 +271,17 @@ VLC_PUBLIC_API void libvlc_media_add_option( * read the media. 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 detailed in vlc --long-help, for instance + * "--sout-all". Note that all options are not usable on medias: + * specifically, due to architectural issues, video-related options + * such as text renderer options cannot be set on a single media. They + * must be set on the whole libvlc instance instead. * * \param p_md the media descriptor * \param ppsz_options the options (as a string) * \param i_flags the flags for this option */ -VLC_PUBLIC_API void libvlc_media_add_option_flag( +LIBVLC_API void libvlc_media_add_option_flag( libvlc_media_t *p_md, const char * ppsz_options, unsigned i_flags ); @@ -286,7 +294,7 @@ VLC_PUBLIC_API void libvlc_media_add_option_flag( * * \param p_md the media descriptor */ -VLC_PUBLIC_API void libvlc_media_retain( libvlc_media_t *p_md ); +LIBVLC_API void libvlc_media_retain( libvlc_media_t *p_md ); /** * Decrement the reference count of a media descriptor object. If the @@ -297,7 +305,7 @@ VLC_PUBLIC_API void libvlc_media_retain( libvlc_media_t *p_md ); * * \param p_md the media descriptor */ -VLC_PUBLIC_API void libvlc_media_release( libvlc_media_t *p_md ); +LIBVLC_API void libvlc_media_release( libvlc_media_t *p_md ); /** @@ -306,14 +314,14 @@ VLC_PUBLIC_API void libvlc_media_release( libvlc_media_t *p_md ); * \param p_md a media descriptor object * \return string with mrl of media descriptor object */ -VLC_PUBLIC_API char *libvlc_media_get_mrl( libvlc_media_t *p_md ); +LIBVLC_API char *libvlc_media_get_mrl( libvlc_media_t *p_md ); /** * Duplicate a media descriptor object. * * \param p_md a media descriptor object. */ -VLC_PUBLIC_API libvlc_media_t *libvlc_media_duplicate( libvlc_media_t *p_md ); +LIBVLC_API libvlc_media_t *libvlc_media_duplicate( libvlc_media_t *p_md ); /** * Read the meta of the media. @@ -332,7 +340,7 @@ VLC_PUBLIC_API libvlc_media_t *libvlc_media_duplicate( libvlc_media_t *p_md ); * \param e_meta the meta to read * \return the media's meta */ -VLC_PUBLIC_API char *libvlc_media_get_meta( libvlc_media_t *p_md, +LIBVLC_API char *libvlc_media_get_meta( libvlc_media_t *p_md, libvlc_meta_t e_meta ); /** @@ -343,7 +351,7 @@ VLC_PUBLIC_API char *libvlc_media_get_meta( libvlc_media_t *p_md, * \param e_meta the meta to write * \param psz_value the media's meta */ -VLC_PUBLIC_API void libvlc_media_set_meta( libvlc_media_t *p_md, +LIBVLC_API void libvlc_media_set_meta( libvlc_media_t *p_md, libvlc_meta_t e_meta, const char *psz_value ); @@ -352,9 +360,9 @@ VLC_PUBLIC_API void libvlc_media_set_meta( libvlc_media_t *p_md, * Save the meta previously set * * \param p_md the media desriptor - * \return true if the write operation was successfull + * \return true if the write operation was successful */ -VLC_PUBLIC_API int libvlc_media_save_meta( libvlc_media_t *p_md ); +LIBVLC_API int libvlc_media_save_meta( libvlc_media_t *p_md ); /** @@ -368,7 +376,7 @@ VLC_PUBLIC_API int libvlc_media_save_meta( libvlc_media_t *p_md ); * \param p_md a media descriptor object * \return state of media descriptor object */ -VLC_PUBLIC_API libvlc_state_t libvlc_media_get_state( +LIBVLC_API libvlc_state_t libvlc_media_get_state( libvlc_media_t *p_md ); @@ -378,8 +386,10 @@ VLC_PUBLIC_API libvlc_state_t libvlc_media_get_state( * \param p_stats: structure that contain the statistics about the media * (this structure must be allocated by the caller) * \return true if the statistics are available, false otherwise + * + * \libvlc_return_bool */ -VLC_PUBLIC_API int libvlc_media_get_stats( libvlc_media_t *p_md, +LIBVLC_API int libvlc_media_get_stats( libvlc_media_t *p_md, libvlc_media_stats_t *p_stats ); /** @@ -395,7 +405,7 @@ VLC_PUBLIC_API int libvlc_media_get_stats( libvlc_media_t *p_md, * and this is here for convenience */ #define VLC_FORWARD_DECLARE_OBJECT(a) struct a -VLC_PUBLIC_API VLC_FORWARD_DECLARE_OBJECT(libvlc_media_list_t *) +LIBVLC_API VLC_FORWARD_DECLARE_OBJECT(libvlc_media_list_t *) libvlc_media_subitems( libvlc_media_t *p_md ); /** @@ -405,7 +415,7 @@ libvlc_media_subitems( libvlc_media_t *p_md ); * \param p_md a media descriptor object * \return event manager object */ -VLC_PUBLIC_API libvlc_event_manager_t * +LIBVLC_API libvlc_event_manager_t * libvlc_media_event_manager( libvlc_media_t *p_md ); /** @@ -414,7 +424,7 @@ VLC_PUBLIC_API libvlc_event_manager_t * * \param p_md media descriptor object * \return duration of media item or -1 on error */ -VLC_PUBLIC_API libvlc_time_t +LIBVLC_API libvlc_time_t libvlc_media_get_duration( libvlc_media_t *p_md ); /** @@ -429,7 +439,7 @@ VLC_PUBLIC_API libvlc_time_t * * \param p_md media descriptor object */ -VLC_PUBLIC_API void +LIBVLC_API void libvlc_media_parse( libvlc_media_t *p_md ); /** @@ -449,7 +459,7 @@ libvlc_media_parse( libvlc_media_t *p_md ); * * \param p_md media descriptor object */ -VLC_PUBLIC_API void +LIBVLC_API void libvlc_media_parse_async( libvlc_media_t *p_md ); /** @@ -459,8 +469,10 @@ libvlc_media_parse_async( libvlc_media_t *p_md ); * * \param p_md media descriptor object * \return true if media object has been parsed otherwise it returns false + * + * \libvlc_return_bool */ -VLC_PUBLIC_API int +LIBVLC_API int libvlc_media_is_parsed( libvlc_media_t *p_md ); /** @@ -471,7 +483,7 @@ VLC_PUBLIC_API int * \param p_md media descriptor object * \param p_new_user_data pointer to user data */ -VLC_PUBLIC_API void +LIBVLC_API void libvlc_media_set_user_data( libvlc_media_t *p_md, void *p_new_user_data ); /** @@ -481,33 +493,22 @@ VLC_PUBLIC_API void * * \param p_md media descriptor object */ -VLC_PUBLIC_API void *libvlc_media_get_user_data( libvlc_media_t *p_md ); +LIBVLC_API void *libvlc_media_get_user_data( libvlc_media_t *p_md ); /** * Get media descriptor's elementary streams description * - * Note, you need to play the media _one_ time with --sout="#description" - * Not doing this will result in an empty array, and doing it more than once - * will duplicate the entries in the array each time. Something like this: - * - * @begincode - * libvlc_media_player_t *player = libvlc_media_player_new_from_media(media); - * libvlc_media_add_option_flag(media, "sout=#description"); - * libvlc_media_player_play(player); - * // ... wait until playing - * libvlc_media_player_release(player); - * @endcode - * - * This is very likely to change in next release, and be done at the parsing - * phase. + * Note, you need to call libvlc_media_parse() or play the media at least once + * before calling this function. + * Not doing this will result in an empty array. * * \param p_md media descriptor object * \param tracks address to store an allocated array of Elementary Streams - * descriptions (must be freed by the caller) + * descriptions (must be freed by the caller) [OUT] * - * return the number of Elementary Streams + * \return the number of Elementary Streams */ -VLC_PUBLIC_API +LIBVLC_API int libvlc_media_get_tracks_info( libvlc_media_t *p_md, libvlc_media_track_info_t **tracks );