TpAccountRequest

TpAccountRequest — object for a currently non-existent account in order to create easily without speaking fluent D-Bus

Synopsis

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

struct              TpAccountRequest;
struct              TpAccountRequestClass;
TpAccountRequest *  tp_account_request_new              (TpAccountManager *account_manager,
                                                         const gchar *manager,
                                                         const gchar *protocol,
                                                         const gchar *display_name);
TpAccountRequest *  tp_account_request_new_from_protocol
                                                        (TpAccountManager *account_manager,
                                                         TpProtocol *protocol,
                                                         const gchar *display_name);

void                tp_account_request_set_display_name (TpAccountRequest *self,
                                                         const gchar *name);
void                tp_account_request_set_icon_name    (TpAccountRequest *self,
                                                         const gchar *icon);
void                tp_account_request_set_nickname     (TpAccountRequest *self,
                                                         const gchar *nickname);
void                tp_account_request_set_requested_presence
                                                        (TpAccountRequest *self,
                                                         TpConnectionPresenceType presence,
                                                         const gchar *status,
                                                         const gchar *message);
void                tp_account_request_set_automatic_presence
                                                        (TpAccountRequest *self,
                                                         TpConnectionPresenceType presence,
                                                         const gchar *status,
                                                         const gchar *message);
void                tp_account_request_set_enabled      (TpAccountRequest *self,
                                                         gboolean enabled);
void                tp_account_request_set_connect_automatically
                                                        (TpAccountRequest *self,
                                                         gboolean connect_automatically);
void                tp_account_request_add_supersedes   (TpAccountRequest *self,
                                                         const gchar *superseded_path);
void                tp_account_request_set_avatar       (TpAccountRequest *self,
                                                         const guchar *avatar,
                                                         gsize len,
                                                         const gchar *mime_type);
void                tp_account_request_set_service      (TpAccountRequest *self,
                                                         const gchar *service);
void                tp_account_request_set_storage_provider
                                                        (TpAccountRequest *self,
                                                         const gchar *provider);

void                tp_account_request_set_parameter    (TpAccountRequest *self,
                                                         const gchar *key,
                                                         GVariant *value);
void                tp_account_request_set_parameter_string
                                                        (TpAccountRequest *self,
                                                         const gchar *key,
                                                         const gchar *value);
void                tp_account_request_unset_parameter  (TpAccountRequest *self,
                                                         const gchar *key);

