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.

Return value:

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.

Return value:

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.