CallsAccount: Calls Reference Manual

## CallsAccount CallsAccount |

## Functions

void | calls_account_go_online ()
const char * | calls_account_get_address ()
CallsAccountState | calls_account_get_state ()
const char * | calls_account_state_to_string ()
const char * | calls_account_state_reason_to_string ()
void | calls_account_emit_message_for_state_change ()
gboolean | calls_account_state_is_for_ui ()
gboolean | calls_account_state_reason_is_for_ui ()

## Properties

CallsAccountState | account-state | Read
char * | address | Read

## Signals

void | account-state-changed | Run Last

## Types and Values

#define | CALLS_TYPE_ACCOUNT
enum | CallsAccountState
enum | CallsAccountStateReason
struct | CallsAccountInterface
| CallsAccount

## Object Hierarchy

        GEnum
        ├── CallsAccountState
        ╰── CallsAccountStateReason
        GInterface
        ╰── CallsAccount

## Prerequisites

CallsAccount requires CallsOrigin, CallsMessageSource and GObject.

## Description

## Functions

### calls_account_go_online ()

    void
    calls_account_go_online (CallsAccount *self,
                             gboolean online);

Connect or disconnect to a server.

#### Parameters

self | a CallsAccount |
online | `TRUE` to try to go online, `FALSE` to go offline |

### calls_account_get_address ()

    const char *
    calls_account_get_address (CallsAccount *self);

#### Parameters

self | A CallsAccount |

#### Returns

The address under which this account can be reached. For example: alice`example.org` for SIP and XMPP/Jingle or `alice` :example.org for Matrix

### calls_account_get_state ()

    CallsAccountState
    calls_account_get_state (CallsAccount *self);

#### Parameters

self | A CallsAccount |

#### Returns

The current CallsAccountState of this account

### calls_account_state_to_string ()

    const char *
    calls_account_state_to_string (CallsAccountState state);

#### Parameters

state | A CallsAccountState |

#### Returns

A human readable description of the account state.

[transfer none]

### calls_account_state_reason_to_string ()

    const char *
    calls_account_state_reason_to_string (CallsAccountStateReason reason);

#### Parameters

reason | A CallsAccountStateReason |

#### Returns

A human readable description for why an account state changed.

[transfer none]

### calls_account_emit_message_for_state_change ()

    void
    calls_account_emit_message_for_state_change
                                   (CallsAccount *account,
                                    CallsAccountState new_state,
                                    CallsAccountStateReason reason);

#### Parameters

account | A CallsAccount |
new_state | The new CallsAccountState |
reason | The CallsAccountStateReason for the state change |

#### Returns

Emits a human readable message for a state change

### calls_account_state_is_for_ui ()

    gboolean
    calls_account_state_is_for_ui (CallsAccountState state);

Helper function to decide which account states are important. Is used f.e. to decide if message should be shown to the user.

#### Parameters

state | a CallsAccountState |

#### Returns

`TRUE` if account state is considered important, `FALSE` otherwise

### calls_account_state_reason_is_for_ui ()

    gboolean
    calls_account_state_reason_is_for_ui (CallsAccountStateReason reason);

Helper function to decide which account states reasons are important. Is used f.e. to decide if message should be shown to the user.

#### Parameters

reason | a CallsAccountStateReason |

#### Returns

`TRUE` if account state reason is considered important, `FALSE` otherwise

## Types and Values

### CALLS_TYPE_ACCOUNT

    #define CALLS_TYPE_ACCOUNT (calls_account_get_type ())

### enum CallsAccountState

#### Members

CALLS_ACCOUNT_STATE_UNKNOWN | Default state for new accounts |
CALLS_ACCOUNT_STATE_INITIALIZING | Account is initializing |
CALLS_ACCOUNT_STATE_DEINITIALIZING | Account is being shutdown |
CALLS_ACCOUNT_STATE_CONNECTING | Connecting to server |
CALLS_ACCOUNT_STATE_ONLINE | Account is online |
CALLS_ACCOUNT_STATE_DISCONNECTING | Disconnecting from server |
CALLS_ACCOUNT_STATE_OFFLINE | Account is offline |
CALLS_ACCOUNT_STATE_ERROR | Account is in an error state |

### enum CallsAccountStateReason

#### Members

CALLS_ACCOUNT_STATE_REASON_UNKNOWN | Default unspecified reason |
CALLS_ACCOUNT_STATE_REASON_INITIALIZATION_STARTED | Initialization started |
CALLS_ACCOUNT_STATE_REASON_INITIALIZED | Initialization done |
CALLS_ACCOUNT_STATE_REASON_DEINITIALIZATION_STARTED | Deinitialization started |
CALLS_ACCOUNT_STATE_REASON_DEINITIALIZED | Deinitialization done |
CALLS_ACCOUNT_STATE_REASON_NO_CREDENTIALS | No credentials were set |
CALLS_ACCOUNT_STATE_REASON_CONNECT_STARTED | Starting to connect |
CALLS_ACCOUNT_STATE_REASON_CONNECTION_TIMEOUT | A connection has timed out |
CALLS_ACCOUNT_STATE_REASON_CONNECTION_DNS_ERROR | A domain name could not be resolved |
CALLS_ACCOUNT_STATE_REASON_AUTHENTICATION_FAILURE | Could not authenticate, possibly wrong credentials |
CALLS_ACCOUNT_STATE_REASON_CONNECTED | Connected successfully |
CALLS_ACCOUNT_STATE_REASON_DISCONNECT_STARTED |  |
CALLS_ACCOUNT_STATE_REASON_DISCONNECTED | Disconnected successfully |
CALLS_ACCOUNT_STATE_REASON_INTERNAL_ERROR | An internal error has occurred |

### struct CallsAccountInterface

    struct CallsAccountInterface {
      GTypeInterface parent_iface;

      void           (*go_online)                           (CallsAccount *self,
                                                             gboolean      online);
      const char    *(*get_address)                         (CallsAccount *self);
    };

### CallsAccount

    typedef struct _CallsAccount CallsAccount;

## Property Details

### The `“account-state”` property

      “account-state”            CallsAccountState

The state of the account.

Owner: CallsAccount

Flags: Read

Default value: CALLS_ACCOUNT_STATE_UNKNOWN

### The `“address”` property

      “address”                  char *

The address of this account.

Owner: CallsAccount

Flags: Read

Default value: NULL

## Signal Details

### The `“account-state-changed”` signal

    void
    user_function (CallsAccount           *self,
                   CallsAccountState       new_state,
                   CallsAccountState       old_state,
                   CallsAccountStateReason reason,
                   gpointer                user_data)

#### Parameters

self | The CallsAccount |
new_state | The new CALLS_ACCOUNT_STATE of the account |
old_state | The old CALLS_ACCOUNT_STATE of the account |
reason | The CALLS_ACCOUNT_STATE_REASON for the change |
user_data | user data set when the signal handler was connected. |

Flags: Run Last