# HG changeset patch # User Mike Ruprecht # Date 1218246606 0 # Node ID b8a73b6dc0a4200cff39b248f06b373fe699e24b # Parent 97f3a3409a1d552cd4c3131524f0c225352cc19e * Added documentation to media.h and mediamanager.h * Removed unnecessary includes from a few files * Fixed a few parameter names diff -r 97f3a3409a1d -r b8a73b6dc0a4 Doxyfile.in --- a/Doxyfile.in Sun Aug 03 23:31:48 2008 +0000 +++ b/Doxyfile.in Sat Aug 09 01:50:06 2008 +0000 @@ -1070,7 +1070,7 @@ # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = +PREDEFINED = USE_VV # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff -r 97f3a3409a1d -r b8a73b6dc0a4 libpurple/media.c --- a/libpurple/media.c Sun Aug 03 23:31:48 2008 +0000 +++ b/libpurple/media.c Sat Aug 09 01:50:06 2008 +0000 @@ -1,8 +1,9 @@ /** * @file media.c Media API * @ingroup core - * - * purple + */ + +/* purple * * Purple is the legal property of its developers, whose names are too numerous * to list here. Please refer to the COPYRIGHT file distributed with this @@ -748,7 +749,7 @@ purple_media_get_element(const gchar *factory_name) { GstElementFactory *factory = gst_element_factory_find(factory_name); - GstElement *element = gst_element_factory_create(factory, "video_src"); + GstElement *element = gst_element_factory_create(factory, NULL); gst_object_unref(factory); return element; } diff -r 97f3a3409a1d -r b8a73b6dc0a4 libpurple/media.h --- a/libpurple/media.h Sun Aug 03 23:31:48 2008 +0000 +++ b/libpurple/media.h Sat Aug 09 01:50:06 2008 +0000 @@ -1,8 +1,9 @@ /** * @file media.h Media API * @ingroup core - * - * purple + */ + +/* purple * * Purple is the legal property of its developers, whose names are too numerous * to list here. Please refer to the COPYRIGHT file distributed with this @@ -30,12 +31,9 @@ #include #include -#include #include #include -#include "connection.h" - G_BEGIN_DECLS #define PURPLE_TYPE_MEDIA (purple_media_get_type()) @@ -45,9 +43,13 @@ #define PURPLE_IS_MEDIA_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEDIA)) #define PURPLE_MEDIA_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEDIA, PurpleMediaClass)) +/** @copydoc _PurpleMedia */ typedef struct _PurpleMedia PurpleMedia; +/** @copydoc _PurpleMediaClass */ typedef struct _PurpleMediaClass PurpleMediaClass; +/** @copydoc _PurpleMediaPrivate */ typedef struct _PurpleMediaPrivate PurpleMediaPrivate; +/** @copydoc _PurpleMediaSession */ typedef struct _PurpleMediaSession PurpleMediaSession; #else @@ -56,6 +58,7 @@ #endif /* USE_VV */ +/** Media session types */ typedef enum { PURPLE_MEDIA_NONE = 0, PURPLE_MEDIA_RECV_AUDIO = 1 << 0, @@ -68,89 +71,449 @@ #ifdef USE_VV +/** The media class */ struct _PurpleMediaClass { - GObjectClass parent_class; + GObjectClass parent_class; /**< The parent class. */ }; +/** The media class's private data */ struct _PurpleMedia { - GObject parent; - PurpleMediaPrivate *priv; + GObject parent; /**< The parent of this object. */ + PurpleMediaPrivate *priv; /**< The private data of this object. */ }; +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Gets the media class's GType + * + * @return The media class's GType. + */ GType purple_media_get_type(void); +/**************************************************************************/ +/** @name Media Utility Functions */ +/**************************************************************************/ +/*@{*/ + +/** + * Converts a PurpleMediaStreamType to an FsMediaType. + * + * @param type The type to derive FsMediaType from + * + * @return The FsMediaType derived from type + */ FsMediaType purple_media_to_fs_media_type(PurpleMediaStreamType type); + +/** + * Converts a PurpleMediaStreamType to an FsStreamDirection. + * + * @param type The type to derive FsMediaType from + * + * @return The FsMediaDirection derived from type + */ FsStreamDirection purple_media_to_fs_stream_direction(PurpleMediaStreamType type); + +/** + * Converts an FsMediaType and FsStreamDirection into a PurpleMediaStreamType. + * + * @param type The type used to construct PurpleMediaStreamType + * @param direction The direction used to construct PurpleMediaStreamType + * + * @return The PurpleMediaStreamType constructed + */ PurpleMediaStreamType purple_media_from_fs(FsMediaType type, FsStreamDirection direction); +/*@}*/ + +/** + * Combines all the separate session types into a single PurpleMediaStreamType. + * + * @param media The media session to retrieve session types from. + * + * @return Combined type. + */ PurpleMediaStreamType purple_media_get_overall_type(PurpleMedia *media); +/** + * Gets a list of session names. + * + * @param media The media session to retrieve session names from. + * + * @return GList of session names. + */ GList *purple_media_get_session_names(PurpleMedia *media); -void purple_media_get_elements(PurpleMedia *media, GstElement **audio_src, GstElement **audio_sink, - GstElement **video_src, GstElement **video_sink); +/** + * Gets an audio and video source and sink from the media session. + * + * Retrieves the first of each element in the media session. + * + * @param media The media session to retreive the sources and sinks from. + * @param audio_src Set to the audio source. + * @param audio_sink Set to the audio sink. + * @param video_src Set to the video source. + * @param video_sink Set to the video sink. + */ +void purple_media_get_elements(PurpleMedia *media, + GstElement **audio_src, GstElement **audio_sink, + GstElement **video_src, GstElement **video_sink); +/** + * Sets the source on a session. + * + * @param media The media object the session is in. + * @param sess_id The session id of the session to set the source on. + * @param src The source to set the session source to. + */ void purple_media_set_src(PurpleMedia *media, const gchar *sess_id, GstElement *src); -void purple_media_set_sink(PurpleMedia *media, const gchar *sess_id, GstElement *src); + +/** + * Sets the sink on a session. + * + * @param media The media object the session is in. + * @param sess_id The session id of the session to set the sink on. + * @param sink The source to set the session sink to. + */ +void purple_media_set_sink(PurpleMedia *media, const gchar *sess_id, GstElement *sink); +/** + * Gets the source from a session + * + * @param media The media object the session is in. + * @param sess_id The session id of the session to get the source from. + * + * @return The source retrieved. + */ GstElement *purple_media_get_src(PurpleMedia *media, const gchar *sess_id); + +/** + * Gets the sink from a session + * + * @param media The media object the session is in. + * @param sess_id The session id of the session to get the source from. + * + * @return The sink retrieved. + */ GstElement *purple_media_get_sink(PurpleMedia *media, const gchar *sess_id); +/** + * Gets the pipeline from the media session. + * + * @param media The media session to retrieve the pipeline from. + * + * @return The pipeline retrieved. + */ GstElement *purple_media_get_pipeline(PurpleMedia *media); +/** + * Gets the connection the media session is associated with. + * + * @param media The media object to retrieve the connection from. + * + * @return The retreived connection. + */ PurpleConnection *purple_media_get_connection(PurpleMedia *media); + +/** + * Gets the screenname of the remote user. + * + * @param media The media object to retrieve the remote user from. + * + * @return The retrieved screenname. + */ const char *purple_media_get_screenname(PurpleMedia *media); + +/** + * Set the media session to the ready state. + * + * @param media The media object to set the state on. + */ void purple_media_ready(PurpleMedia *media); + +/** + * Set the media session to the wait state. + * + * @param media The media object to set the state on. + */ void purple_media_wait(PurpleMedia *media); + +/** + * Set the media session to the accepted state. + * + * @param media The media object to set the state on. + */ void purple_media_accept(PurpleMedia *media); + +/** + * Set the media session to the rejected state. + * + * @param media The media object to set the state on. + */ void purple_media_reject(PurpleMedia *media); + +/** + * Set the media session to the hangup state. + * + * @param media The media object to set the state on. + */ void purple_media_hangup(PurpleMedia *media); + +/** + * Set the media session to the got_request state. + * + * @param media The media object to set the state on. + */ void purple_media_got_request(PurpleMedia *media); + +/** + * Set the media session to the got_hangup state. + * + * @param media The media object to set the state on. + */ void purple_media_got_hangup(PurpleMedia *media); + +/** + * Set the media session to the got_accept state. + * + * @param media The media object to set the state on. + */ void purple_media_got_accept(PurpleMedia *media); -gchar *purple_media_get_device_name(GstElement *element, - GValue *device); +/** + * Gets the name of a device. + * + * @param element The plugin the device is from. + * @param device The device data to retreive the name from. + * + * @return The name of the device. + */ +gchar *purple_media_get_device_name(GstElement *element, + GValue *device); +/** + * Enumerates a list of devices. + * + * @param element The plugin from which to enumerate devices. + * + * @return The list of enumerated devices. + */ GList *purple_media_get_devices(GstElement *element); + +/** + * Sets the device to be used with the particular plugin. + * + * @param element The plugin to set the device on. + * @param device The device to set the plugin to. + */ void purple_media_element_set_device(GstElement *element, GValue *device); + +/** + * Sets the device from the given name. + * + * @param element The plugin to set the device on. + * @param name The name of the device to set the plugin to. + */ void purple_media_element_set_device_from_name(GstElement *element, - const gchar *name); + const gchar *name); + +/** + * Gets the device the plugin is currently set to. + * + * @param element The plugin to retrieve the device from. + * + * @return The device retrieved. + */ GValue *purple_media_element_get_device(GstElement *element); + +/** + * Creates an element from a factory name. + * + * @param factory_name Name of the factory to create an element from. + * + * @return The element that was created. + */ GstElement *purple_media_get_element(const gchar *factory_name); +/** + * Creates a default audio source. + * + * @param sendbin Set to the newly created audio source. + * @param sendlevel Set to the newly created level within the audio source. + */ void purple_media_audio_init_src(GstElement **sendbin, GstElement **sendlevel); + +/** + * Creates a default video source. + * + * @param sendbin Set to the newly created video source. + */ void purple_media_video_init_src(GstElement **sendbin); +/** + * Creates a default audio sink. + * + * @param recvbin Set to the newly created audio sink. + * @param recvlevel Set to the newly created level within the audio sink. + */ void purple_media_audio_init_recv(GstElement **recvbin, GstElement **recvlevel); + +/** + * Creates a default video sink. + * + * @param sendbin Set to the newly created video sink. + */ void purple_media_video_init_recv(GstElement **sendbin); +/** + * Adds a stream to a session. + * + * @param media The media object to find the session in. + * @param sess_id The session id of the session to add the stream to. + * @param who The name of the remote user to add the stream for. + * @param type The type of stream to create. + * @param transmitter The transmitter to use for the stream. + * + * @return @c TRUE The stream was added successfully, @c FALSE otherwise. + */ gboolean purple_media_add_stream(PurpleMedia *media, const gchar *sess_id, const gchar *who, PurpleMediaStreamType type, const gchar *transmitter); + +/** + * Removes a stream from a session. + * + * @param media The media object to find the session in. + * @param sess_id The session id of the session to remove the stream from. + * @param who The name of the remote user to remove the stream from. + */ void purple_media_remove_stream(PurpleMedia *media, const gchar *sess_id, const gchar *who); +/** + * Gets the session type from a session + * + * @param media The media object to find the session in. + * @param sess_id The session id of the session to get the type from. + * + * @return The retreived session type. + */ PurpleMediaStreamType purple_media_get_session_type(PurpleMedia *media, const gchar *sess_id); +/** + * Gets the negotiated codecs from a session. + * + * @param media The media object to find the session in. + * @param sess_id The session id of the session to get the negotiated codecs from. + * + * @return The retreieved codecs. + */ GList *purple_media_get_negotiated_codecs(PurpleMedia *media, const gchar *sess_id); +/** + * Gets the local codecs from a session. + * + * @param media The media object to find the session in. + * @param sess_id The session id of the session to get the local codecs from. + * + * @return The retreieved codecs. + */ GList *purple_media_get_local_codecs(PurpleMedia *media, const gchar *sess_id); -void purple_media_add_remote_candidates(PurpleMedia *media, const gchar *sess_id, - const gchar *name, GList *remote_candidates); -GList *purple_media_get_local_candidates(PurpleMedia *media, const gchar *sess_id, const gchar *name); + +/** + * Adds remote candidates to the stream. + * + * @param media The media object to find the session in. + * @param sess_id The session id of the session find the stream in. + * @param name The name of the remote user to add the candidates for. + * @param remote_candidates The remote candidates to add. + */ +void purple_media_add_remote_candidates(PurpleMedia *media, + const gchar *sess_id, + const gchar *name, + GList *remote_candidates); + +/** + * Gets the local candidates from a stream. + * + * @param media The media object to find the session in. + * @param sess_id The session id of the session to find the stream in. + * @param name The name of the remote user to get the candidates from. + */ +GList *purple_media_get_local_candidates(PurpleMedia *media, + const gchar *sess_id, + const gchar *name); + +/** + * Gets the active local candidate for the stream. + * + * @param media The media object to find the session in. + * @param sess_id The session id of the session to find the stream in. + * @param name The name of the remote user to get the active candidate from. + * + * @return The active candidate retrieved. + */ FsCandidate *purple_media_get_local_candidate(PurpleMedia *media, const gchar *sess_id, const gchar *name); + +/** + * Gets the active remote candidate for the stream. + * + * @param media The media object to find the session in. + * @param sess_id The session id of the session to find the stream in. + * @param name The name of the remote user to get the remote candidate from. + * + * @return The remote candidate retrieved. + */ FsCandidate *purple_media_get_remote_candidate(PurpleMedia *media, const gchar *sess_id, const gchar *name); + +/** + * Gets remote candidates from the stream. + * + * @param media The media object to find the session in. + * @param sess_id The session id of the session find the stream in. + * @param name The name of the remote user to get the candidates from. + * + * @return @c TRUE The codecs were set successfully, or @c FALSE otherwise. + */ gboolean purple_media_set_remote_codecs(PurpleMedia *media, const gchar *sess_id, const gchar *name, GList *codecs); +/** + * Returns whether or not the candidates for a remote user are prepared + * + * @param media The media object to find the remote user in. + * @param name The remote user to check for. + * + * @return @c TRUE All streams for the remote user have candidates prepared, @c FALSE otherwise. + */ gboolean purple_media_candidates_prepared(PurpleMedia *media, const gchar *name); +/** + * Sets the send codec for the a session. + * + * @param media The media object to find the session in. + * @param sess_id The session id of the session to set the codec for. + * @param codec The codec to set the session to stream. + * + * @return @c TRUE The codec was successfully changed, or @c FALSE otherwise. + */ gboolean purple_media_set_send_codec(PurpleMedia *media, const gchar *sess_id, FsCodec *codec); +/** + * Mutes or unmutes all the audio local audio sources. + * + * @param media The media object to mute or unmute + * @param active @c TRUE to mutes all of the local audio sources, or @c FALSE to unmute. + */ void purple_media_mute(PurpleMedia *media, gboolean active); +#ifdef __cplusplus +} +#endif + G_END_DECLS #endif /* USE_VV */ diff -r 97f3a3409a1d -r b8a73b6dc0a4 libpurple/mediamanager.c --- a/libpurple/mediamanager.c Sun Aug 03 23:31:48 2008 +0000 +++ b/libpurple/mediamanager.c Sat Aug 09 01:50:06 2008 +0000 @@ -1,8 +1,9 @@ /** * @file mediamanager.c Media Manager API * @ingroup core - * - * purple + */ + +/* purple * * Purple is the legal property of its developers, whose names are too numerous * to list here. Please refer to the COPYRIGHT file distributed with this diff -r 97f3a3409a1d -r b8a73b6dc0a4 libpurple/mediamanager.h --- a/libpurple/mediamanager.h Sun Aug 03 23:31:48 2008 +0000 +++ b/libpurple/mediamanager.h Sat Aug 09 01:50:06 2008 +0000 @@ -1,8 +1,9 @@ /** * @file mediamanager.h Media Manager API * @ingroup core - * - * purple + */ + +/* purple * * Purple is the legal property of its developers, whose names are too numerous * to list here. Please refer to the COPYRIGHT file distributed with this @@ -28,7 +29,6 @@ #ifdef USE_VV -#include #include #include @@ -44,28 +44,70 @@ #define PURPLE_IS_MEDIA_MANAGER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), PURPLE_TYPE_MEDIA_MANAGER)) #define PURPLE_MEDIA_MANAGER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), PURPLE_TYPE_MEDIA_MANAGER, PurpleMediaManagerClass)) +/** @copydoc _PurpleMediaManager */ typedef struct _PurpleMediaManager PurpleMediaManager; +/** @copydoc _PurpleMediaManagerClass */ typedef struct _PurpleMediaManagerClass PurpleMediaManagerClass; +/** @copydoc _PurpleMediaManagerPrivate */ typedef struct _PurpleMediaManagerPrivate PurpleMediaManagerPrivate; +/** The media manager class. */ struct _PurpleMediaManagerClass { - GObjectClass parent_class; + GObjectClass parent_class; /**< The parent class. */ +}; + +/** The media manager's data. */ +struct _PurpleMediaManager +{ + GObject parent; /**< The parent of this manager. */ + PurpleMediaManagerPrivate *priv; /**< Private data for the manager. */ }; -struct _PurpleMediaManager -{ - GObject parent; - PurpleMediaManagerPrivate *priv; -}; +#ifdef __cplusplus +extern "C" { +#endif + +/**************************************************************************/ +/** @cname Media Manager API */ +/**************************************************************************/ +/*@{*/ + +/** + * Gets the media manager's GType. + * + * @return The media manager's GType. + */ +GType purple_media_manager_get_type(void); -GType purple_media_manager_get_type(void); +/** + * Gets the "global" media manager object. It's created if it doesn't already exist. + * + * @return The "global" instance of the media manager object. + */ PurpleMediaManager *purple_media_manager_get(void); + +/** + * Creates a media session. + * + * @param manager The media manager to create the session under. + * @param gc The connection to create the session on. + * @param conference_type The conference type to feed into Farsight2. + * @param remote_user The remote user to initiate the session with. + * + * @return A newly created media session. + */ PurpleMedia *purple_media_manager_create_media(PurpleMediaManager *manager, PurpleConnection *gc, const char *conference_type, const char *remote_user); +/*}@*/ + +#ifdef __cplusplus +} +#endif + G_END_DECLS #endif /* USE_VV */ diff -r 97f3a3409a1d -r b8a73b6dc0a4 libpurple/server.h --- a/libpurple/server.h Sun Aug 03 23:31:48 2008 +0000 +++ b/libpurple/server.h Sat Aug 09 01:50:06 2008 +0000 @@ -29,7 +29,6 @@ #include "account.h" #include "conversation.h" #include "prpl.h" -#include "media.h" #ifdef __cplusplus extern "C" {