Common debug support

## Common debug support Common debug support — API to activate debugging messages from telepathy-glib |

## Synopsis

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

    void                tp_debug_set_flags                  (const gchar *flags_string);
    void                tp_debug_set_persistent             (gboolean persistent);
    void                tp_debug_divert_messages            (const gchar *filename);
    void                tp_debug_timestamped_log_handler    (const gchar *log_domain,
                                                             GLogLevelFlags log_level,
                                                             const gchar *message,
                                                             gpointer ignored);

    void                tp_debug_set_flags_from_string      (const gchar *flags_string);
    void                tp_debug_set_flags_from_env         (const gchar *var);
    void                tp_debug_set_all_flags              (void);

## Description

telepathy-glib has an internal mechanism for debug messages and filtering. Connection managers written with telepathy-glib are expected to connect this to their own debugging mechanisms: when the CM's debugging mechanism is activated, it should call `tp_debug_set_flags()` and/or `tp_debug_set_persistent()`.

The supported debug-mode keywords and the debug messages that they enable are subject to change, but currently include:

- `misc` - low-level utility code
- `manager` - TpConnectionManager (client)
- `connection` - TpBaseConnection (service) and TpConnection (client)
- `contacts` - TpContact objects (client)
- `channel` - TpChannel (client)
- `im` - (text) instant messaging (service)
- `properties` - TpDBusPropertiesMixin and TpPropertiesMixin (service)
- `params` - connection manager parameters (service)
- `handles` - handle reference tracking tracking in TpBaseConnection (service) and TpConnection (client)
- `accounts` - the TpAccountManager and TpAccount objects (client)
- `contact-lists` - the TpBaseContactList (service)
- `debugger` - TpDebugClient objects
- `tls` - TpTLSCertificate objects (client)
- `all` - all of the above

## Details

### tp_debug_set_flags ()

    void                tp_debug_set_flags                  (const gchar *flags_string);

Set the debug flags indicated by `flags_string`, in addition to any already set.

The parsing matches that of `g_parse_debug_string()`.

If telepathy-glib was compiled with --disable-debug (not recommended), this function has no practical effect, since the debug messages it would enable were removed at compile time.

`flags_string` : | The flags to set, comma-separated. If `NULL` or empty, no additional flags are set.

Since 0.6.1

### tp_debug_set_persistent ()

    void                tp_debug_set_persistent             (gboolean persistent);

Used to enable persistent operation of the connection manager process for debugging purposes.

`persistent` : | TRUE prevents the connection manager mainloop from exiting, FALSE enables exiting if there are no connections (the default behavior).

### tp_debug_divert_messages ()

    void                tp_debug_divert_messages            (const gchar *filename);

Open the given file for writing and duplicate its file descriptor to be used for stdout and stderr. This has the effect of closing the previous stdout and stderr, and sending all messages that would have gone there to the given file instead.

By default the file is truncated and hence overwritten each time the process is executed. Since version 0.7.14, if the filename is prefixed with '+' then the file is not truncated and output is added at the end of the file.

Passing `NULL` to this function is guaranteed to have no effect. This is so you can call it with the recommended usage `tp_debug_divert_messages (g_getenv ("MYAPP_LOGFILE"))` and it won't do anything if the environment variable is not set.

This function still works if telepathy-glib was compiled without debug support.

`filename` : | A file to which to divert stdout and stderr, or `NULL` to do nothing

Since 0.7.1

### tp_debug_timestamped_log_handler ()

    void                tp_debug_timestamped_log_handler    (const gchar *log_domain,
                                                             GLogLevelFlags log_level,
                                                             const gchar *message,
                                                             gpointer ignored);

A GLogFunc that prepends the UTC time (currently in ISO 8601 format, with microsecond resolution) to the message, then calls g_log_default_handler.

Intended usage is:

    1
    2
    if (g_getenv ("MYPROG_TIMING") != NULL)
      g_log_set_default_handler (tp_debug_timestamped_log_handler, NULL);

If telepathy-glib was compiled with --disable-debug (not recommended), this function is equivalent to `g_log_default_handler()`.

Changed in 0.9.0: timestamps are now printed in UTC, in RFC-3339 format. Previously, they were printed in local time, in a format similar to RFC-3339.

`log_domain` : | the message's log domain
`log_level` : | the log level of the message
`message` : | the message to process
`ignored` : | not used

Since 0.7.1

### tp_debug_set_flags_from_string ()

    void                tp_debug_set_flags_from_string      (const gchar *flags_string);

### Warning

`tp_debug_set_flags_from_string` is deprecated and should not be used in newly-written code. since 0.6.1. Use `tp_debug_set_flags()` and `tp_debug_set_persistent()` instead

Set the debug flags indicated by `flags_string`, in addition to any already set. Unlike `tp_debug_set_flags()`, this enables persistence like `tp_debug_set_persistent()` if the "persist" flag is present or the string is "all" - this turns out to be unhelpful, as persistence should be orthogonal.

The parsing matches that of `g_parse_debug_string()`.

`flags_string` : | The flags to set, comma-separated. If `NULL` or empty, no additional flags are set.

### tp_debug_set_flags_from_env ()

    void                tp_debug_set_flags_from_env         (const gchar *var);

### Warning

`tp_debug_set_flags_from_env` is deprecated and should not be used in newly-written code. since 0.6.1. Use tp_debug_set_flags(g_getenv(...)) and `tp_debug_set_persistent()` instead

Equivalent to `tp_debug_set_flags_from_string (g_getenv (var))`, and has the same problem with persistence being included in "all".

`var` : | The name of the environment variable to parse

### tp_debug_set_all_flags ()

    void                tp_debug_set_all_flags              (void);

### Warning

`tp_debug_set_all_flags` is deprecated and should not be used in newly-written code. since 0.6.1. Use tp_debug_set_flags ("all") and `tp_debug_set_persistent()` instead.

Activate all possible debug modes. This also activates persistent mode, which should have been orthogonal.