mission-control

## mission-control mission-control — mission-control service API |

## Synopsis

    typedef             MissionControl;
    typedef             MissionControlClass;
    enum                MCError;
    enum                McPresence;
    enum                McStatus;
                        McAccountStatus;
    void                (*McCallback)                       (MissionControl *mc,
                                                             GError *error,
                                                             gpointer user_data);
    void                (*McGetCurrentStatusCallback)       (MissionControl *mc,
                                                             McStatus status,
                                                             McPresence presence,
                                                             McPresence requested_presence,
                                                             McAccountStatus *accounts,
                                                             gsize n_accounts,
                                                             GError *error,
                                                             gpointer user_data);
    struct              missioncontrol;
    struct              missioncontrolclass;
    MissionControl*     mission_control_new                 (DBusGConnection *connection);
    void                mission_control_set_presence        (MissionControl *self,
                                                             McPresence presence,
                                                             const gchar *message,
                                                             McCallback callback,
                                                             gpointer user_data);
    McPresence          mission_control_get_presence        (MissionControl *self,
                                                             GError **error);
    McPresence          mission_control_get_presence_actual (MissionControl *self,
                                                             GError **error);
    guint               mission_control_request_channel     (MissionControl *self,
                                                             McAccount *account,
                                                             const gchar *type,
                                                             guint handle,
                                                             TelepathyHandleType handle_type,
                                                             McCallback callback,
                                                             gpointer user_data);
    guint               mission_control_request_channel_with_string_handle
                                                            (MissionControl *self,
                                                             McAccount *account,
                                                             const gchar *type,
                                                             const gchar *handle,
                                                             TelepathyHandleType handle_type,
                                                             McCallback callback,
                                                             gpointer user_data);
    gboolean            mission_control_cancel_channel_request
                                                            (MissionControl *self,
                                                             guint operation_id,
                                                             GError **error);
    void                mission_control_connect_all_with_default_presence
                                                            (MissionControl *self,
                                                             McCallback callback,
                                                             gpointer user_data);
    guint               mission_control_get_connection_status
                                                            (MissionControl *self,
                                                             McAccount *account,
                                                             GError **error);
    GSList*             mission_control_get_online_connections
                                                            (MissionControl *self,
                                                             GError **error);
    TpConn*             mission_control_get_connection      (MissionControl *self,
                                                             McAccount *account,
                                                             GError **error);
    McAccount*          mission_control_get_account_for_connection
                                                            (MissionControl *self,
                                                             TpConn *connection,
                                                             GError **error);
    gint                mission_control_get_used_channels_count
                                                            (MissionControl *self,
                                                             GQuark type,
                                                             GError **error);
    void                mission_control_get_current_status  (MissionControl *self,
                                                             McGetCurrentStatusCallback callback,
                                                             gpointer user_data);
    void                mission_control_free_account_statuses
                                                            (McAccountStatus *accounts);
    gboolean            mission_control_remote_avatar_changed
                                                            (MissionControl *self,
                                                             TpConn *connection,
                                                             guint contact_id,
                                                             const gchar *token,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----DBusGProxy
             +----MissionControl

## Signals

      "Error"                                          : Run Last / Has Details
      "ServiceEnded"                                   : Run Last

## Description

## Details

### MissionControl

    typedef struct _missioncontrol MissionControl;

### MissionControlClass

    typedef struct _missioncontrolclass MissionControlClass;

### enum MCError

    typedef enum {
        MC_DISCONNECTED_ERROR,
        MC_INVALID_HANDLE_ERROR,
        MC_NO_MATCHING_CONNECTION_ERROR,
        MC_INVALID_ACCOUNT_ERROR,
        MC_PRESENCE_FAILURE_ERROR,
        MC_NO_ACCOUNTS_ERROR,
        MC_NETWORK_ERROR,
        MC_CONTACT_DOES_NOT_SUPPORT_VOICE_ERROR,
        MC_LOWMEM_ERROR,
        MC_CHANNEL_REQUEST_GENERIC_ERROR,
        MC_CHANNEL_BANNED_ERROR,
        MC_CHANNEL_FULL_ERROR,
        MC_CHANNEL_INVITE_ONLY_ERROR,
        MC_LAST_ERROR /*< skip >*/
    } MCError;

### enum McPresence

    typedef enum {
        MC_PRESENCE_UNSET,
        MC_PRESENCE_OFFLINE,
        MC_PRESENCE_AVAILABLE,
        MC_PRESENCE_AWAY,
        MC_PRESENCE_EXTENDED_AWAY,
        MC_PRESENCE_HIDDEN,
        MC_PRESENCE_DO_NOT_DISTURB,
        LAST_MC_PRESENCE /*< skip >*/
    } McPresence;

### enum McStatus

    typedef enum {
        MC_STATUS_DISCONNECTED,
        MC_STATUS_CONNECTING,
        MC_STATUS_CONNECTED,
    } McStatus;

### McAccountStatus

    typedef struct {
        gchar *unique_name;
        TelepathyConnectionStatus status;
        McPresence presence;
        TelepathyConnectionStatusReason reason;
    } McAccountStatus;

### McCallback ()

    void                (*McCallback)                       (MissionControl *mc,
                                                             GError *error,
                                                             gpointer user_data);

Callback used for reporting errors from various MissionControl calls.

`mc` : | the MissionControl object.
`error` : | if set, some error occurred. Must be freed.
`user_data` : | user data specified when making the call request.

### McGetCurrentStatusCallback ()

    void                (*McGetCurrentStatusCallback)       (MissionControl *mc,
                                                             McStatus status,
                                                             McPresence presence,
                                                             McPresence requested_presence,
                                                             McAccountStatus *accounts,
                                                             gsize n_accounts,
                                                             GError *error,
                                                             gpointer user_data);

This callback is called in response to the mission_control_get_current_status call, and carries in its parameters the information on MissionControl status.

`mc` : | the MissionControl object.
`status` : | global connection status.
`presence` : | global presence.
`requested_presence` : | global requested presence.
`accounts` : | array of McAccountStatus structs which hold information about the status (connection and presence) of all enabled accounts. The callback is responsible to free this array by calling mission_control_free_account_statuses.
`n_accounts` : | number of accounts in the `accounts` array.
`error` : | if this is not `NULL`, then some error occurred and all the status information is invalid. In that case, the callback has to free `error`.
`user_data` : | the user data specified when calling mission_control_get_current_status.

### struct missioncontrol

    struct missioncontrol {
        DBusGProxy parent;

        gboolean first_run;
    };

### struct missioncontrolclass

    struct missioncontrolclass {
        DBusGProxyClass parent_class;
    };

### mission_control_new ()

    MissionControl*     mission_control_new                 (DBusGConnection *connection);

Creates a new Mission Control client library object.

`connection` : | The D-BUS connection for this object
Returns : | A new mc (Mission Control) library object, or NULL if unsuccesful

### mission_control_set_presence ()

    void                mission_control_set_presence        (MissionControl *self,
                                                             McPresence presence,
                                                             const gchar *message,
                                                             McCallback callback,
                                                             gpointer user_data);

Sets presence for the accounts.

`self` : | The MissionControl object.
`presence` : | Integer specifying the presence status code
`message` : | Optional presence associated message
`callback` : | a McCallback function to be notified about any errors
`user_data` : | data to be passed to the `callback` function

### mission_control_get_presence ()

    McPresence          mission_control_get_presence        (MissionControl *self,
                                                             GError **error);

Gets the currently requested presence status.

`self` : | The MissionControl object.
`error` : | address where an error can be returned, or NULL.
Returns : | The currently requested presence status

### mission_control_get_presence_actual ()

    McPresence          mission_control_get_presence_actual (MissionControl *self,
                                                             GError **error);

Gets the actual presence status.

`self` : | The MissionControl object.
`error` : | address where an error can be returned, or NULL.
Returns : | The actual presence status

### mission_control_request_channel ()

    guint               mission_control_request_channel     (MissionControl *self,
                                                             McAccount *account,
                                                             const gchar *type,
                                                             guint handle,
                                                             TelepathyHandleType handle_type,
                                                             McCallback callback,
                                                             gpointer user_data);

Requests creation of a new channel, or join to an existing channel.

`self` : | The MissionControl object.
`account` : | The account which will join a new channel or request joining to an existing channel
`type` : | a D-Bus interface name representing base channel type
`handle` : | The handle we want to initiate the communication with
`handle_type` : | The type of the handle we are initiating the communication with. See TelepathyHandleType
`callback` : | a McCallback function to be notified about any errors
`user_data` : | data to be passed to the `callback` function
Returns : | An operation ID which can be used to cancel the request using mission_control_cancel_channel_request.

### mission_control_request_channel_with_string_handle ()

    guint               mission_control_request_channel_with_string_handle
                                                            (MissionControl *self,
                                                             McAccount *account,
                                                             const gchar *type,
                                                             const gchar *handle,
                                                             TelepathyHandleType handle_type,
                                                             McCallback callback,
                                                             gpointer user_data);

Requests creation of a new channel, or join to an existing channel. Differs from the plain mission_control_request_channel by taking handles as strings, which will be resolved to integers by MC.

`self` : | The MissionControl object.
`account` : | The account which will join a new channel or request joining to an existing channel
`type` : | a D-Bus interface name representing base channel type
`handle` : | The handle we want to initiate the communication with
`handle_type` : | The type of the handle we are initiating the communication with. See TelepathyHandleType
`callback` : | a McCallback function to be notified about any errors
`user_data` : | data to be passed to the `callback` function
Returns : | An operation ID which can be used to cancel the request using mission_control_cancel_channel_request.

### mission_control_cancel_channel_request ()

    gboolean            mission_control_cancel_channel_request
                                                            (MissionControl *self,
                                                             guint operation_id,
                                                             GError **error);

Cancel a channel request; a process can only cancel the requests that were originated by itself.

`self` : | The MissionControl object.
`operation_id` : | the operation id of the request to cancel, as returned by mission_control_request_channel_with_string_handle.
`error` : | address where an error can be returned, or NULL.
Returns : | `TRUE` on success, `FALSE` otherwise.

### mission_control_connect_all_with_default_presence ()

    void                mission_control_connect_all_with_default_presence
                                                            (MissionControl *self,
                                                             McCallback callback,
                                                             gpointer user_data);

Connect all accounts using default presence, or HIDDEN if default presence is OFFLINE. If accounts are already connected do nothing.

`self` : | The MissionControl object.
`callback` : | a McCallback function to be notified about any errors
`user_data` : | data to be passed to the `callback` function

### mission_control_get_connection_status ()

    guint               mission_control_get_connection_status
                                                            (MissionControl *self,
                                                             McAccount *account,
                                                             GError **error);

Request a status code describing the status of the connection that the provided account currently uses.

`self` : | The MissionControl object.
`account` : | The account whose connection status is inspected
`error` : | address where an error can be returned, or NULL.
Returns : | A status code describing the status of the specified connection eg. CONNECTED = 0, CONNECTING = 1, DISCONNECTED = 2

### mission_control_get_online_connections ()

    GSList*             mission_control_get_online_connections
                                                            (MissionControl *self,
                                                             GError **error);

Request an array of the accounts that have an active connection.

`self` : | The MissionControl object.
`error` : | address where an error can be returned, or NULL.
Returns : | A list of McAccounts corresponding to the online connections

### mission_control_get_connection ()

    TpConn*             mission_control_get_connection      (MissionControl *self,
                                                             McAccount *account,
                                                             GError **error);

Gets a connection object for the specified account name.

`self` : | The MissionControl object.
`account` : | The account the connection is created for.
`error` : | address where an error can be returned, or NULL.
Returns : | An existing TpConn object, NULL if the account is not connected

### mission_control_get_account_for_connection ()

    McAccount*          mission_control_get_account_for_connection
                                                            (MissionControl *self,
                                                             TpConn *connection,
                                                             GError **error);

Gets the account corresponding to the connection object. Note that as a result the caller owns a reference to the account object.

`self` : | The MissionControl object.
`connection` : | connection object to get the account for
`error` : | address where an error can be returned, or NULL.
Returns : | The matching account object, NULL on error

### mission_control_get_used_channels_count ()

    gint                mission_control_get_used_channels_count
                                                            (MissionControl *self,
                                                             GQuark type,
                                                             GError **error);

Counts the number of active channels of specified type.

`self` : | The MissionControl object.
`type` : | Type of the counted channels as a GQuark (see the defines in tp-chan.h)
`error` : | address where an error can be returned, or NULL.
Returns : | The number of channels currently in use (negative if the query fails)

### mission_control_get_current_status ()

    void                mission_control_get_current_status  (MissionControl *self,
                                                             McGetCurrentStatusCallback callback,
                                                             gpointer user_data);

Queries the status of all the enabled accounts, as well as the global presence and status. This information will be returned in the registered `callback`, which will be resposible for freeing all the dynamic data.

`self` : | The MissionControl object.
`callback` : | a McGetCurrentStatusCallback function which will be called with the requested information.
`user_data` : | data to be passed to the `callback` function

### mission_control_free_account_statuses ()

    void                mission_control_free_account_statuses
                                                            (McAccountStatus *accounts);

Frees the `accounts` array.

`accounts` : | The array of McAccountStatus.

### mission_control_remote_avatar_changed ()

    gboolean            mission_control_remote_avatar_changed
                                                            (MissionControl *self,
                                                             TpConn *connection,
                                                             guint contact_id,
                                                             const gchar *token,
                                                             GError **error);

This function is responsible for taking actions in response to the own avatar being received from the server. Depending on the situation, this function can update the local avatar in our McAccount.

`self` : | the MissionControl object.
`connection` : | connection object which received the avatar update.
`contact_id` : | the Telepathy self contact handle.
`token` : | the Telepathy token for the new avatar.
`error` : | address where an error can be returned, or NULL.
Returns : | `TRUE` if success, `FALSE` if some error occurred.

## Signal Details

### The "Error" signal

    void                user_function                      (MissionControl *self,
                                                            guint           operation_id,
                                                            guint           error_code,
                                                            gpointer        user_data)         : Run Last / Has Details

This signal is emitted when an error is raised from the mission-control server. This is not raised in response to some API call failing (they already provide a way to report errors), but rather for informing the client of some unexpected event, such as a channel handler failing.

`self` : | The MissionControl object.
`operation_id` : | The unique ID of the operation which caused the error. When this signal is emitted to report a failure in handling a channel, this parameter holds the same `operation_id` returned by the channel request function call.
`error_code` : | The MCError code describing the error.
`user_data` : | user data set when the signal handler was connected.

### The "ServiceEnded" signal

    void                user_function                      (MissionControl *self,
                                                            gpointer        user_data)      : Run Last

This signal is emitted when a mission-control server process has exited.

`self` : | The MissionControl object
`user_data` : | user data set when the signal handler was connected.