## GdictSource

GdictSource — A dictionary source definition

## Synopsis

    enum                GdictSourceError;
                        GdictSource;
                        GdictSourceClass;
    GdictSource *       gdict_source_new                    (void);
    gboolean            gdict_source_load_from_file         (GdictSource *source,
                                                             const gchar *filename,
                                                             GError **error);
    gboolean            gdict_source_load_from_data         (GdictSource *source,
                                                             const gchar *data,
                                                             gsize length,
                                                             GError **error);
    gchar *             gdict_source_to_data                (GdictSource *source,
                                                             gsize *length,
                                                             GError **error);
    void                gdict_source_set_name               (GdictSource *source,
                                                             const gchar *name);
    const gchar *       gdict_source_get_name               (GdictSource *source);
    void                gdict_source_set_description        (GdictSource *source,
                                                             const gchar *description);
    const gchar *       gdict_source_get_description        (GdictSource *source);
    void                gdict_source_set_database           (GdictSource *source,
                                                             const gchar *database);
    const gchar *       gdict_source_get_database           (GdictSource *source);
    void                gdict_source_set_strategy           (GdictSource *source,
                                                             const gchar *strategy);
    const gchar *       gdict_source_get_strategy           (GdictSource *source);
    enum                GdictSourceTransport;
    void                gdict_source_set_transport          (GdictSource *source,
                                                             GdictSourceTransport transport,
                                                             const gchar *first_transport_property,
                                                             ...);
    void                gdict_source_set_transportv         (GdictSource *source,
                                                             GdictSourceTransport transport,
                                                             const gchar *first_transport_property,
                                                             va_list var_args);
    GdictSourceTransport  gdict_source_get_transport        (GdictSource *source);
    GdictContext *      gdict_source_get_context            (GdictSource *source);
    GdictContext *      gdict_source_peek_context           (GdictSource *source);

## Object Hierarchy

      GObject
       +----GdictSource

## Properties

      "context"                  GdictContext*         : Read
      "database"                 gchar*                : Read / Write
      "description"              gchar*                : Read / Write
      "filename"                 gchar*                : Read
      "name"                     gchar*                : Read / Write
      "strategy"                 gchar*                : Read / Write
      "transport"                GdictSourceTransport  : Read / Write

## Description

GdictSource is the representation of a GdictContext. Each dictionary source provides a list of available dictionaries (databases) and a list of available matching strategies. Using a GdictContext you can query the dictionary source for matching words and for definitions.

By using a GdictSource object you can retrieve the appropriate GdictContext, already set up with the right parameters.

## Details

### enum GdictSourceError

    typedef enum
    {
      GDICT_SOURCE_ERROR_PARSE,
      GDICT_SOURCE_ERROR_INVALID_NAME,
      GDICT_SOURCE_ERROR_INVALID_TRANSPORT,
      GDICT_SOURCE_ERROR_INVALID_BAD_PARAMETER
    } GdictSourceError;

### GdictSource

    typedef struct _GdictSource GdictSource;

### GdictSourceClass

    typedef struct {
    } GdictSourceClass;

### gdict_source_new ()

    GdictSource *       gdict_source_new                    (void);

Creates an empty GdictSource object. Use `gdict_load_from_file()` to read an existing dictionary source definition file.

Returns : | an empty GdictSource

### gdict_source_load_from_file ()

    gboolean            gdict_source_load_from_file         (GdictSource *source,
                                                             const gchar *filename,
                                                             GError **error);

Loads a dictionary source definition file into an empty GdictSource object.

`source` : | an empty GdictSource
`filename` : | path to a dictionary source file
`error` : | return location for a GError or `NULL`
Returns : | `TRUE` if `filename` was loaded successfully.

Since 1.0

### gdict_source_load_from_data ()

    gboolean            gdict_source_load_from_data         (GdictSource *source,
                                                             const gchar *data,
                                                             gsize length,
                                                             GError **error);

Loads a dictionary source definition from `data` inside an empty GdictSource object.

`source` : | a GdictSource
`data` : | string containing a dictionary source
`length` : | length of `data`
`error` : | return location for a GError or `NULL`
Returns : | `TRUE` if `filename` was loaded successfully.

Since 1.0

### gdict_source_to_data ()

    gchar *             gdict_source_to_data                (GdictSource *source,
                                                             gsize *length,
                                                             GError **error);

Outputs a dictionary source as a string.

`source` : | a GdictSource
`length` : | return loaction for the length of the string, or `NULL`
`error` : | return location for a GError or `NULL`
Returns : | a newly allocated string holding the contents of `source`.

Since 1.0

### gdict_source_set_name ()

    void                gdict_source_set_name               (GdictSource *source,
                                                             const gchar *name);

Sets `name` as the displayable name of the dictionary source.

`source` : | a GdictSource
`name` : | the UTF8-encoded name of the dictionary source

Since 1.0

### gdict_source_get_name ()

    const gchar *       gdict_source_get_name               (GdictSource *source);

Retrieves the name of `source`.

`source` : | a GdictSource
Returns : | the name of a GdictSource. The returned string is owned by the GdictSource object, and should not be modified or freed.

Since 1.0

### gdict_source_set_description ()

    void                gdict_source_set_description        (GdictSource *source,
                                                             const gchar *description);

