translate

translate — library initialization and core functions

Synopsis




#define     TRANSLATE_MAJOR_VERSION
#define     TRANSLATE_MINOR_VERSION
#define     TRANSLATE_MICRO_VERSION
extern      const unsigned int		translate_major_version;
extern      const unsigned int		translate_minor_version;
extern      const unsigned int		translate_micro_version;
#define     TRANSLATE_ERROR
#define     TRANSLATE_INIT_ERROR
enum        TranslateError;
enum        TranslateInitError;
gboolean    (*TranslateModuleInitFunc)      (GError **err);
extern      gboolean	   translate_initialized;
gboolean    translate_init                  (GError **err);
gboolean    translate_add_service           (TranslateService *service);
TranslateService* translate_get_service     (const char *name);
GSList*     translate_get_services          (void);
gboolean    translate_add_language          (const char *tag,
                                             const char *name);
const char* translate_get_language_name     (const char *tag);
void        translate_set_proxy             (const char *uri);
char*       translate_get_proxy             (void);

Description

The following functions, variables and macros are used to determine the libtranslate version, initialize libtranslate, manipulate services, languages and the network proxy.

Details

TRANSLATE_MAJOR_VERSION

#define TRANSLATE_MAJOR_VERSION		0

Like translate_major_version, but from the headers used at application compile time, rather than from the library linked against at application runtime.


TRANSLATE_MINOR_VERSION

#define TRANSLATE_MINOR_VERSION		99

Like translate_minor_version, but from the headers used at application compile time, rather than from the library linked against at application runtime.


TRANSLATE_MICRO_VERSION

#define TRANSLATE_MICRO_VERSION		0

Like translate_micro_version, but from the headers used at application compile time, rather than from the library linked against at application runtime.


translate_major_version

extern const unsigned int		translate_major_version;

The major version number of libtranslate. This variable is in the library, so it represents the translate library you have linked against. Contrast with the TRANSLATE_MAJOR_VERSION macro, which represents the major version of the libtranslate headers you have included.


translate_minor_version

extern const unsigned int		translate_minor_version;

The minor version number of libtranslate. This variable is in the library, so it represents the translate library you have linked against. Contrast with the TRANSLATE_MINOR_VERSION macro, which represents the minor version of the libtranslate headers you have included.


translate_micro_version

extern const unsigned int		translate_micro_version;

The micro version number of libtranslate. This variable is in the library, so it represents the translate library you have linked against. Contrast with the TRANSLATE_MICRO_VERSION macro, which represents the micro version of the libtranslate headers you have included.


TRANSLATE_ERROR

#define TRANSLATE_ERROR			(translate_error_quark())

Generic libtranslate error domain. Errors in this domain are from the TranslateError enumeration.


TRANSLATE_INIT_ERROR

#define TRANSLATE_INIT_ERROR		(translate_init_error_quark())

The error domain of translate_init(). Errors in this domain are from the TranslateInitError enumeration.


enum TranslateError

typedef enum
{
  TRANSLATE_ERROR_FAILED,
  TRANSLATE_ERROR_CANCELLED
} TranslateError;

Generic error codes returned by libtranslate routines when more specialized error codes are not relevant.

TRANSLATE_ERROR_FAILEDa generic error has occurred
TRANSLATE_ERROR_CANCELLEDthe user has cancelled the operation

enum TranslateInitError

typedef enum
{
  TRANSLATE_INIT_ERROR_MULTI_THREADING_NOT_SUPPORTED
} TranslateInitError;

Error codes returned by translate_init().

TRANSLATE_INIT_ERROR_MULTI_THREADING_NOT_SUPPORTEDmulti-threading is not supported

TranslateModuleInitFunc ()

gboolean    (*TranslateModuleInitFunc)      (GError **err);

Specifies the type of the module initialization function.

A libtranslate module must contain a function named translate_module_init(), which is called when the module is loaded.

err : a location to report errors, or NULL.
Returns : the function should return FALSE if the module could not be initialized. In such case it should also set err, which is printed by libtranslate.

translate_initialized

extern gboolean	   translate_initialized;

Whether libtranslate is initialized or not (read-only). You probably do not need to use this variable, as translate_init() can be called multiple times.


translate_init ()

gboolean    translate_init                  (GError **err);

Initializes libtranslate. This function can safely be called multiple times (however, it is not thread-safe, read below). When it is called more than once, it returns the status (and error if any) of the initial invocation.

Important

Unlike other libtranslate functions, translate_init() is not thread-safe, and must not be called while any mutex is held. The reason is that translate_init() may call g_thread_init(). Refer to the g_thread_init() documentation for more details.

err : a location to report errors, or NULL. Any of the errors in TranslateInitError or other domains may occur.
Returns : TRUE if the initialization was successful, FALSE otherwise (in such case err is set to the error that has occurred).

translate_add_service ()

gboolean    translate_add_service           (TranslateService *service);

Adds service to the libtranslate service list. If a service with the same name is already in the list, nothing is done and FALSE is returned.

service : a service.
Returns : TRUE if the service was added, FALSE if it was already in the list.

translate_get_service ()

TranslateService* translate_get_service     (const char *name);

Looks up a service in the libtranslate service list.

name : a service name, encoded in ASCII.
Returns : a new reference to the service with name name, or NULL if not found.

translate_get_services ()

GSList*     translate_get_services          (void);

Gets a copy of the libtranslate service list. When no longer needed, the list should be freed with:

g_slist_foreach(list, (GFunc) g_object_unref, NULL);
g_slist_free(list);

Returns : a copy of the libtranslate service list.

translate_add_language ()

gboolean    translate_add_language          (const char *tag,
                                             const char *name);

Adds a language tag to name mapping to the libtranslate language database. If a language with the same tag already exists in the database, nothing is done and FALSE is returned.

Note

Some RFC 3066 tag to name mappings are built into libtranslate and do not need to be added.

tag : a RFC 3066 language tag.
name : the language human-readable name.
Returns : TRUE if the language was added, FALSE if it was already in the database.

translate_get_language_name ()

const char* translate_get_language_name     (const char *tag);

Looks up a language tag in the libtranslate language database, and returns its human-readable name.

tag : a RFC 3066 language tag.
Returns : the human-readable name of the language with tag tag, or tag itself if not found. If the returned string is not tag, it is owned by libtranslate and must not be modified or freed.

translate_set_proxy ()

void        translate_set_proxy             (const char *uri);

Sets the URI of a proxy server to use for network transfers.

uri : the URI of a proxy server, or NULL to unset.

translate_get_proxy ()

char*       translate_get_proxy             (void);

Gets the URI thas has been previously set with translate_set_proxy().

If you are implementing a service, you must use this URI for proxying network transfers.

Returns : the libtranslate proxy URI, or NULL if no proxy is set. The returned string should be freed when no longer needed.