/pidgin/main: ea1c4f205efb: PurpleImage: fill comments
Tomasz Wasilczyk
twasilczyk at pidgin.im
Mon Apr 14 16:03:21 EDT 2014
Changeset: ea1c4f205efb3e5d57ce6b1e55e9ef69d6d41063
Author: Tomasz Wasilczyk <twasilczyk at pidgin.im>
Date: 2014-04-14 22:03 +0200
Branch: default
URL: https://hg.pidgin.im/pidgin/main/rev/ea1c4f205efb
Description:
PurpleImage: fill comments
diffstat:
doc/reference/libpurple/libpurple-docs.xml | 11 +-
libpurple/conversation.h | 6 +-
libpurple/image-store.h | 106 ++++++++++++++++-
libpurple/image.h | 175 ++++++++++++++++++++++++++++-
libpurple/smiley.h | 9 +-
5 files changed, 294 insertions(+), 13 deletions(-)
diffs (truncated from 469 to 300 lines):
diff --git a/doc/reference/libpurple/libpurple-docs.xml b/doc/reference/libpurple/libpurple-docs.xml
--- a/doc/reference/libpurple/libpurple-docs.xml
+++ b/doc/reference/libpurple/libpurple-docs.xml
@@ -88,7 +88,6 @@
<xi:include href="xml/sound-theme.xml" />
<xi:include href="xml/sound-theme-loader.xml" />
<xi:include href="xml/upnp.xml" />
- <xi:include href="xml/whiteboard.xml" />
<xi:include href="xml/xmlnode.xml" />
<xi:include href="xml/version.xml" />
<xi:include href="xml/util.xml" />
@@ -123,6 +122,14 @@
</reference>
<reference label="c">
+ <title>Graphics</title>
+
+ <xi:include href="xml/image.xml" />
+ <xi:include href="xml/image-store.xml" />
+ <xi:include href="xml/whiteboard.xml" />
+ </reference>
+
+ <reference label="d">
<title>Media APIs</title>
<xi:include href="xml/media.xml" />
@@ -134,7 +141,7 @@
<xi:include href="xml/enum-types.xml" />
</reference>
- <reference label="d">
+ <reference label="e">
<title>D-Bus Server APIs</title>
<xi:include href="xml/dbus-bindings.xml" />
diff --git a/libpurple/conversation.h b/libpurple/conversation.h
--- a/libpurple/conversation.h
+++ b/libpurple/conversation.h
@@ -680,7 +680,11 @@ purple_conversation_get_max_message_size
* @shortcut: The shortcut for the new smiley.
*
* Adds new smiley to the list of remote smileys for this conversation.
- * The smiley have to be written and closed, when data is ready.
+ * The smiley image have to be written and closed, when data is ready.
+ *
+ * You can retrieve smiley's #PurpleImage object using #purple_smiley_get_image
+ * and set its data with #purple_image_transfer_write
+ * and #purple_image_transfer_close.
*
* Returns: (transfer none): New smiley, or %NULL if it's already being
* retrieved (or possibly, in case of error).
diff --git a/libpurple/image-store.h b/libpurple/image-store.h
--- a/libpurple/image-store.h
+++ b/libpurple/image-store.h
@@ -25,43 +25,139 @@
* SECTION:image-store
* @include:image-store.h
* @section_id: libpurple-image-store
- * @short_description: todo
+ * @short_description: a global, temporary storage for images
* @title: Image store
*
- * TODO desc.
+ * Image store references #PurpleImage's by a simple integer value.
+ * It's a convenient way to embed images in HTML-like strings.
+ *
+ * Integer ID's are tracked for being valid - when a image is destroyed, it's
+ * also removed from the store. If the application runs for a very long time and
+ * all possible id numbers from integer range are utilized, it will use
+ * previously released numbers.
*/
#include "image.h"
+/**
+ * PURPLE_IMAGE_STORE_PROTOCOL:
+ *
+ * A global URI prefix for images stored in this subsystem.
+ */
#define PURPLE_IMAGE_STORE_PROTOCOL "purple-image:"
+
+/**
+ * PURPLE_IMAGE_STORE_STOCK_PROTOCOL:
+ *
+ * A global URI prefix for stock images, with names defined by libpurple and
+ * contents defined by the UI.
+ */
#define PURPLE_IMAGE_STORE_STOCK_PROTOCOL "purple-stock-image:"
G_BEGIN_DECLS
-/* increases and maintains reference count */
+/**
+ * purple_image_store_add:
+ * @image: the image.
+ *
+ * Permanently adds an image to the store. If the @image is already in the
+ * store, it will return its current id.
+ *
+ * This function increases @image's reference count, so it won't be destroyed
+ * until image store subsystem is shut down. Don't decrease @image's reference
+ * count by yourself - if you don't want the store to hold the reference,
+ * use #purple_image_store_add_weak.
+ *
+ * Returns: the unique identifier for the @image.
+ */
guint
purple_image_store_add(PurpleImage *image);
-/* doesn't change reference count and is removed from the store when obj is destroyed */
+/**
+ * purple_image_store_add_weak:
+ * @image: the image.
+ *
+ * Adds an image to the store without increasing reference count. It will be
+ * removed from the store when @image gets destroyed.
+ *
+ * If the @image is already in the store, it will return its current id.
+ *
+ * Returns: the unique identifier for the @image.
+ */
guint
purple_image_store_add_weak(PurpleImage *image);
-/* increases reference count for five seconds */
+/**
+ * purple_image_store_add_temporary:
+ * @image: the image.
+ *
+ * Adds an image to the store to be used in a short period of time.
+ * If the @image is already in the store, it will just return its current id.
+ *
+ * Increases reference count for the @image for a time long enough to display
+ * the @image by the UI. In current implementation it's five seconds, but may be
+ * changed in the future, so if you need more sophisticated reference
+ * management, implement it on your own.
+ *
+ * Returns: the unique identifier for the @image.
+ */
guint
purple_image_store_add_temporary(PurpleImage *image);
+/**
+ * purple_image_store_get:
+ * @id: the unique identifier of an image.
+ *
+ * Finds the image with a certain identifier within a store.
+ *
+ * Returns: (transfer none): the image referenced by @id, or %NULL if it
+ * doesn't exists.
+ */
PurpleImage *
purple_image_store_get(guint id);
+/**
+ * purple_image_store_get_from_uri:
+ * @uri: the URI of a potential #PurpleImage. Should not be %NULL.
+ *
+ * Checks, if the @uri is pointing to any #PurpleImage by referring
+ * to #PURPLE_IMAGE_STORE_PROTOCOL and returns the image, if it's valid.
+ *
+ * The function doesn't throw any warning, if the @uri is for any
+ * other protocol.
+ *
+ * Returns: (transfer none): the image referenced by @uri, or %NULL if it
+ * doesn't point to any valid image.
+ */
PurpleImage *
purple_image_store_get_from_uri(const gchar *uri);
+/**
+ * purple_image_store_get_uri:
+ * @image: the image.
+ *
+ * Generates an URI for the @image, to be retrieved using
+ * #purple_image_store_get_from_uri.
+ *
+ * Returns: (transfer full): the URI for the @image. Should be #g_free'd when
+ * you done using it.
+ */
gchar *
purple_image_store_get_uri(PurpleImage *image);
+/**
+ * _purple_image_store_init: (skip)
+ *
+ * Initializes the image store subsystem.
+ */
void
_purple_image_store_init(void);
+/**
+ * _purple_image_store_uninit: (skip)
+ *
+ * Uninitializes the image store subsystem.
+ */
void
_purple_image_store_uninit(void);
diff --git a/libpurple/image.h b/libpurple/image.h
--- a/libpurple/image.h
+++ b/libpurple/image.h
@@ -25,10 +25,16 @@
* SECTION:image
* @include:image.h
* @section_id: libpurple-image
- * @short_description: implementation-independent image container.
+ * @short_description: implementation-independent image data container
* @title: Images
*
- * TODO desc.
+ * #PurpleImage object is a container for raw image data. It doesn't manipulate
+ * image data, just stores it in its binary format - png, jpeg etc. Thus, it's
+ * totally independent from the UI.
+ *
+ * This class also provides certain file-related features, like: friendly
+ * filenames (not necessarily real filename for displaying); remote images
+ * (which data is not yet loaded) or guessing file format from its header.
*/
#include <glib-object.h>
@@ -46,7 +52,7 @@ typedef struct _PurpleImageClass PurpleI
/**
* PurpleImage:
*
- * TODO desc
+ * An image data container.
*/
struct _PurpleImage
{
@@ -80,55 +86,218 @@ G_BEGIN_DECLS
GType
purple_image_get_type(void);
+/**
+ * purple_image_new_from_file:
+ * @path: the path to the image file.
+ * @be_eager: %TRUE, if file should be loaded now, %FALSE when needed.
+ *
+ * Loads an image file as a new #PurpleImage object. The @path must exists, be
+ * readable and should point to a valid image file. If you don't set @be_eager
+ * parameter, there will be a risk that file will be removed from disk before
+ * you access its data.
+ *
+ * Returns: the new #PurpleImage.
+ */
PurpleImage *
purple_image_new_from_file(const gchar *path, gboolean be_eager);
+/**
+ * purple_image_new_from_data:
+ * @data: the pointer to the image data buffer.
+ * @length: the length of @data.
+ *
+ * Creates a new #PurpleImage object with contents of @data buffer.
+ *
+ * The @data buffer is owned by #PurpleImage object, so you might want
+ * to #g_memdup it first.
+ *
+ * Returns: the new #PurpleImage.
+ */
PurpleImage *
purple_image_new_from_data(gpointer data, gsize length);
+/**
+ * purple_image_save:
+ * @image: the image.
+ * @path: destination of a saved image file.
+ *
+ * Saves an @image to the disk.
+ *
+ * Returns: %TRUE if succeeded, %FALSE otherwise.
+ */
gboolean
purple_image_save(PurpleImage *image, const gchar *path);
+/**
+ * purple_image_get_path:
+ * @image: the image.
+ *
+ * Returns the physical path of the @image file. It is set only, if the @image is
+ * really backed by an existing file. In the other case it returns %NULL.
+ *
+ * Returns: the physical path of the @image, or %NULL.
+ */
const gchar *
purple_image_get_path(PurpleImage *image);
+/**
+ * purple_image_is_ready:
+ * @image: the image.
+ *
+ * Checks, if the @image data is ready to be displayed. Remote image data may
+ * not be accessible at the moment, so you should check it before using
+ * #purple_image_get_data. If the image is not ready yet, you may wait for
+ * #PurpleImage::ready signal.
+ *
+ * Returns: %TRUE, if the @image is ready.
+ */
gboolean
More information about the Commits
mailing list