GalagoService

GalagoService — A messaging or VoIP service.

Synopsis




enum        GalagoServiceFlags;
            GalagoService;
#define     GALAGO_DBUS_SERVICE_INTERFACE
#define     GALAGO_SERVICE_ID_AIM
#define     GALAGO_SERVICE_ID_GADUGADU
#define     GALAGO_SERVICE_ID_GROUPWISE
#define     GALAGO_SERVICE_ID_ICQ
#define     GALAGO_SERVICE_ID_IRC
#define     GALAGO_SERVICE_ID_JABBER
#define     GALAGO_SERVICE_ID_MSN
#define     GALAGO_SERVICE_ID_NAPSTER
#define     GALAGO_SERVICE_ID_SILC
#define     GALAGO_SERVICE_ID_TREPIA
#define     GALAGO_SERVICE_ID_YAHOO
#define     GALAGO_SERVICE_ID_ZEPHYR
const char* galago_service_get_id           (const GalagoService *service);
const char* galago_service_get_name         (const GalagoService *service);
GalagoServiceFlags galago_service_get_flags (const GalagoService *service);
GalagoAccount* galago_service_create_account
                                            (GalagoService *service,
                                             GalagoPerson *person,
                                             const char *username);
GalagoAccount* galago_service_get_account   (const GalagoService *service,
                                             const char *username,
                                             gboolean query);
GalagoCallHandle galago_service_get_account_async
                                            (const GalagoService *service,
                                             const char *username,
                                             GalagoServiceAccountCb cb,
                                             gpointer user_data,
                                             GFreeFunc free_func);
GList*      galago_service_get_accounts     (const GalagoService *service,
                                             gboolean query);
char*       galago_service_normalize        (const GalagoService *service,
                                             const char *username);

Object Hierarchy


  GObject
   +----GalagoObject
         +----GalagoService

Properties


  "flags"                GalagoServiceFlags    : Read / Write / Construct Only
  "id"                   gchararray            : Read / Write / Construct Only
  "name"                 gchararray            : Read / Write / Construct Only

Signals


"account-added"
            void        user_function      (GalagoService *service,
                                            gpointer       account,
                                            gpointer       user_data)      : Run last / Action
"account-removed"
            void        user_function      (GalagoService *service,
                                            gpointer       account,
                                            gpointer       user_data)      : Run last / Action

Description

GalagoService represents a service of some kind, typically used for messaging or VoIP. It owns a list of GalagoAccounts, and contains rules determining how account usernames should be normalized and compared.

GalagoServices are created through galago_create_service().

By default, account usernames are converted to lowercase and all spaces are removed when normalizing them for comparison. GalagoServiceFlags can change this behavior.

Details

enum GalagoServiceFlags

typedef enum
{
	/* Preserve spaces during normalization */
	GALAGO_PRESERVE_SPACES = 1 << 0,

	/* Preserve case during normalization */
	GALAGO_PRESERVE_CASE   = 1 << 1,

	/* Strip a slash and everything after it during normalization. */
	GALAGO_STRIP_SLASH     = 1 << 2

} GalagoServiceFlags;

A list of flags specifying rules for the service. Currently this consists of flags dictating how account usernames should be normalized when comparing the usernames.

GALAGO_PRESERVE_SPACES Preserve spaces in the account usernames when normalizing.
GALAGO_PRESERVE_CASE Preserve casing in the account usernames when normalizing.
GALAGO_STRIP_SLASH Strip the first slash and everything after it in the account usernames when normalizing. This is used for services such as Jabber.

GalagoService

typedef struct _GalagoService GalagoService;

This is an opaque structure representing a service. This should not be used directly. Use the accessor functions below.

GALAGO_DBUS_SERVICE_INTERFACE

#define     GALAGO_DBUS_SERVICE_INTERFACE

The D-BUS interface that GalagoService maps to.

GALAGO_SERVICE_ID_AIM

#define     GALAGO_SERVICE_ID_AIM

AOL Instant Messenger.

GALAGO_SERVICE_ID_GADUGADU

#define     GALAGO_SERVICE_ID_GADUGADU

Gadu-Gadu.

GALAGO_SERVICE_ID_GROUPWISE

#define     GALAGO_SERVICE_ID_GROUPWISE

Novell GroupWise.

GALAGO_SERVICE_ID_ICQ

#define     GALAGO_SERVICE_ID_ICQ

ICQ.

GALAGO_SERVICE_ID_IRC

#define     GALAGO_SERVICE_ID_IRC

Internet Relay Chat.

GALAGO_SERVICE_ID_JABBER

#define     GALAGO_SERVICE_ID_JABBER

