changeset 23868:1aa383ee5fc8

Fixed up media functions in prpl.c and prpl.h, adding more documentation and using PURPLE_PROTOCOL_PLUGIN_HAS_FUNC.

--- a/libpurple/prpl.c	Sat Aug 09 02:24:38 2008 +0000
+++ b/libpurple/prpl.c	Sat Aug 09 03:11:46 2008 +0000
@@ -494,30 +494,6 @@
 	got_attention(gc, id, who, type_code);
 }
 
-/**************************************************************************
- * Protocol Plugin Subsystem API
- **************************************************************************/
-
-PurplePlugin *
-purple_find_prpl(const char *id)
-{
-	GList *l;
-	PurplePlugin *plugin;
-
-	g_return_val_if_fail(id != NULL, NULL);
-
-	for (l = purple_plugins_get_protocols(); l != NULL; l = l->next) {
-		plugin = (PurplePlugin *)l->data;
-
-		if (!strcmp(plugin->info->id, id))
-			return plugin;
-	}
-
-	return NULL;
-}
-
-
-
 PurpleMedia *
 purple_prpl_initiate_media(PurpleAccount *account,
 			   const char *who,
@@ -535,7 +511,7 @@
 	if (prpl)
 		prpl_info = PURPLE_PLUGIN_PROTOCOL_INFO(prpl);
 
-	if (prpl_info && prpl_info->initiate_media) {
+	if (prpl_info && PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl_info, initiate_media)) {
 		/* should check that the protocol supports this media type here? */
 		return prpl_info->initiate_media(gc, who, type);
 	} else {
@@ -563,7 +539,7 @@
 	if (prpl)
 		prpl_info = PURPLE_PLUGIN_PROTOCOL_INFO(prpl);
 	
-	if (prpl_info && prpl_info->can_do_media) {
+	if (prpl_info && PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl_info, can_do_media)) {
 		return prpl_info->can_do_media(gc, who, type);
 	} else {
 		return FALSE;
@@ -573,3 +549,25 @@
 #endif
 }
 
+/**************************************************************************
+ * Protocol Plugin Subsystem API
+ **************************************************************************/
+
+PurplePlugin *
+purple_find_prpl(const char *id)
+{
+	GList *l;
+	PurplePlugin *plugin;
+
+	g_return_val_if_fail(id != NULL, NULL);
+
+	for (l = purple_plugins_get_protocols(); l != NULL; l = l->next) {
+		plugin = (PurplePlugin *)l->data;
+
+		if (!strcmp(plugin->info->id, id))
+			return plugin;
+	}
+
+	return NULL;
+}
+

--- a/libpurple/prpl.h	Sat Aug 09 02:24:38 2008 +0000
+++ b/libpurple/prpl.h	Sat Aug 09 03:11:46 2008 +0000
@@ -441,10 +441,27 @@
 	 */
 	GHashTable *(*get_account_text_table)(PurpleAccount *account);
 
-	/** Initiate media with the given buddy */
-	PurpleMedia  *(*initiate_media)(PurpleConnection *conn, const char *who, PurpleMediaStreamType type);
+	/**
+	 * Initiate a media session with the given contact.
+	 *
+	 * @param conn The connection to initiate the media session on.
+	 * @param who The remote user to initiate the session with.
+	 * @param type The type of media session to initiate.
+	 * @return The newly created media object.
+	 */
+	PurpleMedia  *(*initiate_media)(PurpleConnection *gc, const char *who,
+					PurpleMediaStreamType type);
 
-	gboolean (*can_do_media)(PurpleConnection *conn, const char *who, PurpleMediaStreamType type);
+	/**
+	 * Checks to see if the given contact supports the given type of media session.
+	 *
+	 * @param conn The connection the contact is on.
+	 * @param who The remote user to check for media capability with.
+	 * @param type The type of media session to check for.
+	 * @return @c TRUE The contact supports the given media type, or @c FALSE otherwise.
+	 */
+	gboolean (*can_do_media)(PurpleConnection *gc, const char *who,
+				 PurpleMediaStreamType type);
 };
 
 #define PURPLE_PROTOCOL_PLUGIN_HAS_FUNC(prpl, member) \