Sets the description of `source`. If `description` is `NULL`, unsets the currently set description.

`source` : | a GdictSource
`description` : | a UTF-8 encoded description or `NULL`

Since 1.0

### gdict_source_get_description ()

    const gchar *       gdict_source_get_description        (GdictSource *source);

Retrieves the description of `source`.

`source` : | a GdictSource
Returns : | the description of a GdictSource. The returned string is owned by the GdictSource object, and should not be modified or freed.

Since 1.0

### gdict_source_set_database ()

    void                gdict_source_set_database           (GdictSource *source,
                                                             const gchar *database);

Sets the default database of `source`. If `database` is `NULL`, unsets the currently set database.

`source` : | a GdictSource
`database` : | a UTF-8 encoded database name or `NULL`

Since 1.0

### gdict_source_get_database ()

    const gchar *       gdict_source_get_database           (GdictSource *source);

Retrieves the default database of `source`.

`source` : | a GdictSource
Returns : | the default strategy of a GdictSource. The returned string is owned by the GdictSource object, and should not be modified or freed.

Since 1.0

### gdict_source_set_strategy ()

    void                gdict_source_set_strategy           (GdictSource *source,
                                                             const gchar *strategy);

Sets the description of `source`. If `strategy` is `NULL`, unsets the currently set strategy.

`source` : | a GdictSource
`strategy` : | a UTF-8 encoded strategy or `NULL`

Since 1.0

### gdict_source_get_strategy ()

    const gchar *       gdict_source_get_strategy           (GdictSource *source);

Retrieves the default strategy of `source`.

`source` : | a GdictSource
Returns : | the default strategy of a GdictSource. The returned string is owned by the GdictSource object, and should not be modified or freed.

Since 1.0

### enum GdictSourceTransport

    typedef enum
    {
      GDICT_SOURCE_TRANSPORT_DICTD,

      GDICT_SOURCE_TRANSPORT_INVALID /* only for debug */
    } GdictSourceTransport;

### gdict_source_set_transport ()

    void                gdict_source_set_transport          (GdictSource *source,
                                                             GdictSourceTransport transport,
                                                             const gchar *first_transport_property,
                                                             ...);

Sets `transport` as the choosen transport for `source`. The `transport` argument is a method of retrieving dictionary data from a source; it is used to create the right GdictContext for this GdictSource. After `transport`, property name/value pairs should be listed, with a `NULL` pointer ending the list. Properties are the same passed to a GdictContext implementation instance using `g_object_set()`.

Here's a simple example:

    #include <gdict/gdict.h>
     GdictSource *source = gdict_source_new ();

     gdict_source_set_name (source, "My Source");
     gdict_source_set_transport (source, GDICT_SOURCE_TRANSPORT_DICTD,
                                 "hostname", "dictionary-server.org",
                                 "port", 2628,
                                 NULL);

`source` : | a GdictSource
`transport` : | a valid transport
`first_transport_property` : | property for the context bound to the transport, or `NULL`
`...` : | property value for first property name, then additionary properties, ending with `NULL`

Since 1.0

### gdict_source_set_transportv ()

    void                gdict_source_set_transportv         (GdictSource *source,
                                                             GdictSourceTransport transport,
                                                             const gchar *first_transport_property,
                                                             va_list var_args);

FIXME

`source` : | a GdictSource
`transport` : | a GdictSourceTransport
`first_transport_property` : | FIXME
`var_args` : | FIXME

Since 1.0

### gdict_source_get_transport ()

    GdictSourceTransport  gdict_source_get_transport        (GdictSource *source);

FIXME

`source` : | a GdictSource
Returns : | FIXME

Since 1.0

### gdict_source_get_context ()

    GdictContext *      gdict_source_get_context            (GdictSource *source);

Gets the GdictContext bound to `source`.

`source` : | a GdictSource
Returns : | a GdictContext for `source`. Use `g_object_unref()` when you don't need it anymore.

Since 1.0

### gdict_source_peek_context ()

    GdictContext *      gdict_source_peek_context           (GdictSource *source);

Gets the GdictContext bound to `source`. The returned object is a referenced copy of the context held by `source`; if you want a different instance, use `gdict_source_get_context()`.

`source` : | a GdictSource
Returns : | a referenced GdictContext. Use `g_object_unref()` when finished using it.

Since 1.0

## Property Details

### The `"context"` property

      "context"                  GdictContext*         : Read

The GdictContext bound to this source.

Since 1.0

### The `"database"` property

      "database"                 gchar*                : Read / Write

The default database of this dictionary source.

Default value: NULL

Since 1.0

### The `"description"` property

      "description"              gchar*                : Read / Write

The description of this dictionary source.

Default value: NULL

Since 1.0

### The `"filename"` property

      "filename"                 gchar*                : Read

The filename used by this dictionary source.

Default value: NULL

Since 1.0

### The `"name"` property

      "name"                     gchar*                : Read / Write

The display name of this dictionary source.

Default value: NULL

Since 1.0

### The `"strategy"` property

      "strategy"                 gchar*                : Read / Write

The default strategy of this dictionary source.

Default value: NULL

Since 1.0

### The `"transport"` property

      "transport"                GdictSourceTransport  : Read / Write

The transport mechanism used by this source.

Default value: GDICT_SOURCE_TRANSPORT_INVALID

Since 1.0