TpSimplePasswordManager

TpSimplePasswordManager — a simple X-TELEPATHY-PASSWORD channel manager

Synopsis

#include <telepathy-glib/telepathy-glib.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.