changeset 25715:b8a73b6dc0a4

* Added documentation to media.h and mediamanager.h * Removed unnecessary includes from a few files * Fixed a few parameter names

--- 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. 

--- 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;
 }

--- 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 <gst/gst.h>
 #include <gst/farsight/fs-stream.h>
-#include <gst/farsight/fs-session.h>
 #include <glib.h>
 #include <glib-object.h>
 
-#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 */

--- 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

--- 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 <gst/farsight/fs-session.h>
 #include <glib.h>
 #include <glib-object.h>
 
@@ -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 */

--- 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" {