TranslateSession

TranslateSession — session object

Synopsis




struct      TranslateSession;
#define     TRANSLATE_SESSION_ERROR
enum        TranslateSessionError;
TranslateSession* translate_session_new     (const GSList *services);
void        translate_session_set_services  (TranslateSession *session,
                                             const GSList *services);
void        translate_session_set_max_threads
                                            (TranslateSession *session,
                                             unsigned int max_threads);
void        translate_session_set_max_retries
                                            (TranslateSession *session,
                                             unsigned int max_retries);
GSList*     translate_session_get_services  (TranslateSession *session);
GSList*     translate_session_get_pairs     (TranslateSession *session);
unsigned int translate_session_get_max_threads
                                            (TranslateSession *session);
int         translate_session_get_max_retries
                                            (TranslateSession *session);
char*       translate_session_translate_text
                                            (TranslateSession *session,
                                             const char *text,
                                             const char *from,
                                             const char *to,
                                             TranslateProgressFunc progress_func,
                                             gpointer user_data,
                                             GError **err);
char*       translate_session_translate_web_page
                                            (TranslateSession *session,
                                             const char *url,
                                             const char *from,
                                             const char *to,
                                             TranslateProgressFunc progress_func,
                                             gpointer user_data,
                                             GError **err);

Object Hierarchy


  GObject
   +----TranslateSession

Properties


  "max-retries"          gint                 : Read / Write / Construct
  "max-threads"          guint                : Read / Write / Construct
  "pairs"                gpointer             : Read
  "services"             gpointer             : Read / Write / Construct

Description

A TranslateSession object is used to translate a text or web page using a set of translation services. After creating a new session with translate_session_new(), you can translate a text or web page using translate_session_translate_text() or translate_session_translate_web_page().

Details

struct TranslateSession

struct TranslateSession;

The TranslateSession struct contains private data only, and should be accessed using the functions below.


TRANSLATE_SESSION_ERROR

#define TRANSLATE_SESSION_ERROR			(translate_session_error_quark())

The error domain of translate_session_translate_text() and translate_session_translate_web_page(). Errors in this domain are from the TranslateSessionError enumeration.


enum TranslateSessionError

typedef enum
{
  TRANSLATE_SESSION_ERROR_NO_SERVICE
} TranslateSessionError;

Error codes returned by translate_session_translate_text() and translate_session_translate_web_page().

TRANSLATE_SESSION_ERROR_NO_SERVICEno service could translate using the given language pair

translate_session_new ()

TranslateSession* translate_session_new     (const GSList *services);

Creates a new translation session, which will use services for performing translations.

services : a list of TranslateService objects to use. See translate_session_set_services().
Returns : a new translation session.

translate_session_set_services ()

void        translate_session_set_services  (TranslateSession *session,
                                             const GSList *services);

Sets the services used by session. Default value: NULL.

The list of services determines the available language pairs (see translate_session_get_pairs()). The order of the list is important, as translate_session_translate_text() and translate_session_translate_web_page() iterate over the list until the translation can be performed.

session : a session.
services : a list of TranslateService objects to use.

translate_session_set_max_threads ()

void        translate_session_set_max_threads
                                            (TranslateSession *session,
                                             unsigned int max_threads);

Sets the maximum number of concurrent threads to use for translating text. Default value: 8.

session : a session.
max_threads : a maximum number of threads.

translate_session_set_max_retries ()

void        translate_session_set_max_retries
                                            (TranslateSession *session,
                                             unsigned int max_retries);

Sets the maximum number of retries per text chunk. Default value: 3.

session : a session.
max_retries : a maximum number of retries.

translate_session_get_services ()

GSList*     translate_session_get_services  (TranslateSession *session);

Gets the services used by session. When no longer needed, the list should be freed with:

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

session : a session.
Returns : the list of TranslateService objects used by session.

translate_session_get_pairs ()

GSList*     translate_session_get_pairs     (TranslateSession *session);

Gets the list of language pairs available for translations. When no longer needed, the list should be freed with:

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

session : a session.
Returns : the list of TranslatePair objects available for translations.

translate_session_get_max_threads ()

unsigned int translate_session_get_max_threads
                                            (TranslateSession *session);

Gets the maximum number of concurrent threads to use for translating text.

session : a session.
Returns : the maximum number of threads.

translate_session_get_max_retries ()

int         translate_session_get_max_retries
                                            (TranslateSession *session);

Gets the maximum number of retries per text chunk.

session : a session.
Returns : the maximum number of retries.

translate_session_translate_text ()

char*       translate_session_translate_text
                                            (TranslateSession *session,
                                             const char *text,
                                             const char *from,
                                             const char *to,
                                             TranslateProgressFunc progress_func,
                                             gpointer user_data,
                                             GError **err);

Translates text from the language from into the language to.

If progress_func is specified, it may be called periodically to report progress. If, when called, progress_func returns FALSE, the translation is cancelled as soon as possible, NULL is returned, and err is set to an error of domain TRANSLATE_ERROR and code TRANSLATE_ERROR_CANCELLED.

session : a session.
text : a nul-terminated string.
from : a RFC 3066 language tag.
to : a RFC 3066 language tag.
progress_func : a function to call when progressing, or NULL.
user_data : data to pass to progress_func, or NULL.
err : a location to report errors, or NULL. Any of the errors in TranslateSessionError, TranslateError or other domains may occur.
Returns : the translated text on success, or NULL on failure (in such case err is set). The returned string should be freed when no longer needed.

translate_session_translate_web_page ()

char*       translate_session_translate_web_page
                                            (TranslateSession *session,
                                             const char *url,
                                             const char *from,
                                             const char *to,
                                             TranslateProgressFunc progress_func,
                                             gpointer user_data,
                                             GError **err);

Translates a web page from the language from into the language to.

If progress_func is specified, it may be called periodically to report progress. If, when called, progress_func returns FALSE, the translation is cancelled as soon as possible, NULL is returned, and err is set to an error of domain TRANSLATE_ERROR and code TRANSLATE_ERROR_CANCELLED.

session : a session.
url : an URL.
from : a RFC 3066 language tag.
to : a RFC 3066 language tag.
progress_func : a function to call when progressing, or NULL.
user_data : data to pass to progress_func, or NULL.
err : a location to report errors, or NULL. Any of the errors in TranslateSessionError, TranslateError or other domains may occur.
Returns : an URL pointing to the translated web page on success, or NULL on failure (in such case err is set). The returned string should be freed when no longer needed.

Properties

"max-retries" (gint : Read / Write / Construct)

The maximum number of times to retry a translation of the same chunk (-1 for unlimited).

"max-threads" (guint : Read / Write / Construct)

The maximum number of translation threads to use.

"pairs" (gpointer : Read)

The list of pairs this session supports.

"services" (gpointer : Read / Write / Construct)

The list of services used by this session.