OssoABookPresence

OssoABookPresence — Base interface for presence representation.

Synopsis

enum                OssoABookPresenceState;
                    OssoABookPresence;
                    OssoABookPresenceIface;
TpConnectionPresenceType osso_abook_presence_get_presence_type
                                                        (OssoABookPresence *presence);
const char*         osso_abook_presence_get_presence_status
                                                        (OssoABookPresence *presence);
const char*         osso_abook_presence_get_display_status
                                                        (OssoABookPresence *presence);
const char*         osso_abook_presence_get_presence_status_message
                                                        (OssoABookPresence *presence);
const char*         osso_abook_presence_get_location_string
                                                        (OssoABookPresence *presence);
const char*         osso_abook_presence_get_icon_name   (OssoABookPresence *presence);
const char*         osso_abook_presence_get_branded_icon_name
                                                        (OssoABookPresence *presence,
                                                         McProfile *profile);
OssoABookPresenceState osso_abook_presence_get_blocked  (OssoABookPresence *presence);
OssoABookPresenceState osso_abook_presence_get_published
                                                        (OssoABookPresence *presence);
OssoABookPresenceState osso_abook_presence_get_subscribed
                                                        (OssoABookPresence *presence);
unsigned            osso_abook_presence_get_handle      (OssoABookPresence *presence);
gboolean            osso_abook_presence_is_invalid      (OssoABookPresence *presence);
int                 osso_abook_presence_compare_for_display
                                                        (OssoABookPresence *a,
                                                         OssoABookPresence *b);
int                 osso_abook_presence_compare         (OssoABookPresence *a,
                                                         OssoABookPresence *b);

Object Hierarchy

  GInterface
   +----OssoABookPresence

Prerequisites

OssoABookPresence requires GObject.

Known Implementations

OssoABookPresence is implemented by OssoABookContact, OssoABookGconfContact, OssoABookSelfContact and OssoABookVoicemailContact.

Properties

  "presence-location-string" gchar*                : Read
  "presence-status"          gchar*                : Read
  "presence-status-message"  gchar*                : Read
  "presence-type"            guint                 : Read

Description

OssoABookPresence is an interface that represents the online presence.

Details

enum OssoABookPresenceState

typedef enum {
        OSSO_ABOOK_PRESENCE_STATE_YES,
        OSSO_ABOOK_PRESENCE_STATE_NO,
        OSSO_ABOOK_PRESENCE_STATE_LOCAL_PENDING,
        OSSO_ABOOK_PRESENCE_STATE_REMOTE_PENDING,
} OssoABookPresenceState;

The various possible states of presence information. A simple boolean flag is not sufficient for representing this information, since presence state can depend on manual feedback and actual network conditions.

OSSO_ABOOK_PRESENCE_STATE_YES the condition is true
OSSO_ABOOK_PRESENCE_STATE_NO the condition is false
OSSO_ABOOK_PRESENCE_STATE_LOCAL_PENDING the state is not resolved yet and pending on some local action, e.g. some confirmation
OSSO_ABOOK_PRESENCE_STATE_REMOTE_PENDING the state is not resolved yet and pending on some remote action, e.g. network latency

OssoABookPresence

typedef struct _OssoABookPresence OssoABookPresence;

Dummy type for the OssoABookPresence interface.


OssoABookPresenceIface

typedef struct {
        TpConnectionPresenceType (* get_presence_type)           (OssoABookPresence *presence);
        const char *             (* get_presence_status)         (OssoABookPresence *presence);
        const char *             (* get_presence_status_message) (OssoABookPresence *presence);
        const char *             (* get_location_string)         (OssoABookPresence *presence);

        OssoABookPresenceState   (* get_blocked)                 (OssoABookPresence *presence);
        OssoABookPresenceState   (* get_published)               (OssoABookPresence *presence);
        OssoABookPresenceState   (* get_subscribed)              (OssoABookPresence *presence);
        unsigned                 (* get_handle)                  (OssoABookPresence *presence);
        gboolean                 (* is_invalid)                  (OssoABookPresence *presence);
} OssoABookPresenceIface;

Virtual methods of the OssoABookPresence interface.

get_presence_type () virtual method for osso_abook_presence_get_presence_type()
get_presence_status () virtual method for osso_abook_presence_get_presence_status()
get_presence_status_message () virtual method for osso_abook_presence_get_presence_status_message()
get_location_string () virtual method for osso_abook_presence_get_location_string()
get_blocked () virtual method for osso_abook_presence_get_blocked()
get_published () virtual method for osso_abook_presence_get_published()
get_subscribed () virtual method for osso_abook_presence_get_subscribed()
get_handle () virtual method for osso_abook_presence_get_handle()
is_invalid () virtual method for osso_abook_presence_is_invalid()

osso_abook_presence_get_presence_type ()

TpConnectionPresenceType osso_abook_presence_get_presence_type
                                                        (OssoABookPresence *presence);

Retrieves the presence type of presence. Note that the "presence-type" property can be monitored by connecting to the GObject "notify" signal with "presence-type" as detail, i.e. "notify::presence-type".

presence : An OssoABookPresence
Returns : An TpConnectionPresenceType.

osso_abook_presence_get_presence_status ()

const char*         osso_abook_presence_get_presence_status
                                                        (OssoABookPresence *presence);

