TpSimplePasswordManager: telepathy-glib API Reference Manual

## TpSimplePasswordManager TpSimplePasswordManager — a simple X-TELEPATHY-PASSWORD channel manager |

## Functions

TpSimplePasswordManager * | tp_simple_password_manager_new ()
void | tp_simple_password_manager_prompt_async ()
const GString * | tp_simple_password_manager_prompt_finish ()
void | tp_simple_password_manager_prompt_for_channel_async ()
const GString * | tp_simple_password_manager_prompt_for_channel_finish ()

## Properties

TpBaseConnection * | connection | Read / Write / Construct Only

## Types and Values

struct | TpSimplePasswordManager

## Object Hierarchy

        GObject
        ╰── TpSimplePasswordManager

## Implemented Interfaces

TpSimplePasswordManager implements TpChannelManager.

## Includes

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

## Description

This class makes it easy to implement the X-TELEPATHY-PASSWORD SASL mechanism in a connection manger. It implements the TpChannelManager interface and pops up a ServerAuthentication channel when `tp_simple_password_manager_prompt_async()` is called to enable a channel handler to pass in the password using the appropriate D-Bus methods.

This channel manager is only useful for connection managers only wanting to implement the X-TELEPATHY-PASSWORD SASL mechanism in authentication channels. For connections with more SASL mechanisms, the channel manager and channel itself should be reimplemented to support the desired mechanisms.

A new TpSimplePasswordManager object should be created in the TpBaseConnectionClass->create_channel_managers implementation and added to the GPtrArray of channel managers. Then, in the TpBaseConnectionClass->start_connecting implementation, once the connection status has been changed to CONNECTING, the connection should check whether a password parameter was given when creating the connection through RequestConnection. If a password is present, the connection should go ahead and use it. If it is not present, `tp_simple_password_manager_prompt_async()` should be called.

Once a password is retrieved using the server authentication channel, or an error is occurred, the callback that was passed to `tp_simple_password_manager_prompt_async()` is called and the connection should call `tp_simple_password_manager_prompt_finish()` to get the result of the process. If the GString returned from said finish function is non-NULL, the connection can then proceed with that password, otherwise the connection must deal with the error reached.

## Functions

### tp_simple_password_manager_new ()

    TpSimplePasswordManager *
    tp_simple_password_manager_new (TpBaseConnection *connection);

Creates a new simple server authentication channel manager.

#### Parameters

connection | a TpBaseConnection |

#### Returns

a new reference to a server authentication channel manager.

### tp_simple_password_manager_prompt_async ()

    void
    tp_simple_password_manager_prompt_async
                                   (TpSimplePasswordManager *self,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Pops up a new server authentication channel and handles the X-TELEPATHY-PASSWORD mechanism to obtain a password for the connection.

When the operation is finished, `callback` will be called. You must then call `tp_simple_password_manager_prompt_finish()` to get the result of the request.

#### Parameters

self | a TpSimplePasswordManager |
callback | a callback to call when the request is satisfied |
user_data | data to pass to `callback` |

Since: 0.13.8

### tp_simple_password_manager_prompt_finish ()

    const GString *
    tp_simple_password_manager_prompt_finish
                                   (TpSimplePasswordManager *self,
                                    GAsyncResult *result,
                                    GError **error);

Retrieve the value of the request begun with `tp_simple_password_manager_prompt_async()`.

#### Parameters

self | a TpSimplePasswordManager |
result | a GAsyncResult |
error | a GError to fill |

#### Returns

a GString with the password (or byte-blob) retrieved by `manager` .

[transfer none]

Since: 0.13.8

### tp_simple_password_manager_prompt_for_channel_async ()

    void
    tp_simple_password_manager_prompt_for_channel_async
                                   (TpSimplePasswordManager *self,
                                    TpBasePasswordChannel *channel,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Pops up a new server authentication channel and handles the X-TELEPATHY-PASSWORD mechanism to obtain a password for the connection.

When the operation is finished, `callback` will be called. You must then call `tp_simple_password_manager_prompt_for_channel_finish()` to get the result of the request.

Most of the time, `tp_simple_password_manager_prompt_async()` should be used instead. This function enables applications to provide custom channels instead of letting the password manager handle all of the channel details automatically. This may be useful if your SASL channel needs to implement additional interfaces (such as Channel.Interface.CredentialsStorage)

#### Parameters

self | a TpSimplePasswordManager |
channel | a TpBasePasswordChannel |
callback | a callback to call when the request is satisfied |
user_data | data to pass to `callback` |

Since: 0.13.15

### tp_simple_password_manager_prompt_for_channel_finish ()

    const GString *
    tp_simple_password_manager_prompt_for_channel_finish
                                   (TpSimplePasswordManager *self,
                                    GAsyncResult *result,
                                    TpBasePasswordChannel **channel,
                                    GError **error);

Retrieve the value of the request begun with `tp_simple_password_manager_prompt_for_channel_async()`.

#### Parameters

self | a TpSimplePasswordManager |
result | a GAsyncResult |
channel | an output location to retrieve the custom password channel that was passed to `tp_simple_password_manager_prompt_for_channel_async()`. | [transfer none]
error | a GError to fill |

#### Returns

a GString with the password (or byte-blob) retrieved by `manager` .

[transfer none]

Since: 0.13.15

## Types and Values

### struct TpSimplePasswordManager

    struct TpSimplePasswordManager;

A helper channel manager to manage X-TELEPATHY-PASSWORD ServerAuthentication channels.

Since: 0.13.8

## Property Details

### The `“connection”` property

      “connection”               TpBaseConnection *

The connection object that owns this channel manager.

Owner: TpSimplePasswordManager

Flags: Read / Write / Construct Only