McAccount

## McAccount McAccount — MC's representation of an account. |

## Synopsis

                        McAccount;
    enum                McAccountSettingState;
    McAccount*          mc_account_lookup                   (const gchar *unique_name);
    McAccount*          mc_account_lookup_with_profile      (McProfile *profile,
                                                             const gchar *account);
    McAccount*          mc_account_lookup_with_vcard_field  (const gchar *vcard_field,
                                                             const gchar *account);
    void                mc_account_free                     (McAccount *account);
    void                mc_account_clear_cache              (void);
    McAccount*          mc_account_create                   (McProfile *profile);
    gboolean            mc_account_delete                   (McAccount *account);
    GList*              mc_accounts_list                    (void);
    GList*              mc_accounts_list_by_enabled         (gboolean enabled);
    GList*              mc_accounts_list_by_profile         (McProfile *profile);
    GList*              mc_accounts_list_by_vcard_field     (const gchar *vcard_field);
    void                mc_accounts_list_free               (GList *list);
    gboolean            (*McAccountFilter)                  (McAccount *account,
                                                             gpointer data);
    GList*              mc_accounts_filter                  (GList *accounts,
                                                             McAccountFilter filter,
                                                             gpointer data);
    const gchar*        mc_account_get_unique_name          (McAccount *account);
    McProfile*          mc_account_get_profile              (McAccount *account);
    const gchar*        mc_account_get_display_name         (McAccount *account);
    gboolean            mc_account_set_display_name         (McAccount *account,
                                                             const gchar *name);
    const gchar*        mc_account_get_normalized_name      (McAccount *account);
    gboolean            mc_account_set_normalized_name      (McAccount *account,
                                                             const gchar *name);
    gboolean            mc_account_is_enabled               (McAccount *account);
    gboolean            mc_account_set_enabled              (McAccount *account,
                                                             const gboolean enabled);
    McAccountSettingState mc_account_get_param_boolean      (McAccount *account,
                                                             const gchar *name,
                                                             gboolean *value);
    McAccountSettingState mc_account_get_param_int          (McAccount *account,
                                                             const gchar *name,
                                                             gint *value);
    McAccountSettingState mc_account_get_param_string       (McAccount *account,
                                                             const gchar *name,
                                                             gchar **value);
    GHashTable*         mc_account_get_params               (McAccount *account);
    gboolean            mc_account_set_param_boolean        (McAccount *account,
                                                             const gchar *name,
                                                             gboolean value);
    gboolean            mc_account_set_param_int            (McAccount *account,
                                                             const gchar *name,
                                                             gint value);
    gboolean            mc_account_set_param_string         (McAccount *account,
                                                             const gchar *name,
                                                             const gchar *value);
    gboolean            mc_account_unset_param              (McAccount *account,
                                                             const gchar *name);
    gboolean            mc_account_is_complete              (McAccount *account);
    gboolean            mc_account_set_avatar               (McAccount *account,
                                                             const gchar *filename,
                                                             const gchar *mime_type);
    gboolean            mc_account_get_avatar               (McAccount *account,
                                                             gchar **filename,
                                                             gchar **mime_type,
                                                             gchar **token);
    gboolean            mc_account_set_alias                (McAccount *account,
                                                             const gchar *alias);
    gchar*              mc_account_get_alias                (McAccount *account);

## Object Hierarchy

      GObject
       +----McAccount

## Description

A McAccount stores all the informations required to use an account (login, password, McProfile, etc.).

The McAccount API allows clients to manage accounts.

## Details

### McAccount

    typedef struct _McAccount McAccount;

### enum McAccountSettingState

    typedef enum
    {
        MC_ACCOUNT_SETTING_ABSENT = 0,
        MC_ACCOUNT_SETTING_FROM_ACCOUNT,
        MC_ACCOUNT_SETTING_FROM_PROFILE,
        MC_ACCOUNT_SETTING_FROM_PROXY,
    } McAccountSettingState;

### mc_account_lookup ()

    McAccount*          mc_account_lookup                   (const gchar *unique_name);

Look-up an account from its unique name. The reference count of the returned account is incremented.

`unique_name` : | The unique name of the account.
Returns : | The requested McAccount, or NULL if not found.

### mc_account_lookup_with_profile ()

    McAccount*          mc_account_lookup_with_profile      (McProfile *profile,
                                                             const gchar *account);

Look-up an account from its name in the given McProfile. The reference count of the returned account is incremented.

`profile` : | A McProfile.
`account` : | The name of the account.
Returns : | The requested McAccount, or NULL if not found.

### mc_account_lookup_with_vcard_field ()

    McAccount*          mc_account_lookup_with_vcard_field  (const gchar *vcard_field,
                                                             const gchar *account);

