Mercurial > pidgin3 / changeset

--- a/libpurple/smiley-remote.c	Sat Apr 05 17:51:34 2014 +0200
+++ b/libpurple/smiley-remote.c	Sat Apr 05 18:14:27 2014 +0200
@@ -33,13 +33,13 @@
 	GString *contents;
 	PurpleStoredImage *image; /* it's not the same as in parent */
 
-	gboolean failed;
+	gboolean has_failed;
 } PurpleRemoteSmileyPrivate;
 
 enum
 {
 	PROP_0,
-	PROP_FAILED,
+	PROP_HAS_FAILED,
 	PROP_LAST
 };
 
@@ -66,7 +66,7 @@
 		PURPLE_REMOTE_SMILEY_GET_PRIVATE(smiley);
 
 	g_return_if_fail(priv != NULL);
-	g_return_if_fail(!priv->failed);
+	g_return_if_fail(!priv->has_failed);
 	g_return_if_fail(!purple_smiley_is_ready(PURPLE_SMILEY(smiley)));
 	g_return_if_fail(data != NULL || size == 0);
 
@@ -83,7 +83,7 @@
 		PURPLE_REMOTE_SMILEY_GET_PRIVATE(smiley);
 
 	g_return_if_fail(priv != NULL);
-	g_return_if_fail(!priv->failed);
+	g_return_if_fail(!priv->has_failed);
 	g_return_if_fail(!purple_smiley_is_ready(PURPLE_SMILEY(smiley)));
 	g_return_if_fail(priv->contents != NULL);
 	g_return_if_fail(priv->image == NULL);
@@ -113,11 +113,11 @@
 	g_return_if_fail(priv != NULL);
 	g_return_if_fail(!purple_smiley_is_ready(PURPLE_SMILEY(smiley)));
 
-	if (priv->failed)
+	if (priv->has_failed)
 		return;
 
-	priv->failed = TRUE;
-	g_object_notify_by_pspec(G_OBJECT(smiley), properties[PROP_FAILED]);
+	priv->has_failed = TRUE;
+	g_object_notify_by_pspec(G_OBJECT(smiley), properties[PROP_HAS_FAILED]);
 	g_signal_emit(smiley, signals[SIG_FAILED], 0);
 }
 
@@ -153,7 +153,7 @@
 		PURPLE_REMOTE_SMILEY_GET_PRIVATE(smiley);
 
 	priv->contents = g_string_new(NULL);
-	priv->failed = FALSE;
+	priv->has_failed = FALSE;
 }
 
 static void
@@ -179,8 +179,8 @@
 	PurpleRemoteSmileyPrivate *priv = PURPLE_REMOTE_SMILEY_GET_PRIVATE(remote_smiley);
 
 	switch (par_id) {
-		case PROP_FAILED:
-			g_value_set_boolean(value, priv->failed);
+		case PROP_HAS_FAILED:
+			g_value_set_boolean(value, priv->has_failed);
 			break;
 		default:
 			G_OBJECT_WARN_INVALID_PROPERTY_ID(object, par_id, pspec);
@@ -204,12 +204,19 @@
 
 	gobj_class->get_property = purple_remote_smiley_get_property;
 
-	properties[PROP_FAILED] = g_param_spec_boolean("failed", "Failed",
-		"The remote host has failed to send the smiley", FALSE,
-		G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+	properties[PROP_HAS_FAILED] = g_param_spec_boolean("has-failed",
+		"Has hailed", "The remote host has failed to send the smiley",
+		FALSE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
 
 	g_object_class_install_properties(gobj_class, PROP_LAST, properties);
 
+	/**
+	 * PurpleRemoteSmiley::failed:
+	 * @smiley: a smiley that failed to transfer.
+	 *
+	 * Called when a @smiley fails to be transferred. It's guaranteed to be
+	 * fired at most once for a particular @smiley.
+	 */
 	signals[SIG_FAILED] = g_signal_new("failed", G_OBJECT_CLASS_TYPE(klass),
 		0, 0, NULL, NULL,
 		g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);

--- a/libpurple/smiley-remote.h	Sat Apr 05 17:51:34 2014 +0200
+++ b/libpurple/smiley-remote.h	Sat Apr 05 18:14:27 2014 +0200
@@ -27,6 +27,15 @@
  * @section_id: libpurple-smiley-remote
  * @short_description: smileys sent by a remote client
  * @title: Remote smileys
+ *
+ * A #PurpleRemoteSmiley is quite handy, if you have received the message with
+ * custom remote smileys, but haven't received smileys yet. Obviously, it also
+ * fits for protocols, where a smiley image contents is sent with the message
+ * and is accessible without a delay - it does not require storing any temporary
+ * files to the disk.
+ *
+ * It handles received image data by storing it in its internal buffer and
+ * creates image object when needed.
  */
 
 #include <glib-object.h>
@@ -48,6 +57,9 @@
  * PurpleRemoteSmiley:
  *
  * A smiley that was sent by remote client, most probably your buddy.
+ *
+ * It shouldn't be created directly. Instead, use
+ * #purple_conversation_add_remote_smiley.
  */
 struct _PurpleRemoteSmiley
 {
@@ -55,6 +67,11 @@
 	PurpleSmiley parent;
 };
 
+/**
+ * PurpleRemoteSmileyClass:
+ *
+ * Base class for #PurpleRemoteSmiley objects.
+ */
 struct _PurpleRemoteSmileyClass
 {
 	/*< private >*/
@@ -71,22 +88,42 @@
 /**
  * purple_remote_smiley_get_type:
  *
- * Returns: The #GType for a remote smiley.
+ * Returns: the #GType for a remote smiley.
  */
 GType
 purple_remote_smiley_get_type(void);
 
-/******************************************************************************
- * Remote smiley API
- ******************************************************************************/
-
+/**
+ * purple_remote_smiley_write:
+ * @smiley: the remote smiley.
+ * @data: the buffer with image data chunk.
+ * @size: the size of image contents stored in @data.
+ *
+ * Writes next chunk of image data to the receive buffer.
+ */
 void
 purple_remote_smiley_write(PurpleRemoteSmiley *smiley, const guchar *data,
 	gsize size);
 
+/**
+ * purple_remote_smiley_close:
+ * @smiley: the remote smiley.
+ *
+ * Called when all image data was already written using
+ * #purple_remote_smiley_write and image is ready to be processed.
+ */
 void
 purple_remote_smiley_close(PurpleRemoteSmiley *smiley);
 
+/**
+ * purple_remote_smiley_failed:
+ * @smiley: the remote smiley.
+ *
+ * Called when the transfer of image data has failed. This invalidates @smiley
+ * object, which cannot be used anymore. It's removed from the #PurpleSmileyList
+ * containing it (depending on its configuration), so the smiley can be
+ * retrieved again.
+ */
 void
 purple_remote_smiley_failed(PurpleRemoteSmiley *smiley);