cpw.darkrain42.docs: 18a763ca: disapproval of revision '6ddba69dc6d0bac...

paul at darkrain42.org paul at darkrain42.org
Sat Apr 25 16:16:10 EDT 2009


-----------------------------------------------------------------
Revision: 18a763ca3d80ae60e586ade3456b8d59196a7b8f
Ancestor: 6ddba69dc6d0bac552c512dd4495b255463c1c5c
Author: paul at darkrain42.org
Date: 2009-04-20T00:02:16
Branch: im.pidgin.cpw.darkrain42.docs
URL: http://d.pidgin.im/viewmtn/revision/info/18a763ca3d80ae60e586ade3456b8d59196a7b8f

Modified files:
        ChangeLog.API libpurple/smiley.c libpurple/smiley.h

ChangeLog: 

disapproval of revision '6ddba69dc6d0bac552c512dd4495b255463c1c5c'
-------------- next part --------------
============================================================
--- ChangeLog.API	afa04cb443c0ee87022cc7eb89bd5103c85b6743
+++ ChangeLog.API	360e5fd079d3b227b725ddd06be2c7f1740b3a0b
@@ -30,7 +30,6 @@ version 2.6.0 (??/??/2009):
 		Deprecated:
 		* purple_buddy_get_local_alias
 		* purple_notify_user_info_remove_entry
-		* purple_smiley_get_storing_dir
 		* purple_status_type_set_primary_attr
 		* purple_status_type_add_attr
 		* purple_status_type_add_attrs
============================================================
--- libpurple/smiley.c	514576e7bafc0d208cd85df320dbf5c8cd53b430
+++ libpurple/smiley.c	525d1524918b111d3d5806f42b9ca54955a5643f
@@ -57,7 +57,9 @@ static gboolean smileys_loaded = FALSE;
 
 static guint save_timer = 0;
 static gboolean smileys_loaded = FALSE;
+static char *smileys_dir = NULL;
 
+#define SMILEYS_DEFAULT_FOLDER			"custom_smiley"
 #define SMILEYS_LOG_ID				"smileys"
 
 #define XML_FILE_NAME				"smileys.xml"
@@ -870,7 +872,7 @@ purple_smileys_get_storing_dir(void)
 const char *
 purple_smileys_get_storing_dir(void)
 {
-	return "";
+	return smileys_dir;
 }
 
 void
@@ -879,6 +881,8 @@ purple_smileys_init()
 	smiley_shortcut_index = g_hash_table_new_full(g_str_hash, g_str_equal, g_free, NULL);
 	smiley_checksum_index = g_hash_table_new_full(g_str_hash, g_str_equal, g_free, NULL);
 
+	smileys_dir = g_build_filename(purple_user_dir(), SMILEYS_DEFAULT_FOLDER, NULL);
+
 	purple_smileys_load();
 }
 
@@ -893,5 +897,6 @@ purple_smileys_uninit()
 
 	g_hash_table_destroy(smiley_shortcut_index);
 	g_hash_table_destroy(smiley_checksum_index);
+	g_free(smileys_dir);
 }
 