Look-up an account from its name in the given VCard field. The reference count of the returned account is incremented.

`vcard_field` : | The VCard field.
`account` : | The name of the account.
Returns : | The requested McAccount, or NULL if not found.

### mc_account_free ()

    void                mc_account_free                     (McAccount *account);

Free an account. DEPRECATED, use `g_object_unref()` instead.

`account` : | The McAccount.

### mc_account_clear_cache ()

    void                mc_account_clear_cache              (void);

### mc_account_create ()

    McAccount*          mc_account_create                   (McProfile *profile);

Create a new account of the given McProfile.

`profile` : | A McProfile.
Returns : | the newly created McAccount.

### mc_account_delete ()

    gboolean            mc_account_delete                   (McAccount *account);

Delete the given account from the accounts configuration. The object itself remains valid and must be free separately.

`account` : | The McAccount.
Returns : | `TRUE` if the account was deleted, `FALSE` otherwise.

### mc_accounts_list ()

    GList*              mc_accounts_list                    (void);

Lists all configured accounts.

Returns : | a GList of all accounts. Must be freed with mc_accounts_list_free.

### mc_accounts_list_by_enabled ()

    GList*              mc_accounts_list_by_enabled         (gboolean enabled);

Lists all enabled/disabled accounts.

`enabled` : | a boolean to select if enabled accounts should be returned.
Returns : | a GList of all the enabled accounts. Must be freed with mc_accounts_list_free.

### mc_accounts_list_by_profile ()

    GList*              mc_accounts_list_by_profile         (McProfile *profile);

Lists all accounts of a McProfile.

`profile` : | a McProfile.
Returns : | a GList of the accounts. Must be freed with mc_accounts_list_free.

### mc_accounts_list_by_vcard_field ()

    GList*              mc_accounts_list_by_vcard_field     (const gchar *vcard_field);

Lists all accounts of a VCard field.

`vcard_field` : | the VCard field.
Returns : | a GList of the accounts. Must be freed with mc_accounts_list_free.

### mc_accounts_list_free ()

    void                mc_accounts_list_free               (GList *list);

Frees the lists of accounts returned by the mc_accounts_list* family of functions.

`list` : | A GList of McAccount.

### McAccountFilter ()

    gboolean            (*McAccountFilter)                  (McAccount *account,
                                                             gpointer data);

This function is called for every McAccount in the list, and determines which elements have to be removed from the list.

`account` : | The McAccount.
`data` : | Pointer to user data.
Returns : | `TRUE` if the account must stay in the list, `FALSE` if is must be removed.

### mc_accounts_filter ()

    GList*              mc_accounts_filter                  (GList *accounts,
                                                             McAccountFilter filter,
                                                             gpointer data);

Filter a list of accounts according to whether a function returns TRUE, freeing the list and any accounts which are filtered out.

`accounts` : | a GList of McAccount.
`filter` : | a McAccountFilter function.
`data` : | user data to be passed to the filter function.
Returns : | a GList of the accounts. Must be freed with mc_accounts_list_free.

### mc_account_get_unique_name ()

    const gchar*        mc_account_get_unique_name          (McAccount *account);

Gets the unique name for the account.

`account` : | The McAccount.
Returns : | the unique name, or NULL.

### mc_account_get_profile ()

    McProfile*          mc_account_get_profile              (McAccount *account);

Get the McProfile this McAccount belongs to.

`account` : | The McAccount.
Returns : | the McProfile, or NULL.

### mc_account_get_display_name ()

    const gchar*        mc_account_get_display_name         (McAccount *account);

Gets the display name for the account.

`account` : | The McAccount.
Returns : | the display name, or NULL.

### mc_account_set_display_name ()

    gboolean            mc_account_set_display_name         (McAccount *account,
                                                             const gchar *name);

Sets the display name of the account. If `name` is NULL or an empty string, the display name is unset.

`account` : | The McAccount.
`name` : | The name to set.
Returns : | `TRUE`, or `FALSE` if some error occurs.

### mc_account_get_normalized_name ()

    const gchar*        mc_account_get_normalized_name      (McAccount *account);

Gets the normalized name for the account.

`account` : | The McAccount.
Returns : | the normalized name, or NULL.

### mc_account_set_normalized_name ()

    gboolean            mc_account_set_normalized_name      (McAccount *account,
                                                             const gchar *name);

Sets the normalized name of the account.

`account` : | The McAccount.
`name` : | The name to set.
Returns : | `TRUE`, or `FALSE` if some error occurs.

### mc_account_is_enabled ()

    gboolean            mc_account_is_enabled               (McAccount *account);

Checks if the account is enabled.

`account` : | The McAccount.
Returns : | `TRUE` if enabled, `FALSE` otherwise.

### mc_account_set_enabled ()

    gboolean            mc_account_set_enabled              (McAccount *account,
                                                             const gboolean enabled);

