## GdictSource GdictSource — A Dictionary Source definition |

## Synopsis

                GdictSourcePrivate;
    enum        GdictSourceTransport;
    #define     GDICT_SOURCE_ERROR
    enum        GdictSourceError;
    GQuark      gdict_source_error_quark        (void);
                GdictSource;
    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);
    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);

## Description

GdictSource is the representation of a dictionary source definition. By using a GdictSource object you can retrieve the appropriate GdictContext, already set up with the right parameters.

A GdictSource is represented using a GKeyFile.

## Details

### GdictSourcePrivate

    typedef struct _GdictSourcePrivate GdictSourcePrivate;

### enum GdictSourceTransport

    typedef enum
    {
      GDICT_SOURCE_TRANSPORT_DICTD,

      GDICT_SOURCE_TRANSPORT_INVALID /* only for debug */
    } GdictSourceTransport;

### GDICT_SOURCE_ERROR

    #define GDICT_SOURCE_ERROR	(gdict_source_error_quark ())

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

### gdict_source_error_quark ()

    GQuark      gdict_source_error_quark        (void);

Returns : |

### GdictSource

    typedef struct {
    } GdictSource;

The GdictSource structure contains onlyn private data.

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

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

## See Also

GdictContext