TpDebugSender

TpDebugSender — object for exposing Telepathy debug interface

Functions

Properties

gboolean enabled Read / Write

Types and Values

struct TpDebugSender

Object Hierarchy

    GObject
    ╰── TpDebugSender

Implemented Interfaces

TpDebugSender implements TpSvcDebug1.

Includes

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

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 /im/telepathy/v1/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().

Functions

tp_debug_sender_dup ()

TpDebugSender *
tp_debug_sender_dup (void);

Returns a TpDebugSender instance on the session bus.

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 session bus connection

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.

Parameters

self

A TpDebugSender instance

 

timestamp

Time of the message or NULL for right now

 

domain

Message domain

 

level

The message level

 

string

The message string itself

 

Since 0.7.36


tp_debug_sender_add_message_vprintf ()

void
tp_debug_sender_add_message_vprintf (TpDebugSender *self,
                                     GTimeVal *timestamp,
                                     gchar **formatted,
                                     const gchar *domain,
                                     GLogLevelFlags level,
                                     const gchar *format,
                                     va_list args);

Formats and 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.

Parameters

self

A TpDebugSender instance

 

timestamp

Time of the message, or NULL for right now

 

formatted

Place to store the formatted message, or NULL if not needed

 

domain

Message domain

 

level

The message level

 

format

The printf() format string

 

args

the va_list of parameters to insert into format

 

Since 0.13.13


tp_debug_sender_add_message_printf ()

void
tp_debug_sender_add_message_printf (TpDebugSender *self,
                                    GTimeVal *timestamp,
                                    gchar **formatted,
                                    const gchar *domain,
                                    GLogLevelFlags level,
                                    const gchar *format,
                                    ...);

Formats and 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.

Parameters

self

A TpDebugSender instance

 

timestamp

Time of the message, or NULL for right now

 

formatted

Place to store the formatted message, or NULL if not required

 

domain

Message domain

 

level

The message level

 

format

The printf() format string

 

...

The parameters to insert into format

 

Since 0.13.13


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.

If timestamps should be prepended to messages (like in tp_debug_timestamped_log_handler()), tp_debug_sender_set_timestamps() should also be called.

Since version 0.11.15, this function can be called from any thread.

Parameters

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


tp_debug_sender_set_timestamps ()

void
tp_debug_sender_set_timestamps (TpDebugSender *self,
                                gboolean maybe);

If the log handler is tp_debug_sender_log_handler() then calling this function with TRUE on the debug sender will prepend the message to be printed to stdout with the UTC time (currently in ISO 8601 format, with microsecond resolution). This is equivalent to using tp_debug_timestamped_log_handler() as the log handler, but also logging to the debug sender.

Parameters

self

a TpDebugSender

 

maybe

whether to display message timestamps

 

Since 0.15.5

Types and Values

struct TpDebugSender

struct TpDebugSender;

An object for exposing the Telepathy debug interface.

Since 0.7.36

Property Details

The “enabled” property

  “enabled”                  gboolean

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

Flags: Read / Write

Default value: FALSE