## TpSimplePasswordManager

TpSimplePasswordManager — a simple X-TELEPATHY-PASSWORD channel manager

## Synopsis

    #include <telepathy-glib/simple-password-manager.h>

                        TpSimplePasswordManager;
    TpSimplePasswordManager * tp_simple_password_manager_new
                                                            (TpBaseConnection *connection);

    void                tp_simple_password_manager_prompt_async
                                                            (TpSimplePasswordManager *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    const GString *     tp_simple_password_manager_prompt_finish
                                                            (TpSimplePasswordManager *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_simple_password_manager_prompt_for_channel_async
                                                            (TpSimplePasswordManager *self,
                                                             TpBasePasswordChannel *channel,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    const GString *     tp_simple_password_manager_prompt_for_channel_finish
                                                            (TpSimplePasswordManager *self,
                                                             GAsyncResult *result,
                                                             TpBasePasswordChannel **channel,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----TpSimplePasswordManager

## Implemented Interfaces

TpSimplePasswordManager implements TpChannelManager.

## Properties

      "connection"               TpBaseConnection*     : Read / Write / Construct Only

## 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.

## Details

### TpSimplePasswordManager

    typedef struct _TpSimplePasswordManager TpSimplePasswordManager;

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

Since 0.13.8

### tp_simple_password_manager_new ()

    TpSimplePasswordManager * tp_simple_password_manager_new
                                                            (TpBaseConnection *connection);

Creates a new simple server authentication channel manager.

`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.

`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()`.

`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)

`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()`.

`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

## Property Details

### The `"connection"` property

      "connection"               TpBaseConnection*     : Read / Write / Construct Only

The connection object that owns this channel manager.