pidgin.next.minor: d0024130: Add documentation to backend-iface.h.

[maiku at pidgin.im]

-----------------------------------------------------------------
Revision: d00241305ccc36eef5bd6723980b66a2e6108856
Ancestor: 7b70aeacc1d10bfd4bbf20f3c3d7055a33f56bf2
Author: maiku at pidgin.im
Date: 2009-11-13T21:46:43
Branch: im.pidgin.pidgin.next.minor
URL: http://d.pidgin.im/viewmtn/revision/info/d00241305ccc36eef5bd6723980b66a2e6108856

Modified files:
        libpurple/media/backend-iface.h

ChangeLog: 

Add documentation to backend-iface.h.

-------------- next part --------------
============================================================
--- libpurple/media/backend-iface.h	40282e5a3b058a1f73d3aefb228d9420d45516f4
+++ libpurple/media/backend-iface.h	cbdc4f80002c2879686777d5744305320b85d1b6
@@ -39,13 +39,16 @@ G_BEGIN_DECLS
 #define PURPLE_MEDIA_BACKEND(obj)		(G_TYPE_CHECK_INSTANCE_CAST((obj), PURPLE_TYPE_MEDIA_BACKEND, PurpleMediaBackend))
 #define PURPLE_MEDIA_BACKEND_GET_INTERFACE(inst)(G_TYPE_INSTANCE_GET_INTERFACE((inst), PURPLE_TYPE_MEDIA_BACKEND, PurpleMediaBackendIface))
 
+/** A placeholder to represent any media backend */
 typedef struct _PurpleMediaBackend PurpleMediaBackend;
+/** A structure to derive media backends from. */
 typedef struct _PurpleMediaBackendIface PurpleMediaBackendIface;
 
 struct _PurpleMediaBackendIface
 {
-	GTypeInterface parent_iface;
+	GTypeInterface parent_iface; /**< The parent iface class */ 
 
+	/** Implementable functions called with purple_media_backend_* */
 	gboolean (*add_stream) (PurpleMediaBackend *self,
 		const gchar *sess_id, const gchar *who,
 		PurpleMediaSessionType type, gboolean initiator,
@@ -67,25 +70,124 @@ struct _PurpleMediaBackendIface
 		const gchar *sess_id, PurpleMediaCodec *codec);
 };
 
+/**
+ * Gets the media backend's GType.
+ *
+ * @return The media backend's GType.
+ *
+ * @since 2.7.0
+ */
 GType purple_media_backend_get_type(void);
 
+/**
+ * Creates and adds a stream to the media backend.
+ *
+ * @param self The backend to add the stream to.
+ * @param sess_id The session id of the stream to add.
+ * @param who The remote participant of the stream to add.
+ * @param type The media type and direction of the stream to add.
+ * @param initiator True if the local user initiated the stream.
+ * @param transmitter The string id of the tranmsitter to use.
+ * @param num_params The number of parameters in the param parameter.
+ * @param params The additional parameters to pass when creating the stream.
+ *
+ * @return True if the stream was successfully created, othewise False.
+ *
+ * @since 2.7.0
+ */
 gboolean purple_media_backend_add_stream(PurpleMediaBackend *self,
 		const gchar *sess_id, const gchar *who,
 		PurpleMediaSessionType type, gboolean initiator,
 		const gchar *transmitter,
 		guint num_params, GParameter *params);
+
+/**
+ * Add remote candidates to a stream.
+ *
+ * @param self The backend the stream is in.
+ * @param sess_id The session id associated with the stream.
+ * @param participant The participant associated with the stream.
+ * @param remote_candidates The list of remote candidates to add.
+ *
+ * @since 2.7.0
+ */
 void purple_media_backend_add_remote_candidates(PurpleMediaBackend *self,
 		const gchar *sess_id, const gchar *participant,
 		GList *remote_candidates);
+
+/**
+ * Get whether or not a session's codecs are ready.
+ *
+ * A codec is ready if all of the attributes and additional
+ * parameters have been collected.
+ *
+ * @param self The media backend the session is in.
+ * @param sess_id The session id of the session to check.
+ *
+ * @return True if the codecs are ready, otherwise False.
+ *
+ * @since 2.7.0
+ */
 gboolean purple_media_backend_codecs_ready(PurpleMediaBackend *self,
 		const gchar *sess_id);
+
+/**
+ * Gets the codec intersection list for a session.
+ *
+ * The intersection list consists of all codecs that are compatible
+ * between the local and remote software.
+ *
+ * @param self The media backend the session is in.
+ * @param sess_id The session id of the session to use.
+ *
+ * @return The codec intersection list.
+ *
+ * @since 2.7.0
+ */
 GList *purple_media_backend_get_codecs(PurpleMediaBackend *self,
 		const gchar *sess_id);
+
+/**
+ * Gets the list of local candidates for a stream.
+ *
+ * @param self The media backend the stream is in.
+ * @param sess_id The session id associated with the stream.
+ * @param particilant The participant associated with the stream.
+ *
+ * @return The list of local candidates.
+ *
+ * @since 2.7.0
+ */
 GList *purple_media_backend_get_local_candidates(PurpleMediaBackend *self,
 		const gchar *sess_id, const gchar *participant);
+
+/**
+ * Sets the remote codecs on a stream.
+ *
+ * @param self The media backend the stream is in.
+ * @param sess_id The session id the stream is associated with.
+ * @param participant The participant the stream is associated with.
+ * @param codecs The list of remote codecs to set.
+ *
+ * @return True if the remote codecs were set successfully, otherwise False.
+ *
+ * @since 2.7.0
+ */
 gboolean purple_media_backend_set_remote_codecs(PurpleMediaBackend *self,
 		const gchar *sess_id, const gchar *participant,
 		GList *codecs);
+
+/**
+ * Sets which codec format to send media content in for a session.
+ *
+ * @param self The media backend the session is in.
+ * @param sess_id The session id of the session to set the codec for.
+ * @param codec The codec to set.
+ *
+ * @return True if set successfully, otherwise False.
+ *
+ * @since 2.7.0
+ */
 gboolean purple_media_backend_set_send_codec(PurpleMediaBackend *self,
 		const gchar *sess_id, PurpleMediaCodec *codec);