soc.2008.vv: 59d05cb3: * Added documentation to media.h and med...
maiku at soc.pidgin.im
maiku at soc.pidgin.im
Fri Aug 8 23:55:52 EDT 2008
-----------------------------------------------------------------
Revision: 59d05cb38af9346d82ce57477273f7b381054bcc
Ancestor: 9e001630f434a5f95e5abc65a8c41359648a8eb1
Author: maiku at soc.pidgin.im
Date: 2008-08-09T01:50:06
Branch: im.pidgin.soc.2008.vv
URL: http://d.pidgin.im/viewmtn/revision/info/59d05cb38af9346d82ce57477273f7b381054bcc
Modified files:
Doxyfile.in libpurple/media.c libpurple/media.h
libpurple/mediamanager.c libpurple/mediamanager.h
libpurple/server.h
ChangeLog:
* Added documentation to media.h and mediamanager.h
* Removed unnecessary includes from a few files
* Fixed a few parameter names
-------------- next part --------------
============================================================
--- Doxyfile.in 8477c5c4ca55496d672aa6e414e975e32eabef1d
+++ Doxyfile.in b42968d9a4b3e488ebc6728a94f79b56ce6d9673
@@ -1070,7 +1070,7 @@ INCLUDE_FILE_PATTERNS =
# 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.
============================================================
--- libpurple/media.c 490b36364eb9b0e52b9056691549ea4bc04650ad
+++ libpurple/media.c b1365d0cb3f622e103e5455d826da0d428d15001
@@ -1,9 +1,10 @@
/**
* @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
* source distribution.
@@ -748,7 +749,7 @@ purple_media_get_element(const gchar *fa
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;
}
============================================================
--- libpurple/media.h eb868a606143bb349a7775b47a2f6db420dd1412
+++ libpurple/media.h 7989b32dd5e9576a97a63fddb0ebe4d7d468bcf2
@@ -1,9 +1,10 @@
/**
* @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
* source distribution.
@@ -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 @@ G_BEGIN_DECLS
#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 @@ typedef void PurpleMedia;
#endif /* USE_VV */
+/** Media session types */
typedef enum {
PURPLE_MEDIA_NONE = 0,
PURPLE_MEDIA_RECV_AUDIO = 1 << 0,
@@ -68,89 +71,449 @@ typedef enum {
#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 */
============================================================
--- libpurple/mediamanager.c 7332f1cde467612d789cd7d3a52843469acc83cc
+++ libpurple/mediamanager.c c4814e6a4688301661ec232593243f5d728d1b9b
@@ -1,9 +1,10 @@
/**
* @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
* source distribution.
============================================================
--- libpurple/mediamanager.h 67c5a26d0fe058b95cc6ebdc401c96a21ed535ff
+++ libpurple/mediamanager.h 6911d477a0ee908851f7d1bfa595a0fbe399bf70
@@ -1,9 +1,10 @@
/**
* @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
* source distribution.
@@ -28,7 +29,6 @@
#ifdef USE_VV
-#include <gst/farsight/fs-session.h>
#include <glib.h>
#include <glib-object.h>
@@ -44,28 +44,70 @@ G_BEGIN_DECLS
#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;
- PurpleMediaManagerPrivate *priv;
+ GObject parent; /**< The parent of this manager. */
+ PurpleMediaManagerPrivate *priv; /**< Private data for the manager. */
};
+#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);
+
+/**
+ * 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 */
============================================================
--- libpurple/server.h 82dd7009428122bf12d500af11edd0a276755da4
+++ libpurple/server.h 2d4f6944539b1304ae6435e480f1a460ca986f25
@@ -29,7 +29,6 @@
#include "account.h"
#include "conversation.h"
#include "prpl.h"
-#include "media.h"
#ifdef __cplusplus
extern "C" {
More information about the Commits
mailing list