TpAccountRequest

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

Functions

Properties

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

Types and Values

Object Hierarchy

    GObject
    ╰── TpAccountRequest

Includes

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

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);
}

Functions

tp_account_request_new ()

TpAccountRequest *
tp_account_request_new (TpAccountManager *account_manager,
                        const gchar *cm_name,
                        const gchar *protocol_name,
                        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 cm_name , and protocol protocol_name .

Parameters

account_manager

the TpAccountManager to create the account on

 

cm_name

the name of the connection manager

 

protocol_name

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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_client_factory_dup_account_features() (with the proxy factory from “account-manager”) prepared on it.

Parameters

self

a TpAccountRequest

 

result

a GAsyncResult

 

error

something

 

Returns

a new ref to a TpAccount, or NULL.

[transfer full]

Since 0.19.1

Types and Values

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.

Property Details

The “account-manager” property

  “account-manager”          TpAccountManager *

The TpAccountManager to create the account on.

Flags: Read / Write / Construct Only

Since 0.19.1


The “automatic-presence-type” property

  “automatic-presence-type”  guint

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.

Flags: Read

Allowed values: <= 9

Default value: 0

Since 0.19.1


The “automatic-status” property

  “automatic-status”         gchar *

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

Flags: Read

Default value: NULL

Since 0.19.1


The “automatic-status-message” property

  “automatic-status-message” gchar *

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

Flags: Read

Default value: NULL

Since 0.19.1


The “avatar” property

  “avatar”                   GBytes *

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

Flags: Read


The “avatar-mime-type” property

  “avatar-mime-type”         gchar *

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

Flags: Read

Default value: NULL

Since 0.19.1


The “cm-name” property

  “cm-name”                  gchar *

The account's connection manager name.

Flags: Read / Write / Construct Only

Default value: NULL


The “connect-automatically” property

  “connect-automatically”    gboolean

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

Flags: Read

Default value: FALSE

Since 0.19.1


The “display-name” property

  “display-name”             gchar *

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

Flags: Read / Write / Construct Only

Default value: NULL

Since 0.19.1


The “enabled” property

  “enabled”                  gboolean

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

Flags: Read

Default value: FALSE

Since 0.19.1


The “icon-name” property

  “icon-name”                gchar *

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

Flags: Read

Default value: NULL

Since 0.19.1


The “nickname” property

  “nickname”                 gchar *

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

Flags: Read

Default value: NULL

Since 0.19.1


The “parameters” property

  “parameters”               GVariant *

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

Flags: Read

Allowed values: GVariant<a{sv}>

Default value: NULL

Since 0.19.1


The “properties” property

  “properties”               GVariant *

The account's properties.

Flags: Read

Allowed values: GVariant<a{sv}>

Default value: NULL

Since 0.19.1


The “protocol-name” property

  “protocol-name”            gchar *

The account's protocol name.

Flags: Read / Write / Construct Only

Default value: NULL


The “requested-presence-type” property

  “requested-presence-type”  guint

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

Flags: Read

Allowed values: <= 9

Default value: 0

Since 0.19.1


The “requested-status” property

  “requested-status”         gchar *

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

Flags: Read

Default value: NULL

Since 0.19.1


The “requested-status-message” property

  “requested-status-message” gchar *

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

Flags: Read

Default value: NULL

Since 0.19.1


The “service” property

  “service”                  gchar *

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

Flags: Read

Default value: NULL

Since 0.19.1


The “storage-provider” property

  “storage-provider”         gchar *

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

Flags: Read

Default value: NULL

Since 0.19.4


The “supersedes” property

  “supersedes”               GStrv

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

Flags: Read

Since 0.19.1

See Also

TpAccountManager