TplLogManager

## TplLogManager TplLogManager — Fetch and search through logs |

## Synopsis

    #define             TPL_LOG_MANAGER_ERROR
    GQuark              tpl_log_manager_errors_quark        (void);
    enum                TplLogManagerError;
    struct              TplLogManager;
    enum                TplEventTypeMask;
    struct              TplLogSearchHit;
    gboolean            (*TplLogEventFilter)                (TplEvent *event,
                                                             gpointer user_data);
    TplLogManager *     tpl_log_manager_dup_singleton       (void);
    gboolean            tpl_log_manager_exists              (TplLogManager *manager,
                                                             TpAccount *account,
                                                             TplEntity *target,
                                                             gint type_mask);
    void                tpl_log_manager_get_dates_async     (TplLogManager *manager,
                                                             TpAccount *account,
                                                             TplEntity *target,
                                                             gint type_mask,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tpl_log_manager_get_dates_finish    (TplLogManager *self,
                                                             GAsyncResult *result,
                                                             GList **dates,
                                                             GError **error);
    void                tpl_log_manager_get_events_for_date_async
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             TplEntity *target,
                                                             gint type_mask,
                                                             const GDate *date,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tpl_log_manager_get_events_for_date_finish
                                                            (TplLogManager *self,
                                                             GAsyncResult *result,
                                                             GList **events,
                                                             GError **error);
    void                tpl_log_manager_get_filtered_events_async
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             TplEntity *target,
                                                             gint type_mask,
                                                             guint num_events,
                                                             TplLogEventFilter filter,
                                                             gpointer filter_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tpl_log_manager_get_filtered_events_finish
                                                            (TplLogManager *self,
                                                             GAsyncResult *result,
                                                             GList **events,
                                                             GError **error);
    TplLogWalker *      tpl_log_manager_walk_filtered_events
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             TplEntity *target,
                                                             gint type_mask,
                                                             TplLogEventFilter filter,
                                                             gpointer filter_data);
    void                tpl_log_manager_get_entities_async  (TplLogManager *self,
                                                             TpAccount *account,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tpl_log_manager_get_entities_finish (TplLogManager *self,
                                                             GAsyncResult *result,
                                                             GList **entities,
                                                             GError **error);
    void                tpl_log_manager_search_async        (TplLogManager *manager,
                                                             const gchar *text,
                                                             gint type_mask,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tpl_log_manager_search_finish       (TplLogManager *self,
                                                             GAsyncResult *result,
                                                             GList **hits,
                                                             GError **error);
    void                tpl_log_manager_search_free         (GList *hits);

## Object Hierarchy

      GObject
       +----TplLogManager

## Description

The TplLogManager object allows user to fetch logs and make searches.

## Details

### TPL_LOG_MANAGER_ERROR

    #define TPL_LOG_MANAGER_ERROR tpl_log_manager_errors_quark()

The error domain for the TplLogManager.

### tpl_log_manager_errors_quark ()

    GQuark              tpl_log_manager_errors_quark        (void);

Returns : | the GQuark associated with the error domain of TplLogManager

### enum TplLogManagerError

    typedef enum {
      TPL_LOG_MANAGER_ERROR_ADD_EVENT
    } TplLogManagerError;

`TPL_LOG_MANAGER_ERROR_ADD_EVENT` | Error return when adding logs fails

### struct TplLogManager

    struct TplLogManager;

An object used to access logs

### enum TplEventTypeMask

    typedef enum {
      TPL_EVENT_MASK_TEXT         = 1 << 0,
      TPL_EVENT_MASK_CALL         = 1 << 1,
      TPL_EVENT_MASK_ANY          = 0xffff
    } TplEventTypeMask;

Mask used to filter type of TplEvent returned.

`TPL_EVENT_MASK_TEXT` | Mask to TplTextEvent
`TPL_EVENT_MASK_CALL` | Mask to TplCallEvent
`TPL_EVENT_MASK_ANY` | Special value to select all type of TplEvent

### struct TplLogSearchHit

    struct TplLogSearchHit {
      TpAccount *account;
      TplEntity *target;
      GDate *date;
    };

Represent the context where the search has results.

TpAccount *`account`; | the TpAccount
TplEntity *`target`; | the TplEntity
GDate *`date`; | the GDate

### TplLogEventFilter ()

    gboolean            (*TplLogEventFilter)                (TplEvent *event,
                                                             gpointer user_data);

`event` : | the TplEvent to filter
`user_data` : | user-supplied data
Returns : | `TRUE` if `event` should appear in the result

### tpl_log_manager_dup_singleton ()

    TplLogManager *     tpl_log_manager_dup_singleton       (void);

Returns : | a new reference on the log manager. [transfer full]

### tpl_log_manager_exists ()

    gboolean            tpl_log_manager_exists              (TplLogManager *manager,
                                                             TpAccount *account,
                                                             TplEntity *target,
                                                             gint type_mask);

Checks if logs exist for `target`.

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

`manager` : | TplLogManager
`account` : | TpAccount
`target` : | a non-NULL TplEntity
`type_mask` : | event type filter see TplEventTypeMask
Returns : | `TRUE` logs exist for `target`, otherwise `FALSE`

### tpl_log_manager_get_dates_async ()

    void                tpl_log_manager_get_dates_async     (TplLogManager *manager,
                                                             TpAccount *account,
                                                             TplEntity *target,
                                                             gint type_mask,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Retrieves a list of GDate corresponding to each day where at least one event exist for `target`.

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

`manager` : | a TplLogManager
`account` : | a TpAccount
`target` : | a non-NULL TplEntity
`type_mask` : | event type filter see TplEventTypeMask
`callback` : | a callback to call when the request is satisfied
`user_data` : | data to pass to `callback`

### tpl_log_manager_get_dates_finish ()

    gboolean            tpl_log_manager_get_dates_finish    (TplLogManager *self,
                                                             GAsyncResult *result,
                                                             GList **dates,
                                                             GError **error);

`self` : | a TplLogManager
`result` : | a GAsyncResult
`dates` : | a pointer to a GList used to return the list of GDate. [out][transfer full][element-type GLib.Date]
`error` : | a GError to fill
Returns : | TRUE if the operation was successful, otherwise FALSE

### tpl_log_manager_get_events_for_date_async ()

    void                tpl_log_manager_get_events_for_date_async
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             TplEntity *target,
                                                             gint type_mask,
                                                             const GDate *date,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Retrieve a list of TplEvent at `date` with `target`.

`manager` : | a TplLogManager
`account` : | a TpAccount
`target` : | a non-NULL TplEntity
`type_mask` : | event type filter see TplEventTypeMask
`date` : | a GDate
`callback` : | a callback to call when the request is satisfied
`user_data` : | data to pass to `callback`

### tpl_log_manager_get_events_for_date_finish ()

    gboolean            tpl_log_manager_get_events_for_date_finish
                                                            (TplLogManager *self,
                                                             GAsyncResult *result,
                                                             GList **events,
                                                             GError **error);

`self` : | a TplLogManager
`result` : | a GAsyncResult
`events` : | a pointer to a GList used to return the list of TplEvent. [out][transfer full][element-type TelepathyLogger.Event]
`error` : | a GError to fill
Returns : | TRUE if the operation was successful, otherwise FALSE

### tpl_log_manager_get_filtered_events_async ()

    void                tpl_log_manager_get_filtered_events_async
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             TplEntity *target,
                                                             gint type_mask,
                                                             guint num_events,
                                                             TplLogEventFilter filter,
                                                             gpointer filter_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Retrieve the most recent `num_event` events exchanged with `target`.

`manager` : | a TplLogManager
`account` : | a TpAccount
`target` : | a non-NULL TplEntity
`type_mask` : | event type filter see TplEventTypeMask
`num_events` : | number of maximum events to fetch
`filter` : | an optional filter function. [scope call][allow-none]
`filter_user_data` : | user data to pass to `filter`
`callback` : | a callback to call when the request is satisfied. [scope async][allow-none]
`user_data` : | data to pass to `callback`

### tpl_log_manager_get_filtered_events_finish ()

    gboolean            tpl_log_manager_get_filtered_events_finish
                                                            (TplLogManager *self,
                                                             GAsyncResult *result,
                                                             GList **events,
                                                             GError **error);

`self` : | a TplLogManager
`result` : | a GAsyncResult
`events` : | a pointer to a GList used to return the list TplEvent. [out][transfer full][element-type TelepathyLogger.Event]
`error` : | a GError to fill
Returns : | TRUE if the operation was successful, otherwise FALSE.

### tpl_log_manager_walk_filtered_events ()

    TplLogWalker *      tpl_log_manager_walk_filtered_events
                                                            (TplLogManager *manager,
                                                             TpAccount *account,
                                                             TplEntity *target,
                                                             gint type_mask,
                                                             TplLogEventFilter filter,
                                                             gpointer filter_data);

Create a TplLogWalker to traverse all the events exchanged with `target`.

`manager` : | a TplLogManager
`account` : | a TpAccount
`target` : | a non-NULL TplEntity
`type_mask` : | event type filter see TplEventTypeMask
`filter` : | an optional filter function. [scope call][allow-none]
`filter_data` : | user data to pass to `filter`
Returns : | a TplLogWalker. [transfer full]

### tpl_log_manager_get_entities_async ()

    void                tpl_log_manager_get_entities_async  (TplLogManager *self,
                                                             TpAccount *account,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Start a query looking for all entities for which you have logs in the `account`.

`self` : | a TplLogManager
`account` : | a TpAccount
`callback` : | a callback to call when the request is satisfied
`user_data` : | data to pass to `callback`

### tpl_log_manager_get_entities_finish ()

    gboolean            tpl_log_manager_get_entities_finish (TplLogManager *self,
                                                             GAsyncResult *result,
                                                             GList **entities,
                                                             GError **error);

`self` : | a TplLogManager
`result` : | a GAsyncResult
`entities` : | a pointer to a GList used to return the list of TplEntity, to be freed using something like g_list_free_full (lst, g_object_unref). [out][transfer full][element-type TelepathyLogger.Entity]
`error` : | a GError to fill
Returns : | TRUE if the operation was successful, otherwise FALSE

### tpl_log_manager_search_async ()

    void                tpl_log_manager_search_async        (TplLogManager *manager,
                                                             const gchar *text,
                                                             gint type_mask,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Search for all the conversations containing `text`.

`manager` : | a TplLogManager
`text` : | the pattern to search
`type_mask` : | event type filter see TplEventTypeMask
`callback` : | a callback to call when the request is satisfied
`user_data` : | data to pass to `callback`

### tpl_log_manager_search_finish ()

    gboolean            tpl_log_manager_search_finish       (TplLogManager *self,
                                                             GAsyncResult *result,
                                                             GList **hits,
                                                             GError **error);

`self` : | a TplLogManager
`result` : | a GAsyncResult
`hits` : | a pointer to a GList used to return the list of TplLogSearchHit. [out][transfer full][element-type TelepathyLogger.SearchHit]
`error` : | a GError to fill
Returns : | TRUE if the operation was successful, otherwise FALSE

### tpl_log_manager_search_free ()

    void                tpl_log_manager_search_free         (GList *hits);

Free `hits` and its content.

`hits` : | a GList of TplLogSearchHit