telepathy-logger Reference Manual: TplLogWalker

## TplLogWalker TplLogWalker — Iterate over the logs |

## Functions

void | tpl_log_walker_get_events_async ()
gboolean | tpl_log_walker_get_events_finish ()
void | tpl_log_walker_rewind_async ()
gboolean | tpl_log_walker_rewind_finish ()
gboolean | tpl_log_walker_is_start ()
gboolean | tpl_log_walker_is_end ()

## Properties

gpointer | filter | Read / Write / Construct Only
gpointer | filter-data | Read / Write / Construct Only

## Types and Values

| TplLogWalkerPriv

## Object Hierarchy

        GObject
        ╰── TplLogWalker

## Description

The TplLogWalker object allows the user to sequentially iterate over the logs.

Example 1. Using a TplLogWalker to fetch text events from the logs.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    #include <telepathy-glib/telepathy-glib.h>
    #include <telepathy-logger/telepathy-logger.h>

    static GMainLoop * loop = NULL;

    static void
    events_foreach (gpointer data, gpointer user_data)
    {
      TplEvent *event = TPL_EVENT (data);
      const gchar *message;
      gint64 timestamp;

      timestamp = tpl_event_get_timestamp (event);
      message = tpl_text_event_get_message (TPL_TEXT_EVENT (event));
      g_message ("%" G_GINT64_FORMAT " %s", timestamp, message);
    }

    static void
    log_walker_get_events_cb (GObject *source_object,
        GAsyncResult *res,
        gpointer user_data)
    {
      TplLogWalker *walker = TPL_LOG_WALKER (source_object);
      GList *events;

      if (!tpl_log_walker_get_events_finish (walker, res, &events, NULL))
        {
          g_main_loop_quit (loop);
          return;
        }

      g_list_foreach (events, events_foreach, NULL);
      g_list_free_full (events, g_object_unref);
      if (tpl_log_walker_is_end (walker))
        {
          g_main_loop_quit (loop);
          return;
        }

      g_message ("");
      tpl_log_walker_get_events_async (walker,
          5,
          log_walker_get_events_cb,
          NULL);
    }

    static void
    accounts_foreach (gpointer data, gpointer user_data)
    {
      TpAccount **account_out = (TpAccount **) user_data;
      TpAccount *account = TP_ACCOUNT (data);
      const gchar *display_name;

      display_name = tp_account_get_display_name (account);
      if (0 != g_strcmp0 (display_name, "alice@bar.net"))
        return;

      g_object_ref (account);
      *account_out = account;
    }

    static void
    account_manager_prepare_cb (GObject * source_object,
        GAsyncResult * res,
        gpointer user_data)
    {
      TpAccountManager *account_manager = TP_ACCOUNT_MANAGER (source_object);
      GList *accounts;
      TpAccount *account = NULL;
      TplLogManager *log_manager;
      TplLogWalker *walker;
      TplEntity *target;

      if (!tp_proxy_prepare_finish (source_object, res, NULL))
        return;

      accounts = tp_account_manager_get_valid_accounts (account_manager);
      g_list_foreach (accounts, accounts_foreach, &account);
      g_list_free_full (accounts, g_object_unref);
      if (account == NULL)
        {
          g_main_loop_quit (loop);
          return;
        }

      log_manager = tpl_log_manager_dup_singleton ();

      target = tpl_entity_new ("bob@foo.net", TPL_ENTITY_CONTACT, NULL, NULL);

      walker = tpl_log_manager_walk_filtered_events (log_manager,
          account,
          target,
          TPL_EVENT_MASK_TEXT,
          NULL,
          NULL);

      tpl_log_walker_get_events_async (walker,
          5,
          log_walker_get_events_cb,
          NULL);

      g_object_unref (walker);
      g_object_unref (target);
      g_object_unref (log_manager);
      g_object_unref (account);
    }

    int
    main (int argc,
        char *argv[])
    {
      GQuark features[] = { TP_ACCOUNT_MANAGER_FEATURE_CORE, 0 };
      TpAccountManager * account_manager;

      g_type_init ();
      loop = g_main_loop_new (NULL, FALSE);

      account_manager = tp_account_manager_dup ();
      tp_proxy_prepare_async (account_manager,
          features,
          account_manager_prepare_cb,
          NULL);

      g_main_loop_run (loop);

      g_object_unref (account_manager);
      g_main_loop_unref (loop);
      return 0;
    }

## Functions

### tpl_log_walker_get_events_async ()

    void
    tpl_log_walker_get_events_async (TplLogWalker *walker,
                                     guint num_events,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Walk the logs to retrieve the next most recent `num_event` events.

#### Parameters

walker | a TplLogWalker |
num_events | number of maximum events to fetch |
callback | a callback to call when the request is satisfied. | [scope async][allow-none]
user_data | data to pass to `callback` |

Since 0.8.0

### tpl_log_walker_get_events_finish ()

    gboolean
    tpl_log_walker_get_events_finish (TplLogWalker *walker,
                                      GAsyncResult *result,
                                      GList **events,
                                      GError **error);

#### Parameters

walker | a TplLogWalker |
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.

Since 0.8.0

### tpl_log_walker_rewind_async ()

    void
    tpl_log_walker_rewind_async (TplLogWalker *walker,
                                 guint num_events,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data);

Move the `walker` back by the last `num_event` events that were returned by `tpl_log_walker_get_events_async()`.

#### Parameters

walker | a TplLogWalker |
num_events | number of events to move back |
callback | a callback to call when the request is satisfied. | [scope async][allow-none]
user_data | data to pass to `callback` |

Since 0.8.0

### tpl_log_walker_rewind_finish ()

    gboolean
    tpl_log_walker_rewind_finish (TplLogWalker *walker,
                                  GAsyncResult *result,
                                  GError **error);

#### Parameters

walker | a TplLogWalker |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

TRUE if the operation was successful, otherwise FALSE.

Since 0.8.0

### tpl_log_walker_is_start ()

    gboolean
    tpl_log_walker_is_start (TplLogWalker *walker);

Determines whether `walker` is pointing at the most recent event in the logs. This is the case when `walker` has not yet returned any events or has been rewound completely.

#### Parameters

walker | a TplLogWalker |

#### Returns

TRUE if `walker` is pointing at the most recent event, otherwise FALSE.

Since 0.8.0

### tpl_log_walker_is_end ()

    gboolean
    tpl_log_walker_is_end (TplLogWalker *walker);

Determines whether `walker` has run out of events. This is the case when `walker` has returned all the events from the logs.

#### Parameters

walker | a TplLogWalker |

#### Returns

TRUE if `walker` has run out of events, otherwise FALSE.

Since 0.8.0

## Types and Values

### TplLogWalkerPriv

    typedef struct _TplLogWalkerPriv TplLogWalkerPriv;

## Property Details

### The `“filter”` property

      “filter”                   gpointer

An optional filter function.

Flags: Read / Write / Construct Only

### The `“filter-data”` property

      “filter-data”              gpointer

User data to pass to the filter function.

Flags: Read / Write / Construct Only