GdictContext

## GdictContext GdictContext — Interface for dictionary transports |

## Synopsis

    struct              GdictContextIface;
    enum                GdictContextError;
    void                gdict_context_set_local_only        (GdictContext *context,
                                                             gboolean local_only);
    gboolean            gdict_context_get_local_only        (GdictContext *context);
    gboolean            gdict_context_lookup_databases      (GdictContext *context,
                                                             GError **error);
    gboolean            gdict_context_lookup_strategies     (GdictContext *context,
                                                             GError **error);
    gboolean            gdict_context_match_word            (GdictContext *context,
                                                             const gchar *database,
                                                             const gchar *strategy,
                                                             const gchar *word,
                                                             GError **error);
    gboolean            gdict_context_define_word           (GdictContext *context,
                                                             const gchar *database,
                                                             const gchar *word,
                                                             GError **error);

                        GdictDatabase;
    GdictDatabase *     gdict_database_ref                  (GdictDatabase *db);
    void                gdict_database_unref                (GdictDatabase *db);
    const gchar *       gdict_database_get_name             (GdictDatabase *db);
    const gchar *       gdict_database_get_full_name        (GdictDatabase *db);

                        GdictStrategy;
    GdictStrategy *     gdict_strategy_ref                  (GdictStrategy *strat);
    void                gdict_strategy_unref                (GdictStrategy *strat);
    const gchar *       gdict_strategy_get_name             (GdictStrategy *strat);
    const gchar *       gdict_strategy_get_description      (GdictStrategy *strat);

                        GdictMatch;
    GdictMatch *        gdict_match_ref                     (GdictMatch *match);
    void                gdict_match_unref                   (GdictMatch *match);
    const gchar *       gdict_match_get_word                (GdictMatch *match);
    const gchar *       gdict_match_get_database            (GdictMatch *match);

                        GdictDefinition;
    GdictDefinition *   gdict_definition_ref                (GdictDefinition *def);
    void                gdict_definition_unref              (GdictDefinition *def);
    gint                gdict_definition_get_total          (GdictDefinition *def);
    const gchar *       gdict_definition_get_word           (GdictDefinition *def);
    const gchar *       gdict_definition_get_database       (GdictDefinition *def);
    const gchar *       gdict_definition_get_text           (GdictDefinition *def);

## Description

GdictContext is an interface used to uniformly access dictionary transport objects. Each implementation of GdictContext must provide functions for accessing the list of databases available on a dictionary source and the available matching strategies; a function for retrieving all words matching a given string, inside one (or more) of those databases and using one of those strategies; a function for querying one (or more) of those databases for a definition of a word.

Implementations of the GdictContext interface should query their dictionary sources asynchronously; methods of the GdictContext interface should return immediately, and each time a new database, strategy, match or definition has been found, a signal should be fired by those implementations.

## Details

### struct GdictContextIface

    struct GdictContextIface {
      /* methods, not signals */
      gboolean (*get_databases)     (GdictContext  *context,
      			         GError       **error);
      gboolean (*get_strategies)    (GdictContext  *context,
      			         GError       **error);
      gboolean (*match_word)        (GdictContext  *context,
      			         const gchar   *database,
      			         const gchar   *strategy,
      			         const gchar   *word,
      			         GError       **error);
      gboolean (*define_word)       (GdictContext  *context,
      			         const gchar   *database,
      			         const gchar   *word,
      			         GError       **error);

      /* signals */
      void (*lookup_start)     (GdictContext    *context);
      void (*lookup_end)       (GdictContext    *context);

      void (*database_found)   (GdictContext    *context,
      			    GdictDatabase   *database);
      void (*strategy_found)   (GdictContext    *context,
      			    GdictStrategy   *strategy);
      void (*match_found)      (GdictContext    *context,
      			    GdictMatch      *match);
      void (*definition_found) (GdictContext    *context,
      			    GdictDefinition *definition);

      /* fired each time there's an error; the GError is owned
       * by the context, and should never be modified or freed
       */
      void (*error)            (GdictContext    *context,
      			    const GError    *error);
    };

Interface defintion

