TpAccountRequest

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