void                tp_account_request_create_account_async
                                                        (TpAccountRequest *self,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
TpAccount *         tp_account_request_create_account_finish
                                                        (TpAccountRequest *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Object Hierarchy

  GObject
   +----TpAccountRequest

Properties

  "account-manager"          TpAccountManager*     : Read / Write / Construct Only
  "automatic-presence-type"  guint                 : Read
  "automatic-status"         gchar*                : Read
  "automatic-status-message" gchar*                : Read
  "avatar"                   GArray*               : Read
  "avatar-mime-type"         gchar*                : Read
  "connect-automatically"    gboolean              : Read
  "connection-manager"       gchar*                : Read / Write / Construct Only
  "display-name"             gchar*                : Read / Write / Construct Only
  "enabled"                  gboolean              : Read
  "icon-name"                gchar*                : Read
  "nickname"                 gchar*                : Read
  "parameters"               GVariant*             : Read
  "properties"               GVariant*             : Read
  "protocol"                 gchar*                : Read / Write / Construct Only
  "requested-presence-type"  guint                 : Read
  "requested-status"         gchar*                : Read
  "requested-status-message" gchar*                : Read
  "service"                  gchar*                : Read
  "storage-provider"         gchar*                : Read
  "supersedes"               GStrv                 : Read

Description

This is a convenience object to aid in the creation of accounts on a TpAccountManager without having to construct GHashTables with well-known keys. For example: 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
static void created_cb (GObject *object, GAsyncResult *res, gpointer user_data);

static void
create_acount (void)
{
  TpAccountManager *am = tp_account_manager_dup ();
  TpAccountRequest *req;

  req = tp_account_request_new (am, "gabble", "jabber", "Work Jabber account");

  tp_account_request_set_parameter (req, "account", "walter.white@lospollos.lit");

  // ...

  tp_account_request_create_account_async (req, created_cb, NULL);
  g_object_unref (req);
  g_object_unref (am);
}

static void
created_cb (GObject *object,
    GAsyncResult *result,
    gpointer user_data)
{
  TpAccountRequest *req = TP_ACCOUNT_REQUEST (object);
  TpAccount *account;
  GError *error = NULL;

  account = tp_account_request_create_account_finish (req, result, &error);

  if (account == NULL)
    {
      g_error ("Failed to create account: %s\n", error->message);
      g_clear_error (&error);
      return;
    }

  // ...

  g_object_unref (account);
}

Details

struct TpAccountRequest

struct TpAccountRequest;

An object for representing a currently non-existent account which is to be created on a TpAccountManager.

Since 0.19.1

struct TpAccountRequestClass

struct TpAccountRequestClass {
};

The class of a TpAccountRequest.

tp_account_request_new ()

TpAccountRequest *  tp_account_request_new              (TpAccountManager *account_manager,
                                                         const gchar *manager,
                                                         const gchar *protocol,
                                                         const gchar *display_name);

Convenience function to create a new account request object which will assist in the creation of a new account on account_manager, using connection manager manager, and protocol protocol.

account_manager :

 the TpAccountManager to create the account on

manager :

 the name of the connection manager

protocol :

 the name of the protocol on manager

display_name :

 the user-visible name of this account

Returns :

 a new reference to an account request object, or NULL if any argument is incorrect. [transfer full]

Since 0.19.1

tp_account_request_new_from_protocol ()

TpAccountRequest *  tp_account_request_new_from_protocol
                                                        (TpAccountManager *account_manager,
                                                         TpProtocol *protocol,
                                                         const gchar *display_name);

Convenience function to create a new TpAccountRequest object using a TpProtocol instance, instead of specifying connection manager and protocol name specifically. See tp_account_request_new() for more details.

account_manager :

 the TpAccountManager to create the account on

protocol :

 a TpProtocol

display_name :

 the user-visible name of this account

Returns :

 a new reference to an account request object, or NULL if any argument is incorrect. [transfer full]

Since 0.19.1

tp_account_request_set_display_name ()

void                tp_account_request_set_display_name (TpAccountRequest *self,
                                                         const gchar *name);

Set the display name for the new account, self, to name. Use the "display-name" property to read the current display name.

self :

 a TpAccountRequest

name :

 a display name for the account

Since 0.19.1

tp_account_request_set_icon_name ()

void                tp_account_request_set_icon_name    (TpAccountRequest *self,
                                                         const gchar *icon);

Set the icon name for the new account, self, to icon. Use the "icon-name" property to read the current icon name.

self :

 a TpAccountRequest

icon :

 an icon name for the account

Since 0.19.1

tp_account_request_set_nickname ()

void                tp_account_request_set_nickname     (TpAccountRequest *self,
                                                         const gchar *nickname);

Set the nickname for the new account, self, to nickname. Use the "nickname" property to read the current nickname.

self :

 a TpAccountRequest

nickname :

 a nickname for the account

Since 0.19.1

tp_account_request_set_requested_presence ()

void                tp_account_request_set_requested_presence
                                                        (TpAccountRequest *self,
                                                         TpConnectionPresenceType presence,
                                                         const gchar *status,
                                                         const gchar *message);

Set the requested presence for the new account, self, to the type (presence, status), with message message. Use the "requested-presence-type", "requested-status", and "requested-status-message" properties to read the current requested presence.

self :

 a TpAccountRequest

presence :

 the requested presence type

status :

 the requested presence status

message :

 the requested presence message

Since 0.19.1

tp_account_request_set_automatic_presence ()

void                tp_account_request_set_automatic_presence
                                                        (TpAccountRequest *self,
                                                         TpConnectionPresenceType presence,
                                                         const gchar *status,
                                                         const gchar *message);

Set the automatic presence for the new account, self, to the type (presence, status), with message message. Use the "automatic-presence-type", "automatic-status", and "automatic-status-message" properties to read the current automatic presence.

self :

 a TpAccountRequest

presence :

 the automatic presence type

status :

 the automatic presence status

message :

 the automatic presence message

Since 0.19.1

tp_account_request_set_enabled ()

void                tp_account_request_set_enabled      (TpAccountRequest *self,
                                                         gboolean enabled);

Set the enabled property of the account on creation to enabled. Use the "enabled" property to read the current enabled value.

self :

 a TpAccountRequest

enabled :

 TRUE if the account is to be enabled

Since 0.19.1

tp_account_request_set_connect_automatically ()

void                tp_account_request_set_connect_automatically
                                                        (TpAccountRequest *self,
                                                         gboolean connect_automatically);

Set the connect automatically property of the account on creation to connect_automatically so that the account is brought online to the automatic presence. Use the "connect-automatically" property to read the current connect automatically value.

self :

 a TpAccountRequest

connect_automatically :

 TRUE if the account is to connect automatically

Since 0.19.1

tp_account_request_add_supersedes ()

void                tp_account_request_add_supersedes   (TpAccountRequest *self,
                                                         const gchar *superseded_path);

Add an account object path to the list of superseded accounts which this new account will supersede. Use the "supersedes" property to read the current list of superseded accounts.

self :

 a TpAccountRequest

superseded_path :

 an account object path to add to the supersedes list

Since 0.19.1

tp_account_request_set_avatar ()

void                tp_account_request_set_avatar       (TpAccountRequest *self,
                                                         const guchar *avatar,
                                                         gsize len,
                                                         const gchar *mime_type);

Set the avatar of the account self to avatar. Use the "avatar" and "avatar-mime-type" properties to read the current avatar.

self :

 a TpAccountRequest

avatar :

 a new avatar to set; can be NULL only if len equals 0. [allow-none][array length=len]

len :

 the length of the new avatar

mime_type :

 the MIME type of the new avatar; can be NULL only if len equals 0. [allow-none]

Since 0.19.1

tp_account_request_set_service ()

void                tp_account_request_set_service      (TpAccountRequest *self,
                                                         const gchar *service);

Set the service property of the account to service. Use the "service" property to read the current value.

self :

 a TpAccountRequest

service :

 the service name for

Since 0.19.1

tp_account_request_set_storage_provider ()

void                tp_account_request_set_storage_provider
                                                        (TpAccountRequest *self,
                                                         const gchar *provider);

Set the account storage to use when creating the account. Use the "storage-provider" property to read the current value.

self :

 a TpAccountRequest

provider :

 the name of an account storage implementation

Since 0.19.4

tp_account_request_set_parameter ()

void                tp_account_request_set_parameter    (TpAccountRequest *self,
                                                         const gchar *key,
                                                         GVariant *value);

Set an account parameter, key, to value. Use the "parameters" property to read the current list of set parameters.

Parameters can be unset using tp_account_request_unset_parameter().

self :

 a TpAccountRequest

key :

 the parameter key

value :

 a variant containing the parameter value. [transfer none]

Since 0.19.1

tp_account_request_set_parameter_string ()

void                tp_account_request_set_parameter_string
                                                        (TpAccountRequest *self,
                                                         const gchar *key,
                                                         const gchar *value);

Convenience function to set an account parameter string value. See tp_account_request_set_parameter() for more details.

self :

 a TpAccountRequest

key :

 the parameter key

value :

 the parameter value

Since 0.19.1

tp_account_request_unset_parameter ()

void                tp_account_request_unset_parameter  (TpAccountRequest *self,
                                                         const gchar *key);

Unset the account parameter key which has previously been set using tp_account_request_set_parameter() or another convenience function.

self :

 a TpAccountRequest

key :

 the parameter key

Since 0.19.1

tp_account_request_create_account_async ()

void                tp_account_request_create_account_async
                                                        (TpAccountRequest *self,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Start an asynchronous operation to create the account self on the account manager.

callback will only be called when the newly created TpAccount has the TP_ACCOUNT_FEATURE_CORE feature ready on it, so when calling tp_account_request_create_account_finish(), one can guarantee this feature.

self :

 a TpAccountRequest

callback :

 a function to call when the account has been created

user_data :

 user data to callback

Since 0.19.1

tp_account_request_create_account_finish ()

TpAccount *         tp_account_request_create_account_finish
                                                        (TpAccountRequest *self,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes an asynchronous account creation operation and returns a new ref to a TpAccount object. The returned account will have the features listed in tp_simple_client_factory_dup_account_features() (with the proxy factory from "account-manager") prepared on it.

self :

 a TpAccountRequest

result :

 a GAsyncResult

error :

 something

Returns :

 a new ref to a TpAccount, or NULL. [transfer full]

Since 0.19.1

Property Details

The "account-manager" property

  "account-manager"          TpAccountManager*     : Read / Write / Construct Only

The TpAccountManager to create the account on.

Since 0.19.1

The "automatic-presence-type" property

  "automatic-presence-type"  guint                 : Read

The account's automatic presence type (a TpConnectionPresenceType). To change this property use tp_account_request_set_automatic_presence().

When the account is put online automatically, for instance to make a channel request or because network connectivity becomes available, the automatic presence type, status and message will be copied to their "requested" counterparts.

Allowed values: <= 9

Default value: 0

Since 0.19.1

The "automatic-status" property

  "automatic-status"         gchar*                : Read

The string status name to use in conjunction with the "automatic-presence-type". To change this property use tp_account_request_set_automatic_presence().

Default value: NULL

Since 0.19.1

The "automatic-status-message" property

  "automatic-status-message" gchar*                : Read

The user-defined message to use in conjunction with the "automatic-presence-type". To change this property use tp_account_request_set_automatic_presence().

Default value: NULL

Since 0.19.1

The "avatar" property

  "avatar"                   GArray*               : Read

The avatar set on the account. The avatar's mime type can be read in the "avatar-mime-type" property. To change this property, use tp_account_request_set_avatar().

Since 0.19.1

The "avatar-mime-type" property

  "avatar-mime-type"         gchar*                : Read

The mime type of the "avatar" property. To change this property, use tp_account_request_set_avatar().

Default value: NULL

Since 0.19.1

The "connect-automatically" property

  "connect-automatically"    gboolean              : Read

Whether the account should connect automatically or not. To change this property, use tp_account_request_set_connect_automatically().

Default value: FALSE

Since 0.19.1

The "connection-manager" property

  "connection-manager"       gchar*                : Read / Write / Construct Only

The account's connection manager name.

Default value: NULL

Since 0.19.1

The "display-name" property

  "display-name"             gchar*                : Read / Write / Construct Only

The account's display name. To change this property use tp_account_request_set_display_name().

Default value: NULL

Since 0.19.1

The "enabled" property

  "enabled"                  gboolean              : Read

Whether the account is enabled or not. To change this property use tp_account_request_set_enabled().

Default value: FALSE

Since 0.19.1

The "icon-name" property

  "icon-name"                gchar*                : Read

The account's icon name. To change this propery, use tp_account_request_set_icon_name().

Default value: NULL

Since 0.19.1

The "nickname" property

  "nickname"                 gchar*                : Read

The account's nickname. To change this property use tp_account_request_set_nickname().

Default value: NULL

Since 0.19.1

The "parameters" property

  "parameters"               GVariant*             : Read

The account's connection parameters. To add a parameter, use tp_account_request_set_parameter() or another convience function.

Allowed values: GVariant<a{sv}>

Default value: NULL

Since 0.19.1

The "properties" property

  "properties"               GVariant*             : Read

The account's properties.

Allowed values: GVariant<a{sv}>

Default value: NULL

Since 0.19.1

The "protocol" property

  "protocol"                 gchar*                : Read / Write / Construct Only

The account's machine-readable protocol name, such as "jabber", "msn" or "local-xmpp". Recommended names for most protocols can be found in the Telepathy D-Bus Interface Specification.

Default value: NULL

Since 0.19.1

The "requested-presence-type" property

  "requested-presence-type"  guint                 : Read

The account's requested presence type (a TpConnectionPresenceType). To change this property use tp_account_request_set_requested_presence().

Allowed values: <= 9

Default value: 0

Since 0.19.1

The "requested-status" property

  "requested-status"         gchar*                : Read

The requested Status string of the account. To change this property use tp_account_request_set_requested_presence().

Default value: NULL

Since 0.19.1

The "requested-status-message" property

  "requested-status-message" gchar*                : Read

The requested status message message of the account. To change this property use tp_account_request_set_requested_presence().

Default value: NULL

Since 0.19.1

The "service" property

  "service"                  gchar*                : Read

A string describing the service of the account, which must consist only of ASCII letters, numbers and hyphen/minus signs, and start with a letter (matching the requirements for Protocol). To change this property, use tp_account_request_set_service().

Default value: NULL

Since 0.19.1

The "storage-provider" property

  "storage-provider"         gchar*                : Read

The account's storage provider. To change this property use tp_account_request_set_storage_provider().

Default value: NULL

Since 0.19.4

The "supersedes" property

  "supersedes"               GStrv                 : Read

The object paths of previously-active accounts superseded by this one. For instance, this can be used in a logger to read old logs for an account that has been migrated from one connection manager to another.

To add to this property use tp_account_request_add_supersedes().

Since 0.19.1

See Also

TpAccountManager
Generated by GTK-Doc V1.19