### enum GdictContextError

    typedef enum {
      GDICT_CONTEXT_ERROR_PARSE,
      GDICT_CONTEXT_ERROR_NOT_IMPLEMENTED,
      GDICT_CONTEXT_ERROR_INVALID_DATABASE,
      GDICT_CONTEXT_ERROR_INVALID_STRATEGY,
      GDICT_CONTEXT_ERROR_INVALID_COMMAND,
      GDICT_CONTEXT_ERROR_NO_MATCH,
      GDICT_CONTEXT_ERROR_NO_DATABASES,
      GDICT_CONTEXT_ERROR_NO_STRATEGIES
    } GdictContextError;

GdictContext error enumeration.

### gdict_context_set_local_only ()

    void                gdict_context_set_local_only        (GdictContext *context,
                                                             gboolean local_only);

Sets whether only local resources will be used when querying for databases, strategies, matches or definitions.

`context` : | a GdictContext
`local_only` : | `TRUE` if only local resources will be used

Since 1.0

### gdict_context_get_local_only ()

    gboolean            gdict_context_get_local_only        (GdictContext *context);

Gets whether only local resources will be used when querying.

`context` : | a GdictContext
Returns : | `TRUE` if only local resources will be used.

Since 1.0

### gdict_context_lookup_databases ()

    gboolean            gdict_context_lookup_databases      (GdictContext *context,
                                                             GError **error);

Query `context` for the list of databases available. Each time a database is found, the "database-found" signal is fired.

`context` : | a GdictContext
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if the query was successfully started.

Since 1.0

### gdict_context_lookup_strategies ()

    gboolean            gdict_context_lookup_strategies     (GdictContext *context,
                                                             GError **error);

Query `context` for the list of matching strategies available. Each time a new strategy is found, the "strategy-found" signal is fired.

`context` : | a GdictContext
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if the query was successfully started.

Since 1.0

### gdict_context_match_word ()

    gboolean            gdict_context_match_word            (GdictContext *context,
                                                             const gchar *database,
                                                             const gchar *strategy,
                                                             const gchar *word,
                                                             GError **error);

Query `context` for a list of word matching `word` inside `database`, using `strategy` as a matching strategy. Each time a matching word is found, the "match-found" signal is fired.

`context` : | a GdictContext
`database` : | a database name to search into, or `NULL` for the default database
`strategy` : | a strategy name to use for matching, or `NULL` for the default strategy
`word` : | the word to match
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if the query was successfully started.

Since 1.0

### gdict_context_define_word ()

    gboolean            gdict_context_define_word           (GdictContext *context,
                                                             const gchar *database,
                                                             const gchar *word,
                                                             GError **error);

Query `context` for a list of definitions of `word` inside `database`. Each time a new definition is found, the "definition-found" signal is fired.

`context` : | a GdictContext
`database` : | a database name to search into, or `NULL` for the default database
`word` : | the word to search
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if the query was successfully sent.

Since 1.0

### GdictDatabase

    typedef struct _GdictDatabase GdictDatabase;

A GdictDatabase represents a database inside a dictionary source.

The GdictDatabase structure is private and should only be accessed using the available functions.

### gdict_database_ref ()

    GdictDatabase *     gdict_database_ref                  (GdictDatabase *db);

Increases the reference count of `db` by one.

`db` : | a GdictDatabase
Returns : | `db` with its reference count increased

Since 1.0

### gdict_database_unref ()

    void                gdict_database_unref                (GdictDatabase *db);

Decreases the reference count of `db` by one. If the reference count reaches zero, `db` is destroyed.

`db` : | a GdictDatabase

Since 1.0

### gdict_database_get_name ()

    const gchar *       gdict_database_get_name             (GdictDatabase *db);

Gets the short name of the database, to be used with functions like `gdict_context_match_word()` or `gdict_context_define_word()`.

`db` : | a GdictDatabase
Returns : | the short name of the database. The string is owned by the GdictDatabase object, and should never be modified or freed.

Since 1.0

### gdict_database_get_full_name ()

    const gchar *       gdict_database_get_full_name        (GdictDatabase *db);

Gets the full name of the database, suitable for display.