Jabber.

GALAGO_SERVICE_ID_MSN

#define     GALAGO_SERVICE_ID_MSN

MSN Messenger.

GALAGO_SERVICE_ID_NAPSTER

#define     GALAGO_SERVICE_ID_NAPSTER

Napster Chat.

GALAGO_SERVICE_ID_SILC

#define     GALAGO_SERVICE_ID_SILC

Secure Internet Live Conferencing.

GALAGO_SERVICE_ID_TREPIA

#define     GALAGO_SERVICE_ID_TREPIA

Trepia Instant Messenger.

GALAGO_SERVICE_ID_YAHOO

#define     GALAGO_SERVICE_ID_YAHOO

Yahoo! Messenger.

GALAGO_SERVICE_ID_ZEPHYR

#define     GALAGO_SERVICE_ID_ZEPHYR

Zephyr.

galago_service_get_id ()

const char* galago_service_get_id           (const GalagoService *service);

Returns a service's ID.

service : The service.
Returns : The service's ID.

galago_service_get_name ()

const char* galago_service_get_name         (const GalagoService *service);

Returns a service's name.

service : The service.
Returns : The service's name.

galago_service_get_flags ()

GalagoServiceFlags galago_service_get_flags (const GalagoService *service);

Returns a service's flags.

service : The service.
Returns : The flags.

galago_service_create_account ()

GalagoAccount* galago_service_create_account
                                            (GalagoService *service,
                                             GalagoPerson *person,
                                             const char *username);

Creates an account belonging to this service.

If the account already exists, the existing account will be returned.

service : The service.
person : The person the account belongs to.
username : The account username.
Returns : The account.

galago_service_get_account ()

GalagoAccount* galago_service_get_account   (const GalagoService *service,
                                             const char *username,
                                             gboolean query);

Returns the account with the specified username from a service.

service : The service.
username : The account's username.
query : TRUE if a remote query should be done if there is no local account found, or FALSE.
Returns : The account, if found, or NULL.

galago_service_get_account_async ()

GalagoCallHandle galago_service_get_account_async
                                            (const GalagoService *service,
                                             const char *username,
                                             GalagoServiceAccountCb cb,
                                             gpointer user_data,
                                             GFreeFunc free_func);

Asynchronously retrieves the account with the specified username from a service.

For example: 

 static void
 account_received_cb(GalagoService *service,
                     GalagoAccount *account,
                     gpointer user_data)
 {
 }
 
 static void
 get_bob_account(GalagoService *service)
 {
     GalagoCallHandle handle;
 
     handle = galago_service_get_account_async(service, "Bob",
                                               account_received_cb,
                                               NULL, NULL);
 }

service : The service.
username : The account's username.
cb : The callback function that will be passed the account.
user_data : Custom data to pass to the callback function.
free_func : Optional function to free user_data when the request completes.
Returns : A valid GalagoCallHandle on success. On error, this will return GALAGO_CALL_HANDLE_INVALID.

Since 0.5.2

galago_service_get_accounts ()

GList*      galago_service_get_accounts     (const GalagoService *service,
                                             gboolean query);

Returns a list of all accounts in the service.

This may emit an account-added signal for every object that returns. If your code connects to this signal and calls galago_service_get_accounts() as a result, you will want to add a lock so that you don't end up with unwanted side-effects.

service : The service.
query : TRUE if a remote query should be done if there is no local account found, or FALSE.
Returns : A list of all accounts in the service.

galago_service_normalize ()

char*       galago_service_normalize        (const GalagoService *service,
                                             const char *username);

Normalizes an account username based on the service's normalization flags.

service : The service.
username : The username to normalize.
Returns : The string. This must be freed.

Property Details

The "flags" property

  "flags"                GalagoServiceFlags    : Read / Write / Construct Only

The service flags.

The "id" property

  "id"                   gchararray            : Read / Write / Construct Only

The service's unique ID.

Default value: NULL

The "name" property

  "name"                 gchararray            : Read / Write / Construct Only

The service's name.

Default value: NULL

Signal Details

The "account-added" signal

void        user_function                  (GalagoService *service,
                                            gpointer       account,
                                            gpointer       user_data)      : Run last / Action

Emitted when an account is added to the service.

service : The object which received the signal.
account : The account that was added.
user_data : user data set when the signal handler was connected.

The "account-removed" signal

void        user_function                  (GalagoService *service,
                                            gpointer       account,
                                            gpointer       user_data)      : Run last / Action

Emitted when an account is removed to the service.

service : The object which received the signal.
account : The account that was removed.
user_data : user data set when the signal handler was connected.

See Also

GalagoAccount