/*****************************************************************************
* 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.
* @{
*/
*/
/**
- * \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.
* @{
*/
#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
* @{
*/
/**@} */
-
-/*****************************************************************************
- * Core handling
- *****************************************************************************/
-
-/** \defgroup libvlc_core libvlc_core
- * \ingroup libvlc
- * LibVLC Core
- * @{
- */
-
/**
* Create and initialize a libvlc instance.
*
/**
* Retrieve libvlc version.
*
- * Example: "0.9.0-git Grishenko"
+ * Example: "1.1.0-git The Luggage"
*
* \return a string containing the libvlc version
*/
*/
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().
* @{
*/
* 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.
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.
* @{
*/
libvlc_log_message_t *p_buffer );
/** @} */
+/** @} */
+/** @} */
# ifdef __cplusplus
}
# endif
#endif /* <vlc/libvlc.h> */
-
-/** @} */
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
{
libvlc_media_t * new_media;
} media_player_media_changed;
- } u;
-};
+ } u; /**< Type-dependent event description */
+} libvlc_event_t;
/**@} */
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,
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
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).
* @{
*/
extern "C" {
# endif
-/*****************************************************************************
- * Media Library
- *****************************************************************************/
-/** \defgroup libvlc_media_library libvlc_media_library
+/** \defgroup libvlc_media_library LibVLC media library
* \ingroup libvlc
- * LibVLC Media Library
* @{
*/
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.
* @{
*/
/*****************************************************************************
* 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.
* @{
*/
/*****************************************************************************
* 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).
* @{
*/
* 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.
*
*/
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
* @{
*/
/** @} video */
-/** \defgroup libvlc_audio libvlc_audio
- * \ingroup libvlc_media_player
- * LibVLC Audio handling
+/** \defgroup libvlc_audio LibVLC audio controls
* @{
*/
/*****************************************************************************
* VLM
*****************************************************************************/
-/** \defgroup libvlc_vlm libvlc_vlm
+/** \defgroup libvlc_vlm LibVLC VLM
* \ingroup libvlc
- * LibVLC VLM
* @{
*/
* 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) :
*
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;
}
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
projects / vlc / commitdiff