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" {
/*****************************************************************************
* Playlist (Deprecated)
*****************************************************************************/
/** \defgroup libvlc_playlist libvlc_playlist (Deprecated)
/** \defgroup libvlc_playlist LibVLC playlist (legacy)
* \ingroup libvlc
* LibVLC Playlist handling (Deprecated)
* @deprecated Use media_list
* @deprecated Use @ref libvlc_media_list instead.
* @{
*/
......
......@@ -29,9 +29,9 @@
*/
/**
* \defgroup libvlc libvlc
* This is libvlc, the base library of the VLC program.
*
* \defgroup libvlc LibVLC
* 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" {
#include <stdarg.h>
#include <vlc/libvlc_structures.h>
/*****************************************************************************
* Error handling
*****************************************************************************/
/** \defgroup libvlc_error libvlc_error
* \ingroup libvlc_core
* LibVLC error handling
/** \defgroup libvlc_core LibVLC core
* \ingroup libvlc
* Before it can do anything useful, LibVLC must be initialized.
* You can create one (or more) instance(s) of LibVLC in a given process,
* with libvlc_new() and destroy them with libvlc_release().
*
* \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, ...);
/**@} */
/*****************************************************************************
* Core handling
*****************************************************************************/
/** \defgroup libvlc_core libvlc_core
* \ingroup libvlc
* LibVLC Core
* @{
*/
/**
* Create and initialize a libvlc instance.
*
......@@ -162,7 +158,7 @@ void libvlc_wait( libvlc_instance_t *p_instance );
/**
* Retrieve libvlc version.
*
* Example: "0.9.0-git Grishenko"
* Example: "1.1.0-git The Luggage"
*
* \return a string containing the libvlc version
*/
......@@ -186,17 +182,15 @@ VLC_PUBLIC_API const char * libvlc_get_compiler(void);
*/
VLC_PUBLIC_API const char * libvlc_get_changeset(void);
struct vlc_object_t;
/** @}*/
/*****************************************************************************
* Event handling
*****************************************************************************/
/** \defgroup libvlc_event libvlc_event
* \ingroup libvlc_core
* LibVLC Events
/** \defgroup libvlc_event LibVLC asynchronous events
* LibVLC emits asynchronous 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;
* Event manager that belongs to a libvlc object, and from whom events can
* be received.
*/
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
* \param p_event the event triggering the callback
*/
typedef void ( *libvlc_callback_t )( const libvlc_event_t *, void * );
typedef void ( *libvlc_callback_t )( const struct libvlc_event_t *, void * );
/**
* Register for an event notification.
......@@ -245,22 +242,11 @@ VLC_PUBLIC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager
libvlc_callback_t f_callback,
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 );
/** @} */
/*****************************************************************************
* Message log handling
*****************************************************************************/
/** \defgroup libvlc_log libvlc_log
* \ingroup libvlc_core
* LibVLC Message Logging
/** \defgroup libvlc_log LibVLC logging
* libvlc_log_* functions provide access to the LibVLC messages log.
* This is used for debugging or by advanced users.
* @{
*/
......@@ -349,11 +335,11 @@ VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterat
libvlc_log_message_t *p_buffer );
/** @} */
/** @} */
/** @} */
# ifdef __cplusplus
}
# endif
#endif /* <vlc/libvlc.h> */
/** @} */
......@@ -34,105 +34,85 @@
extern "C" {
# endif
/*****************************************************************************
* Events handling
*****************************************************************************/
/** \defgroup libvlc_event libvlc_event
* \ingroup libvlc_core
* LibVLC Available Events
/**
* \ingroup libvlc_event
* @{
*/
/**
* Event types
*/
enum libvlc_event_e {
/* Append new event types at the end. Do not remove, insert or
* re-order any entry. The cpp will prepend libvlc_ to the symbols. */
#define DEFINE_LIBVLC_EVENT_TYPES \
DEF( MediaMetaChanged ), \
DEF( MediaSubItemAdded ), \
DEF( MediaDurationChanged ), \
DEF( MediaPreparsedChanged ), \
DEF( MediaFreed ), \
DEF( MediaStateChanged ), \
\
DEF( MediaPlayerNothingSpecial ), \
DEF( MediaPlayerOpening ), \
DEF( MediaPlayerBuffering ), \
DEF( MediaPlayerPlaying ), \
DEF( MediaPlayerPaused ), \
DEF( MediaPlayerStopped ), \
DEF( MediaPlayerForward ), \
DEF( MediaPlayerBackward ), \
DEF( MediaPlayerEndReached ), \
DEF( MediaPlayerEncounteredError ), \
DEF( MediaPlayerTimeChanged ), \
DEF( MediaPlayerPositionChanged ), \
DEF( MediaPlayerSeekableChanged ), \
DEF( MediaPlayerPausableChanged ), \
\
DEF( MediaListItemAdded ), \
DEF( MediaListWillAddItem ), \
DEF( MediaListItemDeleted ), \
DEF( MediaListWillDeleteItem ), \
\
DEF( MediaListViewItemAdded ), \
DEF( MediaListViewWillAddItem ), \
DEF( MediaListViewItemDeleted ), \
DEF( MediaListViewWillDeleteItem ), \
\
DEF( MediaListPlayerPlayed ), \
DEF( MediaListPlayerNextItemSet ), \
DEF( MediaListPlayerStopped ), \
\
DEF( MediaDiscovererStarted ), \
DEF( MediaDiscovererEnded ), \
\
DEF( MediaPlayerTitleChanged ), \
DEF( MediaPlayerSnapshotTaken ), \
DEF( MediaPlayerLengthChanged ), \
\
DEF( VlmMediaAdded ), \
DEF( VlmMediaRemoved ), \
DEF( VlmMediaChanged ), \
DEF( VlmMediaInstanceStarted ), \
DEF( VlmMediaInstanceStopped ), \
DEF( VlmMediaInstanceStatusInit ), \
DEF( VlmMediaInstanceStatusOpening ), \
DEF( VlmMediaInstanceStatusPlaying ), \
DEF( VlmMediaInstanceStatusPause ), \
DEF( VlmMediaInstanceStatusEnd ), \
DEF( VlmMediaInstanceStatusError ), \
\
DEF( MediaPlayerMediaChanged ), \
/* 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_MediaMetaChanged,
libvlc_MediaSubItemAdded,
libvlc_MediaDurationChanged,
libvlc_MediaPreparsedChanged,
libvlc_MediaFreed,
libvlc_MediaStateChanged,
libvlc_MediaPlayerNothingSpecial,
libvlc_MediaPlayerOpening,
libvlc_MediaPlayerBuffering,
libvlc_MediaPlayerPlaying,
libvlc_MediaPlayerPaused,
libvlc_MediaPlayerStopped,
libvlc_MediaPlayerForward,
libvlc_MediaPlayerBackward,
libvlc_MediaPlayerEndReached,
libvlc_MediaPlayerEncounteredError,
libvlc_MediaPlayerTimeChanged,
libvlc_MediaPlayerPositionChanged,
libvlc_MediaPlayerSeekableChanged,
libvlc_MediaPlayerPausableChanged,
libvlc_MediaListItemAdded,
libvlc_MediaListWillAddItem,
libvlc_MediaListItemDeleted,
libvlc_MediaListWillDeleteItem,
libvlc_MediaListViewItemAdded,
libvlc_MediaListViewWillAddItem,
libvlc_MediaListViewItemDeleted,
libvlc_MediaListViewWillDeleteItem,
libvlc_MediaListPlayerPlayed,
libvlc_MediaListPlayerNextItemSet,
libvlc_MediaListPlayerStopped,
libvlc_MediaDiscovererStarted,
libvlc_MediaDiscovererEnded,
libvlc_MediaPlayerTitleChanged,
libvlc_MediaPlayerSnapshotTaken,
libvlc_MediaPlayerLengthChanged,
libvlc_VlmMediaAdded,
libvlc_VlmMediaRemoved,
libvlc_VlmMediaChanged,
libvlc_VlmMediaInstanceStarted,
libvlc_VlmMediaInstanceStopped,
libvlc_VlmMediaInstanceStatusInit,
libvlc_VlmMediaInstanceStatusOpening,
libvlc_VlmMediaInstanceStatusPlaying,
libvlc_VlmMediaInstanceStatusPause,
libvlc_VlmMediaInstanceStatusEnd,
libvlc_VlmMediaInstanceStatusError,
libvlc_MediaPlayerMediaChanged,
/* New event types HERE */
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
* \param type the even type
* \param p_obj the sender object
* \param u Event dependent content
* A LibVLC event
*/
struct libvlc_event_t
typedef struct libvlc_event_t
{
libvlc_event_type_t type;
void * p_obj;
union event_type_specific
int type; /**< Event type (see @ref libvlc_event_e) */
void *p_obj; /**< Object emitting the event */
union
{
/* media descriptor */
struct
......@@ -234,8 +214,8 @@ struct libvlc_event_t
{
libvlc_media_t * new_media;
} media_player_media_changed;
} u;
};
} u; /**< Type-dependent event description */
} libvlc_event_t;
/**@} */
......
......@@ -35,24 +35,21 @@
extern "C" {
# endif
/*****************************************************************************
* media
*****************************************************************************/
/** \defgroup libvlc_media libvlc_media
/** \defgroup libvlc_media LibVLC media
* \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;
/* Meta Handling */
/** defgroup libvlc_meta libvlc_meta
/** defgroup libvlc_meta LibVLC meta data
* \ingroup libvlc_media
* LibVLC Media Meta
* @{
*/
/** Meta data types */
typedef enum libvlc_meta_t {
libvlc_meta_Title,
libvlc_meta_Artist,
......@@ -111,9 +108,8 @@ typedef enum libvlc_es_type_t
libvlc_es_text = 2,
} libvlc_es_type_t;
/** defgroup libvlc_media_stats_t libvlc_media_stats_t
/** defgroup libvlc_media_stats_t LibVLC media statistics
* \ingroup libvlc_media
* LibVLC Media statistics
* @{
*/
typedef struct libvlc_media_stats_t
......
......@@ -35,12 +35,13 @@
extern "C" {
# endif
/*****************************************************************************
* Services/Media Discovery
*****************************************************************************/
/** \defgroup libvlc_media_discoverer libvlc_media_discoverer
/** \defgroup libvlc_media_discoverer LibVLC media discovery
* \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 @@
extern "C" {
# endif
/*****************************************************************************
* Media Library
*****************************************************************************/
/** \defgroup libvlc_media_library libvlc_media_library
/** \defgroup libvlc_media_library LibVLC media library
* \ingroup libvlc
* LibVLC Media Library
* @{
*/
......
......@@ -33,12 +33,9 @@
extern "C" {
# endif
/*****************************************************************************
* Media List
*****************************************************************************/
/** \defgroup libvlc_media_list libvlc_media_list
/** \defgroup libvlc_media_list LibVLC media list
* \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" {
/*****************************************************************************
* Media List Player
*****************************************************************************/
/** \defgroup libvlc_media_list_player libvlc_media_list_player
/** \defgroup libvlc_media_list_player LibVLC media list player
* \ingroup libvlc
* LibVLC Media List Player, play a media_list. You can see that as a media
* instance subclass
* The LibVLC media list player plays a @ref libvlc_media_list_t list of media,
* 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" {
/*****************************************************************************
* Media Player
*****************************************************************************/
/** \defgroup libvlc_media_player libvlc_media_player
/** \defgroup libvlc_media_player LibVLC media player
* \ingroup libvlc
* LibVLC Media Player, object that let you play a media
* in a custom drawable
* A LibVLC media player plays one media (usually in a custom drawable).
* @{
*/
......@@ -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
* respect the protocol:
*
* @protocol VLCOpenGLVideoViewEmbedding <NSObject>
* @begincode
* \@protocol VLCOpenGLVideoViewEmbedding <NSObject>
* - (void)addVoutSubview:(NSView *)view;
* - (void)removeVoutSubview:(NSView *)view;
* @end
* \@end
* @endcode
*
* 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
*/
VLC_PUBLIC_API void libvlc_track_description_release( libvlc_track_description_t *p_track_description );
/** \defgroup libvlc_video libvlc_video
* \ingroup libvlc_media_player
* LibVLC Video handling
/** \defgroup libvlc_video LibVLC video controls
* @{
*/
......@@ -909,9 +908,7 @@ VLC_PUBLIC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi,
/** @} video */
/** \defgroup libvlc_audio libvlc_audio
* \ingroup libvlc_media_player
* LibVLC Audio handling
/** \defgroup libvlc_audio LibVLC audio controls
* @{
*/
......
......@@ -37,9 +37,8 @@ extern "C" {
/*****************************************************************************
* VLM
*****************************************************************************/
/** \defgroup libvlc_vlm libvlc_vlm
/** \defgroup libvlc_vlm LibVLC VLM
* \ingroup libvlc
* LibVLC VLM
* @{
*/
......
......@@ -240,27 +240,6 @@ void libvlc_event_send( libvlc_event_manager_t * p_em,
* 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) :
*
......@@ -299,8 +278,7 @@ int event_attach( libvlc_event_manager_t * p_event_manager,
vlc_mutex_unlock( &p_event_manager->object_lock );
free(listener);
fprintf( stderr, "This object event manager doesn't know about '%s' events",
libvlc_event_type_name(event_type) );
fprintf( stderr, "Unknown event type %d", event_type );
assert(0);
return -1;
}
......
......@@ -29,7 +29,6 @@ libvlc_event_manager_new
libvlc_event_manager_register_event_type
libvlc_event_manager_release
libvlc_event_send
libvlc_event_type_name
libvlc_get_changeset
libvlc_get_compiler
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