Commit fd3ef905 authored by Rémi Denis-Courmont's avatar Rémi Denis-Courmont

Improve Doxygen documentation, deobfuscate event types

parent 18852621
...@@ -37,10 +37,9 @@ extern "C" { ...@@ -37,10 +37,9 @@ extern "C" {
/***************************************************************************** /*****************************************************************************
* Playlist (Deprecated) * Playlist (Deprecated)
*****************************************************************************/ *****************************************************************************/
/** \defgroup libvlc_playlist libvlc_playlist (Deprecated) /** \defgroup libvlc_playlist LibVLC playlist (legacy)
* \ingroup libvlc * \ingroup libvlc
* LibVLC Playlist handling (Deprecated) * @deprecated Use @ref libvlc_media_list instead.
* @deprecated Use media_list
* @{ * @{
*/ */
......
...@@ -29,9 +29,9 @@ ...@@ -29,9 +29,9 @@
*/ */
/** /**
* \defgroup libvlc libvlc * \defgroup libvlc LibVLC
* This is libvlc, the base library of the VLC program. * LibVLC is the external programming interface of the VLC media player.
* * It is used to embed VLC into other applications or frameworks.
* @{ * @{
*/ */
...@@ -61,12 +61,19 @@ extern "C" { ...@@ -61,12 +61,19 @@ extern "C" {
#include <stdarg.h> #include <stdarg.h>
#include <vlc/libvlc_structures.h> #include <vlc/libvlc_structures.h>
/***************************************************************************** /** \defgroup libvlc_core LibVLC core
* Error handling * \ingroup libvlc
*****************************************************************************/ * Before it can do anything useful, LibVLC must be initialized.
/** \defgroup libvlc_error libvlc_error * You can create one (or more) instance(s) of LibVLC in a given process,
* \ingroup libvlc_core * with libvlc_new() and destroy them with libvlc_release().
* LibVLC error handling *
* \version This documents LibVLC version 1.1.
* Earlier versions (0.9 and 1.0) are <b>not</b> compatible.
* @{
*/
/** \defgroup libvlc_error LibVLC error handling
* \ingroup libvlc_error
* @{ * @{
*/ */
...@@ -103,17 +110,6 @@ const char *libvlc_printerr (const char *fmt, ...); ...@@ -103,17 +110,6 @@ const char *libvlc_printerr (const char *fmt, ...);
/**@} */ /**@} */
/*****************************************************************************
* Core handling
*****************************************************************************/
/** \defgroup libvlc_core libvlc_core
* \ingroup libvlc
* LibVLC Core
* @{
*/
/** /**
* Create and initialize a libvlc instance. * Create and initialize a libvlc instance.
* *
...@@ -162,7 +158,7 @@ void libvlc_wait( libvlc_instance_t *p_instance ); ...@@ -162,7 +158,7 @@ void libvlc_wait( libvlc_instance_t *p_instance );
/** /**
* Retrieve libvlc version. * Retrieve libvlc version.
* *
* Example: "0.9.0-git Grishenko" * Example: "1.1.0-git The Luggage"
* *
* \return a string containing the libvlc version * \return a string containing the libvlc version
*/ */
...@@ -186,17 +182,15 @@ VLC_PUBLIC_API const char * libvlc_get_compiler(void); ...@@ -186,17 +182,15 @@ VLC_PUBLIC_API const char * libvlc_get_compiler(void);
*/ */
VLC_PUBLIC_API const char * libvlc_get_changeset(void); VLC_PUBLIC_API const char * libvlc_get_changeset(void);
struct vlc_object_t;
/** @}*/
/*****************************************************************************
* Event handling
*****************************************************************************/
/** \defgroup libvlc_event libvlc_event /** \defgroup libvlc_event LibVLC asynchronous events
* \ingroup libvlc_core * LibVLC emits asynchronous events.
* LibVLC Events *
* Several LibVLC objects (such @ref libvlc_instance_t as
* @ref libvlc_media_player_t) generate events asynchronously. Each of them
* provides @ref libvlc_event_manager_t event manager. You can subscribe to
* events with libvlc_event_attach() and unsubscribe with
* libvlc_event_detach().
* @{ * @{
*/ */
...@@ -204,17 +198,20 @@ struct vlc_object_t; ...@@ -204,17 +198,20 @@ struct vlc_object_t;
* Event manager that belongs to a libvlc object, and from whom events can * Event manager that belongs to a libvlc object, and from whom events can
* be received. * be received.
*/ */
typedef struct libvlc_event_manager_t libvlc_event_manager_t; typedef struct libvlc_event_manager_t libvlc_event_manager_t;
typedef struct libvlc_event_t libvlc_event_t;
typedef uint32_t libvlc_event_type_t; struct libvlc_event_t;
/**
* Type of a LibVLC event.
*/
typedef int libvlc_event_type_t;
/** /**
* Callback function notification * Callback function notification
* \param p_event the event triggering the callback * \param p_event the event triggering the callback
*/ */
typedef void ( *libvlc_callback_t )( const struct libvlc_event_t *, void * );
typedef void ( *libvlc_callback_t )( const libvlc_event_t *, void * );
/** /**
* Register for an event notification. * Register for an event notification.
...@@ -245,22 +242,11 @@ VLC_PUBLIC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager ...@@ -245,22 +242,11 @@ VLC_PUBLIC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager
libvlc_callback_t f_callback, libvlc_callback_t f_callback,
void *p_user_data ); void *p_user_data );
/**
* Get an event's type name.
*
* \param event_type the desired event
*/
VLC_PUBLIC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
/** @} */ /** @} */
/***************************************************************************** /** \defgroup libvlc_log LibVLC logging
* Message log handling * libvlc_log_* functions provide access to the LibVLC messages log.
*****************************************************************************/ * This is used for debugging or by advanced users.
/** \defgroup libvlc_log libvlc_log
* \ingroup libvlc_core
* LibVLC Message Logging
* @{ * @{
*/ */
...@@ -349,11 +335,11 @@ VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterat ...@@ -349,11 +335,11 @@ VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterat
libvlc_log_message_t *p_buffer ); libvlc_log_message_t *p_buffer );
/** @} */ /** @} */
/** @} */
/** @} */
# ifdef __cplusplus # ifdef __cplusplus
} }
# endif # endif
#endif /* <vlc/libvlc.h> */ #endif /* <vlc/libvlc.h> */
/** @} */
...@@ -34,105 +34,85 @@ ...@@ -34,105 +34,85 @@
extern "C" { extern "C" {
# endif # endif
/***************************************************************************** /**
* Events handling * \ingroup libvlc_event
*****************************************************************************/
/** \defgroup libvlc_event libvlc_event
* \ingroup libvlc_core
* LibVLC Available Events
* @{ * @{
*/ */
/**
* Event types
*/
enum libvlc_event_e {
/* Append new event types at the end. Do not remove, insert or /* Append new event types at the end. Do not remove, insert or
* re-order any entry. The cpp will prepend libvlc_ to the symbols. */ * re-order any entry. The cpp will prepend libvlc_ to the symbols. */
#define DEFINE_LIBVLC_EVENT_TYPES \ libvlc_MediaMetaChanged,
DEF( MediaMetaChanged ), \ libvlc_MediaSubItemAdded,
DEF( MediaSubItemAdded ), \ libvlc_MediaDurationChanged,
DEF( MediaDurationChanged ), \ libvlc_MediaPreparsedChanged,
DEF( MediaPreparsedChanged ), \ libvlc_MediaFreed,
DEF( MediaFreed ), \ libvlc_MediaStateChanged,
DEF( MediaStateChanged ), \
\ libvlc_MediaPlayerNothingSpecial,
DEF( MediaPlayerNothingSpecial ), \ libvlc_MediaPlayerOpening,
DEF( MediaPlayerOpening ), \ libvlc_MediaPlayerBuffering,
DEF( MediaPlayerBuffering ), \ libvlc_MediaPlayerPlaying,
DEF( MediaPlayerPlaying ), \ libvlc_MediaPlayerPaused,
DEF( MediaPlayerPaused ), \ libvlc_MediaPlayerStopped,
DEF( MediaPlayerStopped ), \ libvlc_MediaPlayerForward,
DEF( MediaPlayerForward ), \ libvlc_MediaPlayerBackward,
DEF( MediaPlayerBackward ), \ libvlc_MediaPlayerEndReached,
DEF( MediaPlayerEndReached ), \ libvlc_MediaPlayerEncounteredError,
DEF( MediaPlayerEncounteredError ), \ libvlc_MediaPlayerTimeChanged,
DEF( MediaPlayerTimeChanged ), \ libvlc_MediaPlayerPositionChanged,
DEF( MediaPlayerPositionChanged ), \ libvlc_MediaPlayerSeekableChanged,
DEF( MediaPlayerSeekableChanged ), \ libvlc_MediaPlayerPausableChanged,
DEF( MediaPlayerPausableChanged ), \
\ libvlc_MediaListItemAdded,
DEF( MediaListItemAdded ), \ libvlc_MediaListWillAddItem,
DEF( MediaListWillAddItem ), \ libvlc_MediaListItemDeleted,
DEF( MediaListItemDeleted ), \ libvlc_MediaListWillDeleteItem,
DEF( MediaListWillDeleteItem ), \
\ libvlc_MediaListViewItemAdded,
DEF( MediaListViewItemAdded ), \ libvlc_MediaListViewWillAddItem,
DEF( MediaListViewWillAddItem ), \ libvlc_MediaListViewItemDeleted,
DEF( MediaListViewItemDeleted ), \ libvlc_MediaListViewWillDeleteItem,
DEF( MediaListViewWillDeleteItem ), \
\ libvlc_MediaListPlayerPlayed,
DEF( MediaListPlayerPlayed ), \ libvlc_MediaListPlayerNextItemSet,
DEF( MediaListPlayerNextItemSet ), \ libvlc_MediaListPlayerStopped,
DEF( MediaListPlayerStopped ), \
\ libvlc_MediaDiscovererStarted,
DEF( MediaDiscovererStarted ), \ libvlc_MediaDiscovererEnded,
DEF( MediaDiscovererEnded ), \
\ libvlc_MediaPlayerTitleChanged,
DEF( MediaPlayerTitleChanged ), \ libvlc_MediaPlayerSnapshotTaken,
DEF( MediaPlayerSnapshotTaken ), \ libvlc_MediaPlayerLengthChanged,
DEF( MediaPlayerLengthChanged ), \
\ libvlc_VlmMediaAdded,
DEF( VlmMediaAdded ), \ libvlc_VlmMediaRemoved,
DEF( VlmMediaRemoved ), \ libvlc_VlmMediaChanged,
DEF( VlmMediaChanged ), \ libvlc_VlmMediaInstanceStarted,
DEF( VlmMediaInstanceStarted ), \ libvlc_VlmMediaInstanceStopped,
DEF( VlmMediaInstanceStopped ), \ libvlc_VlmMediaInstanceStatusInit,
DEF( VlmMediaInstanceStatusInit ), \ libvlc_VlmMediaInstanceStatusOpening,
DEF( VlmMediaInstanceStatusOpening ), \ libvlc_VlmMediaInstanceStatusPlaying,
DEF( VlmMediaInstanceStatusPlaying ), \ libvlc_VlmMediaInstanceStatusPause,
DEF( VlmMediaInstanceStatusPause ), \ libvlc_VlmMediaInstanceStatusEnd,
DEF( VlmMediaInstanceStatusEnd ), \ libvlc_VlmMediaInstanceStatusError,
DEF( VlmMediaInstanceStatusError ), \
\ libvlc_MediaPlayerMediaChanged,
DEF( MediaPlayerMediaChanged ), \ /* New event types HERE */
/* New event types HERE */
#ifdef __cplusplus
enum libvlc_event_type_e {
#else
enum libvlc_event_type_t {
#endif
#define DEF(a) libvlc_##a
DEFINE_LIBVLC_EVENT_TYPES
libvlc_num_event_types libvlc_num_event_types
#undef DEF
}; };
/* Implementing libvlc_event_type_name() needs the definition too. */
#ifndef LIBVLC_EVENT_TYPES_KEEP_DEFINE
#undef DEFINE_LIBVLC_EVENT_TYPES
#endif
/** /**
* An Event * A LibVLC event
* \param type the even type
* \param p_obj the sender object
* \param u Event dependent content
*/ */
typedef struct libvlc_event_t
struct libvlc_event_t
{ {
libvlc_event_type_t type; int type; /**< Event type (see @ref libvlc_event_e) */
void * p_obj; void *p_obj; /**< Object emitting the event */
union event_type_specific union
{ {
/* media descriptor */ /* media descriptor */
struct struct
...@@ -234,8 +214,8 @@ struct libvlc_event_t ...@@ -234,8 +214,8 @@ struct libvlc_event_t
{ {
libvlc_media_t * new_media; libvlc_media_t * new_media;
} media_player_media_changed; } media_player_media_changed;
} u; } u; /**< Type-dependent event description */
}; } libvlc_event_t;
/**@} */ /**@} */
......
...@@ -35,24 +35,21 @@ ...@@ -35,24 +35,21 @@
extern "C" { extern "C" {
# endif # endif
/***************************************************************************** /** \defgroup libvlc_media LibVLC media
* media
*****************************************************************************/
/** \defgroup libvlc_media libvlc_media
* \ingroup libvlc * \ingroup libvlc
* LibVLC Media * @ref libvlc_media_t is an abstract representation of a playable media.
* It consists of a media location and various optional meta data.
* @{ * @{
*/ */
typedef struct libvlc_media_t libvlc_media_t; typedef struct libvlc_media_t libvlc_media_t;
/* Meta Handling */ /** defgroup libvlc_meta LibVLC meta data
/** defgroup libvlc_meta libvlc_meta
* \ingroup libvlc_media * \ingroup libvlc_media
* LibVLC Media Meta
* @{ * @{
*/ */
/** Meta data types */
typedef enum libvlc_meta_t { typedef enum libvlc_meta_t {
libvlc_meta_Title, libvlc_meta_Title,
libvlc_meta_Artist, libvlc_meta_Artist,
...@@ -111,9 +108,8 @@ typedef enum libvlc_es_type_t ...@@ -111,9 +108,8 @@ typedef enum libvlc_es_type_t
libvlc_es_text = 2, libvlc_es_text = 2,
} libvlc_es_type_t; } libvlc_es_type_t;
/** defgroup libvlc_media_stats_t libvlc_media_stats_t /** defgroup libvlc_media_stats_t LibVLC media statistics
* \ingroup libvlc_media * \ingroup libvlc_media
* LibVLC Media statistics
* @{ * @{
*/ */
typedef struct libvlc_media_stats_t typedef struct libvlc_media_stats_t
......
...@@ -35,12 +35,13 @@ ...@@ -35,12 +35,13 @@
extern "C" { extern "C" {
# endif # endif
/***************************************************************************** /** \defgroup libvlc_media_discoverer LibVLC media discovery
* Services/Media Discovery
*****************************************************************************/
/** \defgroup libvlc_media_discoverer libvlc_media_discoverer
* \ingroup libvlc * \ingroup libvlc
* LibVLC Media Discoverer * LibVLC media discovery finds available media via various means.
* This corresponds to the service discovery functionality in VLC media player.
* Different plugins find potential medias locally (e.g. user media directory),
* from peripherals (e.g. video capture device), on the local network
* (e.g. SAP) or on the Internet (e.g. Internet radios).
* @{ * @{
*/ */
......
...@@ -35,12 +35,8 @@ ...@@ -35,12 +35,8 @@
extern "C" { extern "C" {
# endif # endif
/***************************************************************************** /** \defgroup libvlc_media_library LibVLC media library
* Media Library
*****************************************************************************/
/** \defgroup libvlc_media_library libvlc_media_library
* \ingroup libvlc * \ingroup libvlc
* LibVLC Media Library
* @{ * @{
*/ */
......
...@@ -33,12 +33,9 @@ ...@@ -33,12 +33,9 @@
extern "C" { extern "C" {
# endif # endif
/***************************************************************************** /** \defgroup libvlc_media_list LibVLC media list
* Media List
*****************************************************************************/
/** \defgroup libvlc_media_list libvlc_media_list
* \ingroup libvlc * \ingroup libvlc
* LibVLC Media List, a media list holds multiple media descriptors * A LibVLC media list holds multiple @ref libvlc_media_t media descriptors.
* @{ * @{
*/ */
......
...@@ -36,10 +36,13 @@ extern "C" { ...@@ -36,10 +36,13 @@ extern "C" {
/***************************************************************************** /*****************************************************************************
* Media List Player * Media List Player
*****************************************************************************/ *****************************************************************************/
/** \defgroup libvlc_media_list_player libvlc_media_list_player /** \defgroup libvlc_media_list_player LibVLC media list player
* \ingroup libvlc * \ingroup libvlc
* LibVLC Media List Player, play a media_list. You can see that as a media * The LibVLC media list player plays a @ref libvlc_media_list_t list of media,
* instance subclass * in a certain order.
* This is required to especially support playlist files.
* The normal @ref libvlc_media_player_t LibVLC media player can only play a
* single media, and does not handle playlist files properly.
* @{ * @{
*/ */
......
...@@ -38,10 +38,9 @@ extern "C" { ...@@ -38,10 +38,9 @@ extern "C" {
/***************************************************************************** /*****************************************************************************
* Media Player * Media Player
*****************************************************************************/ *****************************************************************************/
/** \defgroup libvlc_media_player libvlc_media_player /** \defgroup libvlc_media_player LibVLC media player
* \ingroup libvlc * \ingroup libvlc
* LibVLC Media Player, object that let you play a media * A LibVLC media player plays one media (usually in a custom drawable).
* in a custom drawable
* @{ * @{
*/ */
...@@ -197,10 +196,12 @@ VLC_PUBLIC_API void libvlc_media_player_stop ( libvlc_media_player_t *p_mi ); ...@@ -197,10 +196,12 @@ VLC_PUBLIC_API void libvlc_media_player_stop ( libvlc_media_player_t *p_mi );
* The object minimal_macosx expects is of kind NSObject and should * The object minimal_macosx expects is of kind NSObject and should
* respect the protocol: * respect the protocol:
* *
* @protocol VLCOpenGLVideoViewEmbedding <NSObject> * @begincode
* \@protocol VLCOpenGLVideoViewEmbedding <NSObject>
* - (void)addVoutSubview:(NSView *)view; * - (void)addVoutSubview:(NSView *)view;
* - (void)removeVoutSubview:(NSView *)view; * - (void)removeVoutSubview:(NSView *)view;
* @end * \@end
* @endcode
* *
* You can find a live example in VLCVideoView in VLCKit.framework. * You can find a live example in VLCVideoView in VLCKit.framework.
* *
...@@ -484,9 +485,7 @@ VLC_PUBLIC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_mi ...@@ -484,9 +485,7 @@ VLC_PUBLIC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_mi
*/ */
VLC_PUBLIC_API void libvlc_track_description_release( libvlc_track_description_t *p_track_description ); VLC_PUBLIC_API void libvlc_track_description_release( libvlc_track_description_t *p_track_description );
/** \defgroup libvlc_video libvlc_video /** \defgroup libvlc_video LibVLC video controls
* \ingroup libvlc_media_player
* LibVLC Video handling
* @{ * @{
*/ */
...@@ -909,9 +908,7 @@ VLC_PUBLIC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi, ...@@ -909,9 +908,7 @@ VLC_PUBLIC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi,
/** @} video */ /** @} video */
/** \defgroup libvlc_audio libvlc_audio /** \defgroup libvlc_audio LibVLC audio controls
* \ingroup libvlc_media_player
* LibVLC Audio handling
* @{ * @{
*/ */
......
...@@ -37,9 +37,8 @@ extern "C" { ...@@ -37,9 +37,8 @@ extern "C" {
/***************************************************************************** /*****************************************************************************
* VLM * VLM
*****************************************************************************/ *****************************************************************************/
/** \defgroup libvlc_vlm libvlc_vlm /** \defgroup libvlc_vlm LibVLC VLM
* \ingroup libvlc * \ingroup libvlc
* LibVLC VLM
* @{ * @{
*/ */
......
...@@ -240,27 +240,6 @@ void libvlc_event_send( libvlc_event_manager_t * p_em, ...@@ -240,27 +240,6 @@ void libvlc_event_send( libvlc_event_manager_t * p_em,
* Public libvlc functions * Public libvlc functions
*/ */
/**************************************************************************
* libvlc_event_type_name (public) :
*
* Get the char * name of an event type.
**************************************************************************/
static const char event_type_to_name[][libvlc_num_event_types] =
{
#define DEF(a) [libvlc_##a]=#a
DEFINE_LIBVLC_EVENT_TYPES
#undef DEF
};
static const char unknown_event_name[] = "Unknown Event";
const char * libvlc_event_type_name( libvlc_event_type_t event_type )
{
if( event_type >= libvlc_num_event_types )
return unknown_event_name;
return event_type_to_name[event_type];
}
/************************************************************************** /**************************************************************************
* event_attach (internal) : * event_attach (internal) :
* *
...@@ -299,8 +278,7 @@ int event_attach( libvlc_event_manager_t * p_event_manager, ...@@ -299,8 +278,7 @@ int event_attach( libvlc_event_manager_t * p_event_manager,
vlc_mutex_unlock( &p_event_manager->object_lock ); vlc_mutex_unlock( &p_event_manager->object_lock );
free(listener); free(listener);
fprintf( stderr, "This object event manager doesn't know about '%s' events", fprintf( stderr, "Unknown event type %d", event_type );
libvlc_event_type_name(event_type) );
assert(0); assert(0);
return -1; return -1;
} }
......
...@@ -29,7 +29,6 @@ libvlc_event_manager_new ...@@ -29,7 +29,6 @@ libvlc_event_manager_new
libvlc_event_manager_register_event_type libvlc_event_manager_register_event_type
libvlc_event_manager_release libvlc_event_manager_release
libvlc_event_send libvlc_event_send
libvlc_event_type_name
libvlc_get_changeset libvlc_get_changeset
libvlc_get_compiler libvlc_get_compiler
libvlc_get_fullscreen libvlc_get_fullscreen
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment