/pidgin/main: 128a065f1a27: Comments: PurpleRemoteSmiley
Tomasz Wasilczyk
twasilczyk at pidgin.im
Sat Apr 5 12:14:37 EDT 2014
Changeset: 128a065f1a27d6a4496c490772f4501324c93978
Author: Tomasz Wasilczyk <twasilczyk at pidgin.im>
Date: 2014-04-05 18:14 +0200
Branch: default
URL: https://hg.pidgin.im/pidgin/main/rev/128a065f1a27
Description:
Comments: PurpleRemoteSmiley
diffstat:
libpurple/smiley-remote.c | 33 ++++++++++++++++++++-------------
libpurple/smiley-remote.h | 47 ++++++++++++++++++++++++++++++++++++++++++-----
2 files changed, 62 insertions(+), 18 deletions(-)
diffs (184 lines):
diff --git a/libpurple/smiley-remote.c b/libpurple/smiley-remote.c
--- a/libpurple/smiley-remote.c
+++ b/libpurple/smiley-remote.c
@@ -33,13 +33,13 @@ typedef struct {
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_write(PurpleRemoteS
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_close(PurpleRemoteS
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 @@ purple_remote_smiley_failed(PurpleRemote
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_init(GTypeInstance
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 @@ purple_remote_smiley_get_property(GObjec
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 @@ purple_remote_smiley_class_init(PurpleRe
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);
diff --git a/libpurple/smiley-remote.h b/libpurple/smiley-remote.h
--- a/libpurple/smiley-remote.h
+++ b/libpurple/smiley-remote.h
@@ -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 @@ typedef struct _PurpleRemoteSmileyClass
* 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 @@ struct _PurpleRemoteSmiley
PurpleSmiley parent;
};
+/**
+ * PurpleRemoteSmileyClass:
+ *
+ * Base class for #PurpleRemoteSmiley objects.
+ */
struct _PurpleRemoteSmileyClass
{
/*< private >*/
@@ -71,22 +88,42 @@ G_BEGIN_DECLS
/**
* 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);
More information about the Commits
mailing list