diff libpurple/protocols/jabber/jutil.h @ 29402:db0762fbb60b

jabber: Document jabber_find_unnormalized_im_conv (and my guess as to why it exists instead of using purple_find_conversation_with_account).

--- a/libpurple/protocols/jabber/jutil.h	Wed Feb 10 04:35:10 2010 +0000
+++ b/libpurple/protocols/jabber/jutil.h	Wed Feb 10 05:06:36 2010 +0000
@@ -63,7 +63,17 @@
  */
 char *jabber_saslprep(const char *);
 
-PurpleConversation *jabber_find_unnormalized_conv(const char *name, PurpleAccount *account);
+/**
+ * Search for an IM conversation with this specific user (including resource).
+ * This is an alternative to purple_find_conversation_with_account(), which
+ * calls purple_normalize (so if a conversation was found, we'd need to compare
+ * the conversation name to see if the resources match).
+ *
+ * This function saves a call to purple_normalize(), at the expense of
+ * iterating over every open IM conversation.  For most usages, I think
+ * this tradeoff is OK.
+ */
+PurpleConversation *jabber_find_unnormalized_im_conv(const char *name, PurpleAccount *account);
 
 char *jabber_calculate_data_sha1sum(gconstpointer data, size_t len);
 #endif /* PURPLE_JABBER_JUTIL_H_ */