`db` : | a GdictDatabase
Returns : | the full name of the database. The string is owned by the GdictDatabase object, and should never be modified or freed.

Since 1.0

### GdictStrategy

    typedef struct _GdictStrategy GdictStrategy;

A GdictStrategy represents a matching strategy implemented by a dictionary source.

The GdictStrategy structure is private and should only be accessed using the available functions.

### gdict_strategy_ref ()

    GdictStrategy *     gdict_strategy_ref                  (GdictStrategy *strat);

Increases the reference count of `strat` by one.

`strat` : | a GdictStrategy
Returns : | the GdictStrategy object with its reference count increased

Since 1.0

### gdict_strategy_unref ()

    void                gdict_strategy_unref                (GdictStrategy *strat);

Decreases the reference count of `strat` by one. If the reference count reaches zero, the GdictStrategy object is freed.

`strat` : | a GdictStrategy

Since 1.0

### gdict_strategy_get_name ()

    const gchar *       gdict_strategy_get_name             (GdictStrategy *strat);

FIXME

`strat` : | a GdictStrategy
Returns : | FIXME

Since 1.0

### gdict_strategy_get_description ()

    const gchar *       gdict_strategy_get_description      (GdictStrategy *strat);

FIXME

`strat` : | a GdictStrategy
Returns : | FIXME

Since 1.0

### GdictMatch

    typedef struct _GdictMatch GdictMatch;

A GdictMatch represents a single match for the searched word.

The GdictMatch structure is private and should only be accessed using the available functions.

### gdict_match_ref ()

    GdictMatch *        gdict_match_ref                     (GdictMatch *match);

FIXME

`match` : | a GdictMatch
Returns : | FIXME

Since 1.0

### gdict_match_unref ()

    void                gdict_match_unref                   (GdictMatch *match);

FIXME

`match` : | a GdictMatch

Since 1.0

### gdict_match_get_word ()

    const gchar *       gdict_match_get_word                (GdictMatch *match);

FIXME

`match` : | a GdictMatch
Returns : | FIXME

Since 1.0

### gdict_match_get_database ()

    const gchar *       gdict_match_get_database            (GdictMatch *match);

FIXME

`match` : | a GdictMatch
Returns : | FIXME

Since 1.0

### GdictDefinition

    typedef struct _GdictDefinition GdictDefinition;

A GdictDefinition represents a single definition for the searched word.

The GdictDefinition structure is private and should only be accessed using the available functions.

### gdict_definition_ref ()

    GdictDefinition *   gdict_definition_ref                (GdictDefinition *def);

Increases the reference count of `def` by one.

`def` : | a GdictDefinition
Returns : | the GdictDefinition object with its reference count increased.

Since 1.0

### gdict_definition_unref ()

    void                gdict_definition_unref              (GdictDefinition *def);

Decreases the reference count of `def` by one. If the reference count reaches zero, the GdictDefinition object is freed.

`def` : | a GdictDefinition

Since 1.0

### gdict_definition_get_total ()

    gint                gdict_definition_get_total          (GdictDefinition *def);

Retrieves the total number of definitions that were found on a dictionary.

`def` : | a GdictDefinition
Returns : | the number of definitions.

Since 1.0

### gdict_definition_get_word ()

    const gchar *       gdict_definition_get_word           (GdictDefinition *def);

Retrieves the word used by the dictionary database to store the definition.

`def` : | a GdictDefinition
Returns : | a word. The returned string is owned by the GdictDefinition object and should not be modified or freed.

Since 1.0

### gdict_definition_get_database ()

    const gchar *       gdict_definition_get_database       (GdictDefinition *def);

Retrieves the full name of the dictionary database where the definition is stored.

`def` : | a GdictDefinition
Returns : | the full name of a database. The returned string is owned by the GdictDefinition object and should not be modified or freed.

Since 1.0

### gdict_definition_get_text ()

    const gchar *       gdict_definition_get_text           (GdictDefinition *def);

Retrieves the text of the definition.

`def` : | a GdictDefinition
Returns : | the text of the definition. The returned string is owned by the GdictDefinition object, and should not be modified or freed.

Since 1.0