## 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_SERVICE` | no 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.