/pidgin/main: f84e542b30ea: Merge from 2.x.y again.

[Mark Doliner]

Changeset: f84e542b30ea3a761937ec58bc6ac86b4e882dea
Author:	 Mark Doliner <mark at kingant.net>
Date:	 2013-01-21 23:24 -0800
Branch:	 default
URL: http://hg.pidgin.im/pidgin/main/rev/f84e542b30ea

Description:

Merge from 2.x.y again.

diffstat:

 libpurple/imgstore.h |  80 +++++++++++++++++++++++++++++++--------------------
 1 files changed, 49 insertions(+), 31 deletions(-)

diffs (173 lines):

diff --git a/libpurple/imgstore.h b/libpurple/imgstore.h
--- a/libpurple/imgstore.h
+++ b/libpurple/imgstore.h
@@ -1,5 +1,6 @@
 /**
- * @file imgstore.h IM Image Store API
+ * @file imgstore.h Utility functions for reference-counted in-memory
+ *       image data.
  * @ingroup core
  * @see @ref imgstore-signals
  */
@@ -39,58 +40,75 @@ typedef struct _PurpleStoredImage Purple
 G_BEGIN_DECLS
 
 /**
- * Add an image to the store.
+ * Create a new PurpleStoredImage.
  *
- * The caller owns a reference to the image in the store, and must dereference
- * the image with purple_imgstore_unref() for it to be freed.
+ * Despite the name of this function, the image is NOT added to the image
+ * store and no ID is assigned.  If you need to reference the image by an
+ * ID, use purple_imgstore_add_with_id() instead.
  *
- * No ID is allocated when using this function.  If you need to reference the
- * image by an ID, use purple_imgstore_add_with_id() instead.
+ * The caller owns a reference to this image and must dereference it with
+ * purple_imgstore_unref() for it to be freed.
  *
- * @param data		Pointer to the image data, which the imgstore will take
- *                      ownership of and free as appropriate.  If you want a
- *                      copy of the data, make it before calling this function.
- * @param size		Image data's size.
- * @param filename	Filename associated with image.  This is for your
+ * @param data      Pointer to the image data, which the imgstore will take
+ *                  ownership of and free as appropriate.  If you want a
+ *                  copy of the data, make it before calling this function.
+ * @param size      Image data's size.
+ * @param filename  Filename associated with image.  This is for your
  *                  convenience.  It could be the full path to the
  *                  image or, more commonly, the filename of the image
  *                  without any directory information.  It can also be
  *                  NULL, if you don't need to keep track of a filename.
  *
- * @return The stored image.
+ * @return The stored image, or NULL if the image was not added (because of
+ *         empty data or size).
  */
 PurpleStoredImage *
 purple_imgstore_add(gpointer data, size_t size, const char *filename);
 
 /**
- * Create an image and add it to the store.
+ * Create a PurpleStoredImage using purple_imgstore_add() by reading the
+ * given filename from disk.
+ *
+ * The image is not added to the image store and no ID is assigned.  If you
+ * need to reference the image by an ID, use purple_imgstore_add_with_id()
+ * instead.
+ *
+ * Make sure the filename is appropriately escaped.  You may wish to use
+ * purple_escape_filename().  The PurpleStoredImage's filename will be set
+ * to the given path.
+ *
+ * The caller owns a reference to this image and must dereference it with
+ * purple_imgstore_unref() for it to be freed.
  *
  * @param path  The path to the image.
  *
- * @return  The stored image.
+ * @return The stored image, or NULL if the image was not added (because of
+ *         empty data or size).
  */
 PurpleStoredImage *
 purple_imgstore_new_from_file(const char *path);
 
 /**
- * Add an image to the store, allocating an ID.
+ * Create a PurpleStoredImage using purple_imgstore_add() and add the
+ * image to the image store.  A unique ID will be assigned to the image.
  *
- * The caller owns a reference to the image in the store, and must dereference
- * the image with purple_imgstore_unref_by_id() or purple_imgstore_unref()
- * for it to be freed.
+ * The caller owns a reference to the image and must dereference it with
+ * purple_imgstore_unref() or purple_imgstore_unref_by_id() for it to be
+ * freed.
  *
- * @param data		Pointer to the image data, which the imgstore will take
- *                      ownership of and free as appropriate.  If you want a
- *                      copy of the data, make it before calling this function.
- * @param size		Image data's size.
- * @param filename	Filename associated with image.  This is for your
+ * @param data      Pointer to the image data, which the imgstore will take
+ *                  ownership of and free as appropriate.  If you want a
+ *                  copy of the data, make it before calling this function.
+ * @param size      Image data's size.
+ * @param filename  Filename associated with image.  This is for your
  *                  convenience.  It could be the full path to the
  *                  image or, more commonly, the filename of the image
  *                  without any directory information.  It can also be
  *                  NULL, if you don't need to keep track of a filename.
 
  * @return ID for the image.  This is a unique number that can be used
- *         within libpurple to reference the image.
+ *         within libpurple to reference the image.  0 is returned if the
+ *         image was not added (because of empty data or size).
  */
 int purple_imgstore_add_with_id(gpointer data, size_t size, const char *filename);
 
@@ -98,7 +116,7 @@ int purple_imgstore_add_with_id(gpointer
  * Retrieve an image from the store. The caller does not own a
  * reference to the image.
  *
- * @param id		The ID for the image.
+ * @param id The ID for the image.
  *
  * @return A pointer to the requested image, or NULL if it was not found.
  */
@@ -107,7 +125,7 @@ PurpleStoredImage *purple_imgstore_find_
 /**
  * Retrieves a pointer to the image's data.
  *
- * @param img	The Image
+ * @param img The Image.
  *
  * @return A pointer to the data, which must not
  *         be freed or modified.
@@ -117,7 +135,7 @@ gconstpointer purple_imgstore_get_data(P
 /**
  * Retrieves the length of the image's data.
  *
- * @param img	The Image
+ * @param img The Image.
  *
  * @return The size of the data that the pointer returned by
  *         purple_imgstore_get_data points to.
@@ -127,7 +145,7 @@ size_t purple_imgstore_get_size(PurpleSt
 /**
  * Retrieves a pointer to the image's filename.
  *
- * @param img	The image
+ * @param img The image.
  *
  * @return A pointer to the filename, which must not
  *         be freed or modified.
@@ -138,7 +156,7 @@ const char *purple_imgstore_get_filename
  * Looks at the magic numbers of the image data (the first few bytes)
  * and returns an extension corresponding to the image's file type.
  *
- * @param img  The image.
+ * @param img The image.
  *
  * @return The image's extension (for example "png") or "icon"
  *         if unknown.
@@ -174,7 +192,7 @@ purple_imgstore_unref(PurpleStoredImage 
  * purple_imgstore_ref(), so if you have a PurpleStoredImage, it'll
  * be more efficient to call purple_imgstore_ref() directly.
  *
- * @param id		The ID for the image.
+ * @param id The ID for the image.
  */
 void purple_imgstore_ref_by_id(int id);
 
@@ -185,7 +203,7 @@ void purple_imgstore_ref_by_id(int id);
  * purple_imgstore_unref(), so if you have a PurpleStoredImage, it'll
  * be more efficient to call purple_imgstore_unref() directly.
  *
- * @param id		The ID for the image.
+ * @param id The ID for the image.
  */
 void purple_imgstore_unref_by_id(int id);