GdictContext

GdictContext — Abstract interface for dictionary transports.

Synopsis


#include <gdict-context.h>


            GdictContext;
enum        GdictContextError;

gboolean    gdict_context_get_local_only    (GdictContext *context);
void        gdict_context_set_local_only    (GdictContext *context,
                                             gboolean local_only);
gboolean    gdict_context_lookup_databases  (GdictContext *context,
                                             GError **error);
gboolean    gdict_context_lookup_strategies (GdictContext *context,
                                             GError **error);
gboolean    gdict_context_define_word       (GdictContext *context,
                                             const gchar *database,
                                             const gchar *word,
                                             GError **error);
gboolean    gdict_context_match_word        (GdictContext *context,
                                             const gchar *database,
                                             const gchar *strategy,
                                             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 abstract 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 to a 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 is found, a signal should be fired by those implementations.

Details

GdictContext

typedef struct _GdictContext GdictContext;

The GdictClientContext struct contains private data only.


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;

These identify the various errors that can occur while calling GdictContext functions. Implementations should use these general error codes, but might provide other errors.

GDICT_CONTEXT_ERROR_PARSE Indicates that an error occurred while parsing the dictionary source.
GDICT_CONTEXT_ERROR_NOT_IMPLEMENTED Indicates that a command is not implemented by a dictionary source.
GDICT_CONTEXT_ERROR_INVALID_DATABASE Indicates that the requested database is either invalid or was not found on the dictionary source.
GDICT_CONTEXT_ERROR_INVALID_STRATEGY Indicates that the requested strategy is either invalid or was not found on the dictionary source.
GDICT_CONTEXT_ERROR_INVALID_COMMAND Indicates that the requested command is not recognized by the dictionary source.
GDICT_CONTEXT_ERROR_NO_MATCH Indicates that no matches were found for the word used in a query.
GDICT_CONTEXT_ERROR_NO_DATABASES Indicates that no databases were found on the dictionary source.
GDICT_CONTEXT_ERROR_NO_STRATEGIES Indicates that no strategies were found on the dictionary source.

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_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_lookup_databases ()

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

Query context for the list of databases available. Each time a new 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_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


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


GdictDatabase

typedef struct _GdictDatabase GdictDatabase;

A GdictDatabase represents a database inside a dictionary source.


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 inside a dictionary source.


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 a word inside a dictionary source.


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 a word inside a dictionary source.


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

See Also

GdictClientContext, GdictSource