============================================================
--- libpurple/smiley.h	415a13181161b926cadaf806a9b125e35c3c3b7a
+++ libpurple/smiley.h	4902b9db64402a319cdcd8ae154dee876f2b433d
@@ -61,35 +61,38 @@ extern "C" {
 /*@{*/
 
 /**
- * GObject-fu.
+ * GObject foo.
  * @internal.
  */
 GType purple_smiley_get_type(void);
 
 /**
- * Create a new custom smiley from a PurpleStoredImage.
+ * Creates a new custom smiley structure and populates it.
  *
- * If a custom smiley with the given shortcut already exists, it
+ * If a custom smiley with the informed shortcut already exist, it
  * will be automaticaly returned.
  *
  * @param img         The image associated with the smiley.
- * @param shortcut    The associated shortcut (e.g. "(homer)").
+ * @param shortcut    The custom smiley associated shortcut.
  *
- * @return The custom smiley.
+ * @return The custom smiley structure filled up.
  */
 PurpleSmiley *
 purple_smiley_new(PurpleStoredImage *img, const char *shortcut);
 
 /**
- * Create a new custom smiley, reading the image data from a file.
+ * Creates a new custom smiley structure and populates it.
  *
- * If a custom smiley with the given shortcut already exists, it
+ * The data is retrieved from an already existent file.
+ *
+ * If a custom smiley with the informed shortcut already exist, it
  * will be automaticaly returned.
  *
- * @param shortcut           The associated shortcut (e.g. "(homer)").
- * @param filepath           The image file.
+ * @param shortcut           The custom smiley associated shortcut.
+ * @param filepath           The image file to be imported to a
+ *                           new custom smiley.
  *
- * @return The custom smiley.
+ * @return The custom smiley structure filled up.
  */
 PurpleSmiley *
 purple_smiley_new_from_file(const char *shortcut, const char *filepath);
@@ -106,28 +109,32 @@ purple_smiley_delete(PurpleSmiley *smile
  * Changes the custom smiley's shortcut.
  *
  * @param smiley    The custom smiley.
- * @param shortcut  The new shortcut. A custom smiley with this shortcut
- *                  cannot already be in use.
+ * @param shortcut  The custom smiley associated shortcut.
  *
- * @return TRUE if the shortcut was changed. FALSE otherwise.
+ * @return TRUE whether the shortcut is not associated with another
+ *         custom smiley and the parameters are valid. FALSE otherwise.
  */
 gboolean
 purple_smiley_set_shortcut(PurpleSmiley *smiley, const char *shortcut);
 
 /**
- * Changes the custom smiley's image data.
+ * Changes the custom smiley's data.
  *
+ * When the filename controling is made outside this API, the param
+ * #keepfilename must be TRUE.
+ * Otherwise, the file and filename will be regenerated, and the
+ * old one will be removed.
+ *
  * @param smiley             The custom smiley.
- * @param smiley_data        The custom smiley data, which the smiley code
- *                           takes ownership of and will free.
- * @param smiley_data_len    The length of the data in @a smiley_data.
+ * @param smiley_data        The custom smiley data.
+ * @param smiley_data_len    The custom smiley data length.
  */
 void
 purple_smiley_set_data(PurpleSmiley *smiley, guchar *smiley_data,
                                            size_t smiley_data_len);
 
 /**
- * Returns the custom smiley's associated shortcut (e.g. "(homer)").
+ * Returns the custom smiley's associated shortcut.
  *
  * @param smiley   The custom smiley.
  *
@@ -148,11 +155,11 @@ const char *purple_smiley_get_checksum(c
  * Returns the PurpleStoredImage with the reference counter incremented.
  *
  * The returned PurpleStoredImage reference counter must be decremented
- * when the caller is done using it.
+ * after use.
  *
  * @param smiley   The custom smiley.
  *
- * @return A PurpleStoredImage.
+ * @return A PurpleStoredImage reference.
  */
 PurpleStoredImage *purple_smiley_get_stored_image(const PurpleSmiley *smiley);
 
@@ -160,7 +167,7 @@ PurpleStoredImage *purple_smiley_get_sto
  * Returns the custom smiley's data.
  *
  * @param smiley  The custom smiley.
- * @param len     If not @c NULL, the length of the image data returned
+ * @param len     If not @c NULL, the length of the icon data returned
  *                will be set in the location pointed to by this.
  *
  * @return A pointer to the custom smiley data.
@@ -187,8 +194,6 @@ const char *purple_smiley_get_extension(
  * directly.  If you find yourself wanting to use this function, think
  * very long and hard about it, and then don't.
  *
- * Think some more.
- *
  * @param smiley  The custom smiley.
  *
  * @return A full path to the file, or @c NULL under various conditions.
@@ -205,8 +210,7 @@ char *purple_smiley_get_full_path(Purple
 /*@{*/
 
 /**
- * Returns a list of all custom smileys. The caller is responsible for freeing
- * the list.
+ * Returns a list of all custom smileys. The caller should free the list.
  *
  * @return A list of all custom smileys.
  */
@@ -214,21 +218,23 @@ purple_smileys_get_all(void);
 purple_smileys_get_all(void);
 
 /**
- * Returns a custom smiley given its shortcut.
+ * Returns the custom smiley given it's shortcut.
  *
  * @param shortcut The custom smiley's shortcut.
  *
- * @return The custom smiley if found, or @c NULL if not found.
+ * @return The custom smiley (with a reference for the caller) if found,
+ *         or @c NULL if not found.
  */
 PurpleSmiley *
 purple_smileys_find_by_shortcut(const char *shortcut);
 
 /**
- * Returns a custom smiley given its checksum.
+ * Returns the custom smiley given it's checksum.
  *
  * @param checksum The custom smiley's checksum.
  *
- * @return The custom smiley if found, or @c NULL if not found.
+ * @return The custom smiley (with a reference for the caller) if found,
+ *         or @c NULL if not found.
  */
 PurpleSmiley *
 purple_smileys_find_by_checksum(const char *checksum);
@@ -236,10 +242,10 @@ purple_smileys_find_by_checksum(const ch
 /**
  * Returns the directory used to store custom smiley cached files.
  *
- * @return The directory to store custom smyles cached files to.
+ * The default directory is PURPLEDIR/smileys, unless otherwise specified
+ * by purple_buddy_icons_set_cache_dir().
  *
- * @deprecated This function isn't used and does nothing and will be
- *             removed in 3.0.0.
+ * @return The directory to store custom smyles cached files to.
  */
 const char *purple_smileys_get_storing_dir(void);
 


More information about the Commits mailing list