cpw.nader.asynclogging-3: 9f750254: Finished off all the undocumented new fu...
morshed.nader at gmail.com
morshed.nader at gmail.com
Sun Mar 20 23:30:49 EDT 2011
----------------------------------------------------------------------
Revision: 9f750254a977e6e08652797cf14c8fb96bb41ee8
Parent: d1bd2a8a6865741bc8e328bbfcebc71ea26696e1
Author: morshed.nader at gmail.com
Date: 03/20/11 23:28:07
Branch: im.pidgin.cpw.nader.asynclogging-3
URL: http://d.pidgin.im/viewmtn/revision/info/9f750254a977e6e08652797cf14c8fb96bb41ee8
Changelog:
Finished off all the undocumented new functions in log.h
Changes against parent d1bd2a8a6865741bc8e328bbfcebc71ea26696e1
patched libpurple/log.h
-------------- next part --------------
============================================================
--- libpurple/log.h d225c3bc5efbd80b870dc19471e70039d863d9b9
+++ libpurple/log.h 49955114bc2eacf6ae98ecb8e6f40f9355004f11
@@ -99,6 +99,9 @@ struct _PurpleLog {
*
* All asynchronous and finish methods are normally implemented by PurpleLog
* and rely on the synchronous versions being implemented by the subclasses
+ *
+ * For more examples using #GCancellable, #GAsyncReadyCallback, and
+ * #GAsyncResult, refer to Gio's documentaton.
*/
struct _PurpleLogClass {
GObjectClass parent_class;
@@ -419,7 +422,8 @@ gssize purple_log_write(PurpleLog *log,
* @param message The message to log (will be removed in function)
* @param io_priority The io priority of the request
* @param cancellable (allow-none): #GCancellable object
- * @param cb (allow-none): A #GAsyncReadyCallback to call when the request is satisfied
+ * @param cb (allow-none): A #GAsyncReadyCallback to call when the
+ request is satisfied
* @param userdata (allow-none): The data to pass to callback function
*
* @since 3.0.0
@@ -462,7 +466,8 @@ gchar *purple_log_read(PurpleLog *log, P
* @param log The log to read from
* @param io_priority The io priority of the request
* @param cancellable (allow-none): #GCancellable object
- * @param cb (allow-none): A #GAsyncReadyCallback to call when the request is satisfied
+ * @param cb (allow-none): A #GAsyncReadyCallback to call when the
+ request is satisfied
* @param userdata (allow-none): The data to pass to callback function
*
* @since 3.0.0
@@ -503,7 +508,8 @@ gssize purple_log_get_size(PurpleLog *lo
* @param log The log
* @param io_priority The io priority of the request
* @param cancellable (allow-none): #GCancellable object
- * @param cb (allow-none): A #GAsyncReadyCallback to call when the request is satisfied
+ * @param cb (allow-none): A #GAsyncReadyCallback to call when the
+ request is satisfied
* @param userdata (allow-none): The data to pass to callback function
*
* @since 3.0.0
@@ -576,11 +582,9 @@ GList *purple_log_get_logs_finish(Purple
GError **error);
/**
- * Gets a list of all available logs for all available added loggers
+ * Gets a list of all available logs for all available added loggers.
+ * See purple_log_get_logs() for more details.
*
- * Note: Make sure to examine that error is not NULL as it is completely possible
- * for the list to be empty and the function to return NULL without an error
- *
* @param type The type of the log
* @param name The name of the log
* @param account The account
@@ -594,14 +598,17 @@ GList *purple_logs_get_logs(PurpleLogCha
PurpleAccount *account, GCancellable *cancellable, GError **error);
/**
- * Asynchronously gets a list of all available logs for all available added loggers
+ * Asynchronously gets a list of all available logs for all available added
+ * loggers.
+ * See purple_log_get_logs_async() for more details.
*
* @param type The type of the log
* @param name The name of the log
* @param account The account
* @param io_priority The io priority of the request
* @param cancellable (allow-none): #GCancellable object
- * @param cb (allow-none): A #GAsyncReadyCallback to call when the request is satisfied
+ * @param cb (allow-none): A #GAsyncReadyCallback to call when the
+ request is satisfied
* @param userdata (allow-none): The data to pass to callback function
*
* @return pointer to log list or %NULL on error
@@ -614,10 +621,8 @@ void purple_logs_get_logs_async(PurpleLo
/**
* Finishes asynchronously getting a list of all available logs
+ * See purple_log_get_logs_finish() for more details.
*
- * Note: Make sure to examine that error is not NULL as it is completely possible
- * for the list to be empty and the function to return NULL without an error
- *
* @param res A #GAsyncResult
* @param error (out) (allow-none): a #GError location to store the error
*
@@ -630,7 +635,10 @@ GList *purple_logs_get_logs_finish(GAsyn
/**
* Returns a list of all available system logs
*
+ * @param log A dummy log of the type of logger to list the logs of
* @param account The account
+ * @param cancellable (allow-none): #GCancellable object
+ * @param error (out) (allow-none): a #GError location to store the error
*
* @return A sorted list of #PurpleLog<!-- -->s
*/
@@ -640,10 +648,12 @@ GList *purple_log_get_system_logs(Purple
/**
* Asychronously gets a list of all available system logs
*
+ * @param log A dummy log of the type of logger to list the logs of
* @param account The account
* @param io_priority The io priority of the request
* @param cancellable (allow-none): #GCancellable object
- * @param cb (allow-none): A #GAsyncReadyCallback to call when the request is satisfied
+ * @param cb (allow-none): A #GAsyncReadyCallback to call when the
+ request is satisfied
* @param userdata (allow-none): The data to pass to callback function
*
* @since 3.0.0
@@ -668,14 +678,51 @@ GList *purple_log_get_system_logs_finish
GList *purple_log_get_system_logs_finish(PurpleLog *log, GAsyncResult *res,
GError **error);
-//
+/**
+ * Gets a list of all available system logs for all added loggers.
+ * See purple_log_get_system_logs() for more details.
+ *
+ * @param account The account
+ * @param cancellable (allow-none): #GCancellable object
+ * @param error (out) (allow-none): a #GError location to store the error
+ *
+ * @return pointer to log list or %NULL on error
+ *
+ * @since 3.0.0
+ */
GList *purple_logs_get_system_logs(PurpleAccount *account,
GCancellable *cancellable, GError **error);
-//
+
+/**
+ * Asynchronously gets a list of all available system logs for all added
+ * loggers.
+ * See purple_log_get_system_logs_async() for more details.
+ *
+ * @param account The account
+ * @param io_priority The io priority of the request
+ * @param cancellable (allow-none): #GCancellable object
+ * @param cb (allow-none): A #GAsyncReadyCallback to call when the
+ request is satisfied
+ * @param userdata (allow-none): The data to pass to callback function
+ *
+ * @since 3.0.0
+ */
void purple_logs_get_system_logs_async(PurpleAccount *account,
gint io_priority, GCancellable *cancellable, GAsyncReadyCallback cb,
gpointer userdata);
-//
+
+/**
+ * Finishes asynchronously getting all available system logs for all added
+ * loggers.
+ * See purple_log_get_system_logs_finish() for more details.
+ *
+ * @param res A #GAsyncResult
+ * @param error (out) (allow-none): a #GError location to store the error
+ *
+ * @return pointer to log list or %NULL on error
+ *
+ * @since 3.0.0
+ */
GList *purple_logs_get_system_logs_finish(GAsyncResult *res, GError **error);
/**
@@ -685,7 +732,7 @@ GList *purple_logs_get_system_logs_finis
* @param name The name of the log
* @param account The account
*
- * @return The size in bytes
+ * @return Size of logs or -1 on error
*/
gssize purple_log_get_total_size(PurpleLog *log, PurpleLogChatType type,
const gchar *name, PurpleAccount *account, GCancellable *cancellable,
@@ -699,7 +746,8 @@ gssize purple_log_get_total_size(PurpleL
* @param account The account
* @param io_priority The io priority of the request
* @param cancellable (allow-none): #GCancellable object
- * @param cb (allow-none): A #GAsyncReadyCallback to call when the request is satisfied
+ * @param cb (allow-none): A #GAsyncReadyCallback to call when the
+ request is satisfied
* @param userdata (allow-none): The data to pass to callback function
*
* @since 3.0.0
@@ -714,23 +762,60 @@ void purple_log_get_total_size_async(Pur
* @param res A #GAsyncResult
* @param error (out) (allow-none): a #GError location to store the error
*
- * @return size of file or -1 on error
+ * @return Size of logs or -1 on error
*
* @since 3.0.0
*/
gssize purple_log_get_total_size_finish(PurpleLog *log, GAsyncResult *res,
GError **error);
-//
+/**
+ * Gets the total size of all stored conversations.
+ * See purple_log_get_total_size().
+ *
+ * @param type The type of the log
+ * @param name The name of the log
+ * @param account The account
+ * @param cancellable (allow-none): #GCancellable object
+ * @param error (out) (allow-none): a #GError location to store the error
+ *
+ * @return Size of logs or -1 on error
+ *
+ * @since 3.0.0
+ */
gssize purple_logs_get_total_size(PurpleLogChatType type, const gchar *name,
PurpleAccount *account, GCancellable *cancellable, GError **error);
-//
+/**
+ * Asynchronously gets the total size of all stored conversations.
+ * See purple_log_get_total_size_async().
+ *
+ * @param type The type of the log
+ * @param name The name of the log
+ * @param account The account
+ * @param io_priority The io priority of the request
+ * @param cancellable (allow-none): #GCancellable object
+ * @param cb (allow-none): A #GAsyncReadyCallback to call when the
+ request is satisfied
+ * @param userdata (allow-none): The data to pass to callback function
+ *
+ * @since 3.0.0
+ */
void purple_logs_get_total_size_async(PurpleLogChatType type,
const gchar *name, PurpleAccount *account, gint io_priority,
GCancellable *cancellable, GAsyncReadyCallback cb, gpointer userdata);
-//
+/**
+ * Finishes asynchronously getting the total size of all stored conversations.
+ * See purple_log_get_total_size_finish().
+ *
+ * @param res A #GAsyncResult
+ * @param error (out) (allow-none): a #GError location to store the error
+ *
+ * @return Size of logs or -1 on error
+ *
+ * @since 3.0.0
+ */
gssize purple_logs_get_total_size_finish(GAsyncResult *res, GError **error);
/**
@@ -760,7 +845,8 @@ GHashTable *purple_log_get_log_sets(Purp
*
* @param io_priority The io priority of the request
* @param cancellable (allow-none): #GCancellable object
- * @param cb (allow-none): A #GAsyncReadyCallback to call when the request is satisfied
+ * @param cb (allow-none): A #GAsyncReadyCallback to call when the
+ request is satisfied
* @param userdata (allow-none): The data to pass to callback function
*
* @since 3.0.0
@@ -774,22 +860,53 @@ void purple_log_get_log_sets_async(Purpl
* @param res A #GAsyncResult
* @param error (out) (allow-none): a #GError location to store the error
*
- * @return pointer to hash table of log sets or %NULL on error
+ * @return The hash table of log sets or %NULL on error
*
* @since 3.0.0
*/
GHashTable *purple_log_get_log_sets_finish(PurpleLog *log, GAsyncResult *res,
GError **error);
-//
+/**
+ * Gets a #GHashTable for the combined log sets of all accounts.
+ * See purple_log_get_log_sets() for more details.
+ *
+ * @param cancellable (allow-none): #GCancellable object
+ * @param error (out) (allow-none): a #GError location to store the error
+ *
+ * @return The hash table of the log sets or %NULL on error
+ *
+ * @since 3.0.0
+ */
GHashTable *purple_logs_get_log_sets(GCancellable *cancellable,
GError **error);
-//
+/**
+ * Asynchronously gets a #GHashTable for the combined log sets of all accounts.
+ * See purple_log_get_log_sets_async() for more details.
+ *
+ * @param io_priority The io priority of the request
+ * @param cancellable (allow-none): #GCancellable object
+ * @param cb (allow-none): A #GAsyncReadyCallback to call when the
+ request is satisfied
+ * @param userdata (allow-none): The data to pass to callback function
+ *
+ * @since 3.0.0
+ */
void purple_logs_get_log_sets_async(gint io_priority,
GCancellable *cancellable, GAsyncReadyCallback cb, gpointer userdata);
-//
+/**
+ * Finishes asynchronously getting the log sets for all accounts.
+ * See purple_log_get_log_sets_finish() for more details.
+ *
+ * @param res A #GAsyncResult
+ * @param error (out) (allow-none): a #GError location to store the error
+ *
+ * @return The hash table of the log sets or %NULL on error
+ *
+ * @since 3.0.0
+ */
GHashTable *purple_logs_get_log_sets_finish(GAsyncResult *res, GError **error);
/**
@@ -815,7 +932,8 @@ gssize purple_log_get_activity_score(Pur
* @param account The account
* @param io_priority The io priority of the request
* @param cancellable (allow-none): #GCancellable object
- * @param cb (allow-none): A #GAsyncReadyCallback to call when the request is satisfied
+ * @param cb (allow-none): A #GAsyncReadyCallback to call when the
+ request is satisfied
* @param userdata (allow-none): The data to pass to callback function
*
* @since 3.0.0
@@ -865,7 +983,8 @@ gboolean purple_log_remove(PurpleLog *lo
* @param log The log
* @param io_priority The io priority of the request
* @param cancellable (allow-none): #GCancellable object
- * @param cb (allow-none): A #GAsyncReadyCallback to call when the request is satisfied
+ * @param cb (allow-none): A #GAsyncReadyCallback to call when the
+ request is satisfied
* @param userdata (allow-none): The data to pass to callback function
*
* @since 3.0.0
More information about the Commits
mailing list