TpAccountRequest: telepathy-glib API Reference Manual

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

## Functions

TpAccountRequest * | tp_account_request_new ()
TpAccountRequest * | tp_account_request_new_from_protocol ()
void | tp_account_request_set_display_name ()
void | tp_account_request_set_icon_name ()
void | tp_account_request_set_nickname ()
void | tp_account_request_set_requested_presence ()
void | tp_account_request_set_automatic_presence ()
void | tp_account_request_set_enabled ()
void | tp_account_request_set_connect_automatically ()
void | tp_account_request_add_supersedes ()
void | tp_account_request_set_avatar ()
void | tp_account_request_set_service ()
void | tp_account_request_set_storage_provider ()
void | tp_account_request_set_parameter ()
void | tp_account_request_set_parameter_string ()
void | tp_account_request_unset_parameter ()
void | tp_account_request_create_account_async ()
TpAccount * | tp_account_request_create_account_finish ()

## Properties

TpAccountManager * | account-manager | Read / Write / Construct Only
guint | automatic-presence-type | Read
gchar * | automatic-status | Read
gchar * | automatic-status-message | Read
GArray * | avatar | Read
gchar * | avatar-mime-type | Read
gboolean | connect-automatically | Read
gchar * | connection-manager | Read / Write / Construct Only
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 | 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

struct | TpAccountRequest
struct | TpAccountRequestClass

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

#### Parameters

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.

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

[skip]

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

Owner: TpAccountRequest

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.

Owner: TpAccountRequest

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

Owner: TpAccountRequest

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

Owner: TpAccountRequest

Flags: Read

Default value: NULL

Since: 0.19.1

### The `“avatar”` property

      “avatar”                   GArray *

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

Owner: TpAccountRequest

Flags: Read

Since: 0.19.1

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

Owner: TpAccountRequest

Flags: Read

Default value: NULL

Since: 0.19.1

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

Owner: TpAccountRequest

Flags: Read

Default value: FALSE

Since: 0.19.1

### The `“connection-manager”` property

      “connection-manager”       gchar *

The account's connection manager name.

Owner: TpAccountRequest

Flags: Read / Write / Construct Only

Default value: NULL

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

Owner: TpAccountRequest

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

Owner: TpAccountRequest

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

Owner: TpAccountRequest

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

Owner: TpAccountRequest

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.

Owner: TpAccountRequest

Flags: Read

Allowed values: GVariant<a{sv}>

Default value: NULL

Since: 0.19.1

### The `“properties”` property

      “properties”               GVariant *

The account's properties.

Owner: TpAccountRequest

Flags: Read

Allowed values: GVariant<a{sv}>

Default value: NULL

Since: 0.19.1

### The `“protocol”` property

      “protocol”                 gchar *

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.

Owner: TpAccountRequest

Flags: Read / Write / Construct Only

Default value: NULL

Since: 0.19.1

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

Owner: TpAccountRequest

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

Owner: TpAccountRequest

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

Owner: TpAccountRequest

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

Owner: TpAccountRequest

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

Owner: TpAccountRequest

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

Owner: TpAccountRequest

Flags: Read

Since: 0.19.1

## See Also

TpAccountManager