TpDebugSender

## TpDebugSender TpDebugSender — object for exposing Telepathy debug interface |

## Synopsis

    #include <telepathy-glib/debug-sender.h>

                        TpDebugSender;
    TpDebugSender *     tp_debug_sender_dup                 (void);
    void                tp_debug_sender_add_message         (TpDebugSender *self,
                                                             GTimeVal *timestamp,
                                                             const gchar *domain,
                                                             GLogLevelFlags level,
                                                             const gchar *string);
    void                tp_debug_sender_log_handler         (const gchar *log_domain,
                                                             GLogLevelFlags log_level,
                                                             const gchar *message,
                                                             gpointer exclude);

## Object Hierarchy

      GObject
       +----TpDebugSender

## Implemented Interfaces

TpDebugSender implements TpSvcDBusProperties and TpSvcDebug.

## Properties

      "enabled"                  gboolean              : Read / Write

## Description

A TpDebugSender object is an object exposing the Telepathy debug interface. There should be one object per process as it registers the object path /org/freedesktop/Telepathy/debug. Once the object exists and has the object path, messages can be passed to it using tp_debug_sender_add_message and signals will automatically be fired.

TpDebugSender is primarily designed for use in Connection Managers, but can be used by any other part of the Telepathy stack which wants to expose its debugging information over the debug interface.

In a Connection Manager, one would probably keep a ref to the TpDebugSender in the connection manager object, and when this said object is finalized, so is the process's TpDebugSender. A GLib log handler is also provided: `tp_debug_sender_log_handler()`.

## Details

### TpDebugSender

    typedef struct _TpDebugSender TpDebugSender;

An object for exposing the Telepathy debug interface.

Since 0.7.36

### tp_debug_sender_dup ()

    TpDebugSender *     tp_debug_sender_dup                 (void);

Returns a TpDebugSender instance on the bus this process was activated by (if it was launched by D-Bus service activation), or the session bus (otherwise).

The returned TpDebugSender is cached; the same TpDebugSender object will be returned by this function repeatedly, as long as at least one reference exists.

Returns : | a reference to the TpDebugSender instance for the current starter bus daemon

Since 0.7.36

### tp_debug_sender_add_message ()

    void                tp_debug_sender_add_message         (TpDebugSender *self,
                                                             GTimeVal *timestamp,
                                                             const gchar *domain,
                                                             GLogLevelFlags level,
                                                             const gchar *string);

Adds a new message to the debug sender message queue. If the "enabled" property is set to `TRUE`, then a NewDebugMessage signal will be fired too.

`self` : | A TpDebugSender instance
`timestamp` : | Time of the message
`domain` : | Message domain
`level` : | The message level
`string` : | The message string itself

Since 0.7.36

### tp_debug_sender_log_handler ()

    void                tp_debug_sender_log_handler         (const gchar *log_domain,
                                                             GLogLevelFlags log_level,
                                                             const gchar *message,
                                                             gpointer exclude);

A generic log handler designed to be used by CMs. It initially calls `g_log_default_handler()`, and then sends the message on the bus TpDebugSender.

The `exclude` parameter is designed to allow filtering one domain, instead of sending every message to the TpDebugSender: typical usage is for a process to filter out messages from its own `G_LOG_DOMAIN`, so that it can append a category to its own messages and pass them directly to tp_debug_sender_add_message. Note that every message, regardless of domain, is given to `g_log_default_handler()`.

Note that a ref to a TpDebugSender must be kept at all times otherwise no messages given to the handler will be sent to the Telepathy debug interface.

An example of its usage, taking in mind the notes above, follows:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    /* Create a main loop and debug sender */
    GMainLoop *loop = g_main_loop_new (NULL, FALSE);
    TpDebugSender *sender = tp_debug_sender_dup ();

    /* Set the default handler */
    g_log_set_default_handler (tp_debug_sender_log_handler, G_LOG_DOMAIN);

    /* Run the main loop, but keeping a ref on the TpDebugSender from
     * the beginning of this code sample. */
    g_main_loop_run (loop);

    /* g_main_loop_quit was called, so only now can we clean up the
     * TpDebugSender. */
    g_object_unref (sender);

(In a connection manager, replace `g_main_loop_run()` in the above example with `tp_run_connection_manager()`.)

This function is merely for convenience if it meets the requirements. It can easily be re-implemented in services, and does not need to be used.

`log_domain` : | domain of the message
`log_level` : | log leve of the message
`message` : | the message itself
`exclude` : | a log domain string to exclude from the TpDebugSender, or `NULL`

Since 0.7.36

## Property Details

### The `"enabled"` property

      "enabled"                  gboolean              : Read / Write

`TRUE` if the NewDebugMessage signal should be emitted when a new debug message is generated.

Default value: FALSE