Enables or disables an account.

`account` : | The McAccount.
`enabled` : | whether the account must be enabled.
Returns : | `TRUE`, or `FALSE` if some error occurred.

### mc_account_get_param_boolean ()

    McAccountSettingState mc_account_get_param_boolean      (McAccount *account,
                                                             const gchar *name,
                                                             gboolean *value);

Gets a boolean parameter from the account settings.

`account` : | The McAccount.
`name` : | the parameter to retrieve.
`value` : | a pointer to the boolean variable.
Returns : | a McAccountSettingState.

### mc_account_get_param_int ()

    McAccountSettingState mc_account_get_param_int          (McAccount *account,
                                                             const gchar *name,
                                                             gint *value);

Gets a integer parameter from the account settings.

`account` : | The McAccount.
`name` : | the parameter to retrieve.
`value` : | a pointer to the integer variable.
Returns : | a McAccountSettingState.

### mc_account_get_param_string ()

    McAccountSettingState mc_account_get_param_string       (McAccount *account,
                                                             const gchar *name,
                                                             gchar **value);

Gets a string parameter from the account settings. The string will have to be freed with g_free.

`account` : | The McAccount.
`name` : | the parameter to retrieve.
`value` : | a pointer to the string variable which will receive the setting.
Returns : | a McAccountSettingState.

### mc_account_get_params ()

    GHashTable*         mc_account_get_params               (McAccount *account);

Gets all the parameters for this account. The returned hash table must be freed.

`account` : | The McAccount.
Returns : | a GHashTable containing all the account settings, or NULL.

### mc_account_set_param_boolean ()

    gboolean            mc_account_set_param_boolean        (McAccount *account,
                                                             const gchar *name,
                                                             gboolean value);

Sets a boolean parameter in the account settings.

`account` : | The McAccount.
`name` : | the parameter to set.
`value` : | a boolean value.
Returns : | `TRUE`, or `FALSE` if some error occurred.

### mc_account_set_param_int ()

    gboolean            mc_account_set_param_int            (McAccount *account,
                                                             const gchar *name,
                                                             gint value);

Sets a integer parameter in the account settings.

`account` : | The McAccount.
`name` : | the parameter to set.
`value` : | a integer value.
Returns : | `TRUE`, or `FALSE` if some error occurred.

### mc_account_set_param_string ()

    gboolean            mc_account_set_param_string         (McAccount *account,
                                                             const gchar *name,
                                                             const gchar *value);

Sets a string parameter in the account settings.

`account` : | The McAccount.
`name` : | the parameter to set.
`value` : | a string value.
Returns : | `TRUE`, or `FALSE` if some error occurred.

### mc_account_unset_param ()

    gboolean            mc_account_unset_param              (McAccount *account,
                                                             const gchar *name);

Unsets (removes) a parameter from the account settings.

`account` : | The McAccount.
`name` : | the parameter to unset.
Returns : | `TRUE`, or `FALSE` if some error occurred.

### mc_account_is_complete ()

    gboolean            mc_account_is_complete              (McAccount *account);

Checks if all the mandatory parameters declared by the protocol are present in this account's settings.

`account` : | The McAccount.
Returns : | a gboolean.

### mc_account_set_avatar ()

    gboolean            mc_account_set_avatar               (McAccount *account,
                                                             const gchar *filename,
                                                             const gchar *mime_type);

Set the avatar for this account. If `filename` is `NULL`, the avatar is cleared.

`account` : | The McAccount.
`filename` : | the path of the image file to be used as avatar.
`mime_type` : | the MIME type of the image.
Returns : | `TRUE`, or `FALSE` if some error occurred.

### mc_account_get_avatar ()

    gboolean            mc_account_get_avatar               (McAccount *account,
                                                             gchar **filename,
                                                             gchar **mime_type,
                                                             gchar **token);

Get the avatar for this account. Any of the parameters for the output can be NULL, if that information is not needed.

`account` : | The McAccount.
`filename` : | address of the variable to hold the path of the image file used as avatar.
`mime_type` : | address of the variable for the MIME type of the image.
`token` : | address of the variable for the Telepathy token of the avatar.
Returns : | `TRUE`, or `FALSE` if some error occurred.

### mc_account_set_alias ()

    gboolean            mc_account_set_alias                (McAccount *account,
                                                             const gchar *alias);

Sets the alias of the account.

`account` : | The McAccount.
`alias` : | The alias to set.
Returns : | `TRUE`, or `FALSE` if some error occurs.

### mc_account_get_alias ()

    gchar*              mc_account_get_alias                (McAccount *account);

Gets the alias for the account.

`account` : | The McAccount.
Returns : | the alias (must be freed with `g_free()`), or NULL.