log-manager

## log-manager log-manager |

## Synopsis

    #define             TPL_LOG_MANAGER_ERROR
    #define             TPL_LOG_MANAGER_LOG_STORE_DEFAULT
    enum                TplLogManagerError;
    TplLogManager *     tpl_log_manager_dup_singleton       (void);
    gboolean            tpl_log_manager_exists              (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean chatroom);
    GList *             tpl_log_manager_get_dates           (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean chatroom);
    void                tpl_log_manager_get_dates_async     (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean is_chatroom,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GList *             tpl_log_manager_get_messages_for_date
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean chatroom,
                                                             const gchar *date);
    void                tpl_log_manager_get_messages_for_date_async
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean is_chatroom,
                                                             const gchar *date,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GList *             tpl_log_manager_get_filtered_messages
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean chatroom,
                                                             guint num_messages,
                                                             TplLogMessageFilter filter,
                                                             gpointer user_data);
    void                tpl_log_manager_get_filtered_messages_async
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean is_chatroom,
                                                             guint num_messages,
                                                             TplLogMessageFilter filter,
                                                             gpointer filter_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GList *             tpl_log_manager_get_chats           (TplLogManager *manager,
                                                             TpAccount *account);
    void                tpl_log_manager_get_chats_async     (TplLogManager *manager,
                                                             TpAccount *account,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GList *             tpl_log_manager_search_in_identifier_chats_new
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             gchar const *chat_id,
                                                             const gchar *text);
    void                tpl_log_manager_search_in_identifier_chats_new_async
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             gchar const *chat_id,
                                                             const gchar *text,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GList *             tpl_log_manager_search_new          (TplLogManager *manager,
                                                             const gchar *text);
    void                tpl_log_manager_search_new_async    (TplLogManager *manager,
                                                             const gchar *text,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    void                tpl_log_manager_search_free         (GList *hits);
    gchar *             tpl_log_manager_get_date_readable   (const gchar *date);
    void                tpl_log_manager_search_hit_free     (TplLogSearchHit *hit);
    gint                tpl_log_manager_search_hit_compare  (TplLogSearchHit *a,
                                                             TplLogSearchHit *b);
    gboolean            tpl_log_manager_register_log_store  (TplLogManager *self,
                                                             TplLogStore *logstore);

## Description

## Details

### TPL_LOG_MANAGER_ERROR

    #define TPL_LOG_MANAGER_ERROR g_quark_from_static_string ("tpl-log-manager-error-quark")

### TPL_LOG_MANAGER_LOG_STORE_DEFAULT

    #define TPL_LOG_MANAGER_LOG_STORE_DEFAULT "TpLogger"

### enum TplLogManagerError

    typedef enum
    {
      /* generic error */
      TPL_LOG_MANAGER_ERROR_FAILED,
      TPL_LOG_MANAGER_ERROR_ADD_MESSAGE,
      /* arg passed is not a valid GObject or in the expected format */
      TPL_LOG_MANAGER_ERROR_BAD_ARG
    } TplLogManagerError;

### tpl_log_manager_dup_singleton ()

    TplLogManager *     tpl_log_manager_dup_singleton       (void);

Returns : |

### tpl_log_manager_exists ()

    gboolean            tpl_log_manager_exists              (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean chatroom);

Checks if `chat_id` does exist for `account` and - is a chatroom, if `chatroom` is `TRUE` - is not a chatroom, if `chatroom` is `FALSE`

It applies for any registered TplLogStore with the "readable" property `TRUE`.

`manager` : | TplLogManager
`account` : | TpAccount
`chat_id` : | a non-NULL chat id
`chatroom` : | whether `chat_id` is a chatroom or not
Returns : | `TRUE` if `chat_id` exists, `FALSE` otherwise

### tpl_log_manager_get_dates ()

    GList *             tpl_log_manager_get_dates           (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean chatroom);

Retrieves a list of dates, in string form YYYYMMDD, corrisponding to each day at least a message was sent to or received from `chat_id`. `chat_id` may be the id of a buddy or a chatroom, depending on the value of `chatroom`.

It applies for any registered TplLogStore with the "readable" property `TRUE`.

`manager` : | a TplLogManager
`account` : | a TpAccount
`chat_id` : | a non-NULL chat identifier
`chatroom` : | whather if the request is related to a chatroom or not.
Returns : | a GList of (char *), to be freed using something like g_list_foreach (lst, g_free, NULL); g_list_free (lst);

### tpl_log_manager_get_dates_async ()

    void                tpl_log_manager_get_dates_async     (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean is_chatroom,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

`manager` : |
`account` : |
`chat_id` : |
`is_chatroom` : |
`callback` : |
`user_data` : |

### tpl_log_manager_get_messages_for_date ()

    GList *             tpl_log_manager_get_messages_for_date
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean chatroom,
                                                             const gchar *date);

`manager` : |
`account` : |
`chat_id` : |
`chatroom` : |
`date` : |
Returns : |

### tpl_log_manager_get_messages_for_date_async ()

    void                tpl_log_manager_get_messages_for_date_async
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean is_chatroom,
                                                             const gchar *date,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

`manager` : |
`account` : |
`chat_id` : |
`is_chatroom` : |
`date` : |
`callback` : |
`user_data` : |

### tpl_log_manager_get_filtered_messages ()

    GList *             tpl_log_manager_get_filtered_messages
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean chatroom,
                                                             guint num_messages,
                                                             TplLogMessageFilter filter,
                                                             gpointer user_data);

