Commit 7b7f2fe0 authored by Olivier Aubert's avatar Olivier Aubert

mediacontrol: doxygen updates

parent 53af6645
......@@ -21,6 +21,14 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
/**
* \defgroup mediacontrol MediaControl
* This is the MediaControl API, * intended to provide a generic API to movie players.
*
* @{
*/
#ifndef _VLC_CONTROL_H
#define _VLC_CONTROL_H 1
......@@ -36,10 +44,10 @@ extern "C" {
#include <vlc/mediacontrol_structures.h>
/************************************************************************
* Position Object Manipulation
*************************************************************************/
/**
* RGBPicture structure
* This generic structure holds a picture in an encoding specified by type.
*/
typedef struct {
int width;
int height;
......@@ -49,6 +57,10 @@ typedef struct {
char *data;
} mediacontrol_RGBPicture;
/**
* Playlist sequence
* A simple list of strings.
*/
typedef struct {
int size;
char **data;
......@@ -59,18 +71,24 @@ typedef struct {
char *message;
} mediacontrol_Exception;
/* Exception codes */
/**
* Exception codes
*/
#define mediacontrol_PositionKeyNotSupported 1
#define mediacontrol_PositionOriginNotSupported 2
#define mediacontrol_InvalidPosition 3
#define mediacontrol_PlaylistException 4
#define mediacontrol_InternalException 5
/* mediacontrol_Instance is an opaque structure, defined in
mediacontrol_internal.h. API users do not have to mess with it. */
/**
* mediacontrol_Instance is an opaque structure, defined in
* mediacontrol_internal.h. API users do not have to mess with it.
*/
typedef struct mediacontrol_Instance mediacontrol_Instance;
/* Cf stream_control.h */
/**
* Possible player status
*/
enum mediacontrol_PlayerStatusList
{
mediacontrol_PlayingStatus, mediacontrol_PauseStatus,
......@@ -80,6 +98,10 @@ enum mediacontrol_PlayerStatusList
};
typedef enum mediacontrol_PlayerStatusList mediacontrol_PlayerStatus;
/**
* Stream information
* This structure allows to quickly get various informations about the stream.
*/
typedef struct {
mediacontrol_PlayerStatus streamstatus;
char *url; /* The URL of the current media stream */
......@@ -91,8 +113,16 @@ typedef struct {
* Helper functions
***************************************************************************/
/**
* Allocate a RGBPicture structure.
* \param datasize: the size of the data
*/
mediacontrol_RGBPicture *mediacontrol_RGBPicture__alloc( int datasize );
/**
* Free a RGBPicture structure.
* \param pic: the RGBPicture structure
*/
void mediacontrol_RGBPicture__free( mediacontrol_RGBPicture *pic );
mediacontrol_RGBPicture *
......@@ -103,58 +133,144 @@ mediacontrol_PlaylistSeq *mediacontrol_PlaylistSeq__alloc( int size );
void mediacontrol_PlaylistSeq__free( mediacontrol_PlaylistSeq *ps );
/**
* Initialize an exception structure.
* \param p_exception the exception to initialize. If NULL, a new exception will be created.
* \return the exception
*/
mediacontrol_Exception *
mediacontrol_exception_init( mediacontrol_Exception *exception );
/**
* Free an exception structure.
* \return the exception
*/
void mediacontrol_exception_free(mediacontrol_Exception *exception);
/*****************************************************************************
* Core functions
*****************************************************************************/
/**
* Create a MediaControl instance with parameters
* \param argc the number of arguments
* \param argv parameters
* \param exception an initialized exception pointer
* \return a mediacontrol_Instance
*/
mediacontrol_Instance *
mediacontrol_new( int argc, char **argv, mediacontrol_Exception *exception );
/* Bridge with the libvlc API */
/**
* Create a MediaControl instance from an existing libvlc instance
* \param p_instance the libvlc instance
* \param exception an initialized exception pointer
* \return a mediacontrol_Instance
*/
mediacontrol_Instance *
mediacontrol_new_from_instance( libvlc_instance_t* p_instance,
mediacontrol_Exception *exception );
/**
* Get the associated libvlc instance
* \param self: the mediacontrol instance
* \return a libvlc instance
*/
libvlc_instance_t*
mediacontrol_get_libvlc_instance( mediacontrol_Instance* self );
/**
* Get the current position
* \param self the mediacontrol instance
* \param an_origin the position origin
* \param a_key the position unit
* \param exception an initialized exception pointer
* \return a mediacontrol_Position
*/
mediacontrol_Position * mediacontrol_get_media_position(
mediacontrol_Instance *self,
const mediacontrol_PositionOrigin an_origin,
const mediacontrol_PositionKey a_key,
mediacontrol_Exception *exception );
/**
* Set the position
* \param self the mediacontrol instance
* \param a_position a mediacontrol_Position
* \param exception an initialized exception pointer
*/
void mediacontrol_set_media_position( mediacontrol_Instance *self,
const mediacontrol_Position *a_position,
mediacontrol_Exception *exception );
/**
* Play the movie at a given position
* \param self the mediacontrol instance
* \param a_position a mediacontrol_Position
* \param exception an initialized exception pointer
*/
void mediacontrol_start( mediacontrol_Instance *self,
const mediacontrol_Position *a_position,
mediacontrol_Exception *exception );
/**
* Pause the movie at a given position
* \param self the mediacontrol instance
* \param a_position a mediacontrol_Position (ignored for now)
* \param exception an initialized exception pointer
*/
void mediacontrol_pause( mediacontrol_Instance *self,
const mediacontrol_Position *a_position,
mediacontrol_Exception *exception );
/**
* Resume the movie at a given position
* \param self the mediacontrol instance
* \param a_position a mediacontrol_Position (ignored for now)
* \param exception an initialized exception pointer
*/
void mediacontrol_resume( mediacontrol_Instance *self,
const mediacontrol_Position *a_position,
mediacontrol_Exception *exception );
/**
* Stop the movie at a given position
* \param self the mediacontrol instance
* \param a_position a mediacontrol_Position (ignored for now)
* \param exception an initialized exception pointer
*/
void mediacontrol_stop( mediacontrol_Instance *self,
const mediacontrol_Position *a_position,
mediacontrol_Exception *exception );
/**
* Exit the player
* \param self the mediacontrol instance
*/
void mediacontrol_exit( mediacontrol_Instance *self );
/**
* Add a new MRL to the playlist
* \param self the mediacontrol instance
* \param psz_file the MRL
* \param exception an initialized exception pointer
*/
void mediacontrol_playlist_add_item( mediacontrol_Instance *self,
const char* psz_file,
mediacontrol_Exception *exception );
/**
* Clear the playlist
* \param self the mediacontrol instance
* \param exception an initialized exception pointer
*/
void mediacontrol_playlist_clear( mediacontrol_Instance *self,
mediacontrol_Exception *exception );
/**
* Get a flattened view of the playlist
* \param self the mediacontrol instance
* \param exception an initialized exception pointer
* \return a list of strings
*/
mediacontrol_PlaylistSeq *
mediacontrol_playlist_get_list( mediacontrol_Instance *self,
mediacontrol_Exception *exception );
......@@ -163,50 +279,118 @@ mediacontrol_PlaylistSeq *
/*****************************************************************************
* A/V functions
*****************************************************************************/
/**
* Get a snapshot
* \param self the mediacontrol instance
* \param a_position the desired position (ignored for now)
* \param exception an initialized exception pointer
* \return a RGBpicture
*/
mediacontrol_RGBPicture *
mediacontrol_snapshot( mediacontrol_Instance *self,
const mediacontrol_Position *a_position,
mediacontrol_Exception *exception );
/* Return a NULL terminated list */
/**
* Get a list of all cached snapshots (unimplemented)
* \param self the mediacontrol instance
* \param exception an initialized exception pointer
* \return a NULL-terminated list of RGBpicture
*/
mediacontrol_RGBPicture **
mediacontrol_all_snapshots( mediacontrol_Instance *self,
mediacontrol_Exception *exception );
/* Displays the message string, between "begin" and "end" positions */
/**
* Displays the message string, between "begin" and "end" positions.
* \param self the mediacontrol instance
* \param message the message to display
* \param begin the begin position
* \param end the end position
* \param exception an initialized exception pointer
*/
void mediacontrol_display_text( mediacontrol_Instance *self,
const char *message,
const mediacontrol_Position *begin,
const mediacontrol_Position *end,
mediacontrol_Exception *exception );
/**
* Get information about a stream
* \param self the mediacontrol instance
* \param a_key the time unit
* \param exception an initialized exception pointer
* \return a mediacontrol_StreamInformation
*/
mediacontrol_StreamInformation *
mediacontrol_get_stream_information( mediacontrol_Instance *self,
mediacontrol_PositionKey a_key,
mediacontrol_Exception *exception );
/**
* Get the current audio level, normalized in [0..100]
* \param self the mediacontrol instance
* \param exception an initialized exception pointer
* \return the volume
*/
unsigned short
mediacontrol_sound_get_volume( mediacontrol_Instance *self,
mediacontrol_Exception *exception );
/**
* Set the audio level
* \param self the mediacontrol instance
* \param volume the volume (normalized in [0..100])
* \param exception an initialized exception pointer
*/
void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
const unsigned short volume,
mediacontrol_Exception *exception );
/**
* Set the video output window
* \param self the mediacontrol instance
* \param visual_id the Xid or HWND, depending on the platform
* \param exception an initialized exception pointer
*/
vlc_bool_t mediacontrol_set_visual( mediacontrol_Instance *self,
WINDOWHANDLE visual_id,
mediacontrol_Exception *exception );
/* Rate in percent. 100 is normal rate. */
/**
* Get the current playing rate, in percent
* \param self the mediacontrol instance
* \param exception an initialized exception pointer
* \return the rate
*/
int mediacontrol_get_rate( mediacontrol_Instance *self,
mediacontrol_Exception *exception );
/**
* Set the playing rate, in percent
* \param self the mediacontrol instance
* \param rate the desired rate
* \param exception an initialized exception pointer
*/
void mediacontrol_set_rate( mediacontrol_Instance *self,
const int rate,
mediacontrol_Exception *exception );
/**
* Get current fullscreen status
* \param self the mediacontrol instance
* \param exception an initialized exception pointer
* \return the fullscreen status
*/
int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
mediacontrol_Exception *exception );
/**
* Set fullscreen status
* \param self the mediacontrol instance
* \param b_fullscreen the desired status
* \param exception an initialized exception pointer
*/
void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
const int b_fullscreen,
mediacontrol_Exception *exception );
......@@ -216,3 +400,5 @@ void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
# endif
#endif
/** @} */
......@@ -20,6 +20,12 @@
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
/**
* \defgroup mediacontrol_structures MediaControl Structures
* Data structures used in the MediaControl API.
*
* @{
*/
#ifndef _VLC_CONTROL_STRUCTURES_H
#define _VLC_CONTROL_STRUCTURES_H 1
......@@ -28,18 +34,33 @@
extern "C" {
# endif
/**
* A position may have different origins:
* - absolute counts from the movie start
* - relative counts from the current position
* - modulo counts from the current position and wraps at the end of the movie
*/
typedef enum {
mediacontrol_AbsolutePosition,
mediacontrol_RelativePosition,
mediacontrol_ModuloPosition
} mediacontrol_PositionOrigin;
/**
* Units available in mediacontrol Positions
* - ByteCount number of bytes
* - SampleCount number of frames
* - MediaTime time in milliseconds
*/
typedef enum {
mediacontrol_ByteCount,
mediacontrol_SampleCount,
mediacontrol_MediaTime
} mediacontrol_PositionKey;
/**
* MediaControl Position
*/
typedef struct {
mediacontrol_PositionOrigin origin;
mediacontrol_PositionKey key;
......@@ -51,3 +72,5 @@ typedef struct {
# endif
#endif
/** @} */
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