## 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,
                                                             TpHandleType 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,
                                                             TpHandleType 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,
                                                             TpConnection *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;
        TpConnectionStatus status;
        McPresence presence;
        TpConnectionStatusReason 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;
        GHashTable *active_callbacks;
    };

### 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,
                                                             TpHandleType 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,
                                                             TpHandleType 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);

### Warning

`mission_control_get_connection` is deprecated and should not be used in newly-written code. do not use, will be removed soon. Use mission_control_get_tpconnection instead.

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);

### Warning

`mission_control_get_account_for_connection` is deprecated and should not be used in newly-written code. do not use, will be removed soon. Use mission_control_get_account_for_tpconnection instead.

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,
                                                             TpConnection *connection,
                                                             guint contact_id,
                                                             const gchar *token,
                                                             GError **error);

DEPRECATED. Do not use.

`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 : |

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