`manager` : |
`account` : |
`chat_id` : |
`chatroom` : |
`num_messages` : |
`filter` : |
`user_data` : |
Returns : |

### tpl_log_manager_get_filtered_messages_async ()

    void                tpl_log_manager_get_filtered_messages_async
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             const gchar *chat_id,
                                                             gboolean is_chatroom,
                                                             guint num_messages,
                                                             TplLogMessageFilter filter,
                                                             gpointer filter_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

`manager` : |
`account` : |
`chat_id` : |
`is_chatroom` : |
`num_messages` : |
`filter` : |
`filter_user_data` : |
`callback` : |
`user_data` : |

### tpl_log_manager_get_chats ()

    GList *             tpl_log_manager_get_chats           (TplLogManager *manager,
                                                             TpAccount *account);

`manager` : |
`account` : |
Returns : |

### tpl_log_manager_get_chats_async ()

    void                tpl_log_manager_get_chats_async     (TplLogManager *manager,
                                                             TpAccount *account,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

`manager` : |
`account` : |
`callback` : |
`user_data` : |

### tpl_log_manager_search_in_identifier_chats_new ()

    GList *             tpl_log_manager_search_in_identifier_chats_new
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             gchar const *chat_id,
                                                             const gchar *text);

`manager` : |
`account` : |
`chat_id` : |
`text` : |
Returns : |

### tpl_log_manager_search_in_identifier_chats_new_async ()

    void                tpl_log_manager_search_in_identifier_chats_new_async
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             gchar const *chat_id,
                                                             const gchar *text,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

`manager` : |
`account` : |
`chat_id` : |
`text` : |
`callback` : |
`user_data` : |

### tpl_log_manager_search_new ()

    GList *             tpl_log_manager_search_new          (TplLogManager *manager,
                                                             const gchar *text);

`manager` : |
`text` : |
Returns : |

### tpl_log_manager_search_new_async ()

    void                tpl_log_manager_search_new_async    (TplLogManager *manager,
                                                             const gchar *text,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

`manager` : |
`text` : |
`callback` : |
`user_data` : |

### tpl_log_manager_search_free ()

    void                tpl_log_manager_search_free         (GList *hits);

`hits` : |

### tpl_log_manager_get_date_readable ()

    gchar *             tpl_log_manager_get_date_readable   (const gchar *date);

`date` : |
Returns : |

### tpl_log_manager_search_hit_free ()

    void                tpl_log_manager_search_hit_free     (TplLogSearchHit *hit);

`hit` : |

### tpl_log_manager_search_hit_compare ()

    gint                tpl_log_manager_search_hit_compare  (TplLogSearchHit *a,
                                                             TplLogSearchHit *b);

Compare `a` and `b`, returning an ordered relation between the two. Acts similar to the strcmp family, with the difference that since TplLogSerachHit is not a plain string, but a struct, the order relation will be a coposition of: - the order relation between `a.chat_it` and `b.chat_id` - the order relation between `a.chatroom` and `b.chatroom`, being chatroom = `FALSE` > chatroom = `TRUE` (meaning: a 1-1 message is greater than a chatroom one).

`a` : | a TplLogSerachHit
`b` : | a TplLogSerachHit
Returns : | a list of pointer to TplLogSearchHit, having chat_id and is_chatroom fields filled. the result needs to be freed after use using tpl_log_manager_search_hit_free

### tpl_log_manager_register_log_store ()

    gboolean            tpl_log_manager_register_log_store  (TplLogManager *self,
                                                             TplLogStore *logstore);

It registers `logstore` into `manager`, the log store has to be an implementation of the TplLogStore interface.

`logstore` has to properly implement the add_message method if the "writable" is set to `TRUE`.

`logstore` has to properly implement all the search/query methods if the "readable" is set to `TRUE`.

`self` : | the log manager
`logstore` : | a TplLogStore interface implementation
Returns : |