Retrieves the status of presence as a string. This string is not valid to use for display in a user interface. For that purpose, use osso_abook_presence_get_display_status(). The presence status is often called a "status identifier" in Telepathy terminology, and may be a string such as "brb". See the Telepathy SimplePresence specification for more information.

presence : An OssoABookPresence
Returns : The detailed presence status.

osso_abook_presence_get_display_status ()

const char*         osso_abook_presence_get_display_status
                                                        (OssoABookPresence *presence);

Gets a displayable string describing presence's status.

presence : An OssoABookPresence
Returns : a displayable string owned by presence.

osso_abook_presence_get_presence_status_message ()

const char*         osso_abook_presence_get_presence_status_message
                                                        (OssoABookPresence *presence);

Retrieves the message associated with the status of presence

presence : An OssoABookPresence
Returns : The status message currently associated with presence. This string is owned by libosso-abook and should not be freed.

osso_abook_presence_get_location_string ()

const char*         osso_abook_presence_get_location_string
                                                        (OssoABookPresence *presence);

Retrieves the location associated with the status of presence as a string.

presence : An OssoABookPresence
Returns : The location currently associated with presence as a string. This string is owned by libosso-abook and should not be freed.

osso_abook_presence_get_icon_name ()

const char*         osso_abook_presence_get_icon_name   (OssoABookPresence *presence);

Retrieves the icon name associated with the current status of presence. The icon name can be used to look up the appropriate icon to represent presence until the "presence-status" property changes.

presence : An OssoABookPresence
Returns : The icon name currently associated with presence. This string is owned by libosso-abook and should not be freed.

osso_abook_presence_get_branded_icon_name ()

const char*         osso_abook_presence_get_branded_icon_name
                                                        (OssoABookPresence *presence,
                                                         McProfile *profile);

Retrieves the protocol-brand-specific icon name associated with the current status of presence. The icon name can be used to look up the appropriate icon to represent presence until the "presence-status" property changes.

presence : An OssoABookPresence
Returns : The icon name currently associated with presence. This string is owned by this function, so it must not be freed.

osso_abook_presence_get_blocked ()

OssoABookPresenceState osso_abook_presence_get_blocked  (OssoABookPresence *presence);

Retrieves current blocking status of presence.

presence : An OssoABookPresence
Returns : A OssoABookPresenceState.

osso_abook_presence_get_published ()

OssoABookPresenceState osso_abook_presence_get_published
                                                        (OssoABookPresence *presence);

Retrieves current publication status of presence.

presence : An OssoABookPresence
Returns : A OssoABookPresenceState.

osso_abook_presence_get_subscribed ()

OssoABookPresenceState osso_abook_presence_get_subscribed
                                                        (OssoABookPresence *presence);

Retrieves current subscription status of presence.

presence : An OssoABookPresence
Returns : A OssoABookPresenceState.

osso_abook_presence_get_handle ()

unsigned            osso_abook_presence_get_handle      (OssoABookPresence *presence);

Retrieves the Telepathy connection handle associated with the presence.

presence : An OssoABookPresence
Returns : The connection handle associated with presence, or 0.

osso_abook_presence_is_invalid ()

gboolean            osso_abook_presence_is_invalid      (OssoABookPresence *presence);

Checks if this presence object is invalid. Note that a FALSE return value from this function does not necessarily mean that presence is valid; it may simply mean that we have not yet determined whether it is valid or not.

presence : An OssoABookPresence
Returns : TRUE if this presence object is invalid. FALSE if presence is valid or the validity has not been determined.

osso_abook_presence_compare_for_display ()

int                 osso_abook_presence_compare_for_display
                                                        (OssoABookPresence *a,
                                                         OssoABookPresence *b);

Compares the status of presence a to the status of presence b. See TpConnectionPresenceType for the weights assigned to different statuses.

This function differs from osso_abook_presence_compare() in giving different presence types the same weight if they have the same presence icon, although tp_connection_presence_type_cmp_availability() gives them different weight. For instance "unset", "unknown", "offline" and "error" are treated the same by this function.

a : an OssoABookPresence
b : an OssoABookPresence
Returns : < 0 if presence a is "more online" than presence b, 0 if they compare equal, > 0 if presence a is "less online" presence b. (Yes, this is the opposite of how most comparison functions work)

osso_abook_presence_compare ()

int                 osso_abook_presence_compare         (OssoABookPresence *a,
                                                         OssoABookPresence *b);

Compares the status of presence a to the status of presence b. See TpConnectionPresenceType for the weights assigned to different statuses.

a : an OssoABookPresence
b : an OssoABookPresence
Returns : < 0 if presence a is "more online" than presence b, 0 if they compare equal, > 0 if presence a is "less online" presence b. (Yes, this is the opposite of how most comparison functions work)

Property Details

The "presence-location-string" property

  "presence-location-string" gchar*                : Read

The location information for this presence as a string.

Default value: NULL


The "presence-status" property

  "presence-status"          gchar*                : Read

The presence status.

Default value: NULL


The "presence-status-message" property

  "presence-status-message"  gchar*                : Read

The presence status message.

Default value: NULL


The "presence-type" property

  "presence-type"            guint                 : Read

The presence type.

Default value: 0

See Also

OssoABookContactPresence, OssoABookPresence