GalagoService

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