# The Translation Kit: BTranslatorRoster

Derived from: public BArchivable

Declared in: be/translation/TranslatorRoster.h

Library: libtranslation.so

## Overview

BTranslatorRoster is the main mechanism through which applications interact with the Translation Kit. An application using the Translation Kit doesn't need to worry about explicitly loading or calling add-ons; BTranslatorRoster transparently handles all the niggling details. The class provides four categories of service: initialization, information, translation, and configuration.

### Initialization

You can create an empty BTranslatorRoster (one which has no translators loaded) by instantiating it in the usual fashion:

       BTranslatorRoster *roster = new BTranslatorRoster;

You can then load translators to the newly-created BTranslatorRoster with the `AddTranslators()` method (all paths must be absolute):

       // load all translators in a given directory
       roster->AddTranslators("/boot/home/config/add-ons/viewer/");

       // load a specific translator
       roster->AddTranslators("/system/add-ons/Translators/photos");

More commonly, you want a BTranslatorRoster with the default translators (those in /boot/home/config/add-ons/Translators, /boot/home/config/add-ons/Datatypes, and /system/add-ons/Translators). The static member `Default()` returns just such a beast:

       BTranslatorRoster *roster = BTranslatorRoster::Default();

However, not all BTranslatorRosters are created equal: the object returned by `Default()` is global to the application and controlled by BTranslatorRoster. As a result, you should never `delete` it. Additionally, if you want to load additional translators, you're better off creating a new instance of BTranslatorRoster rather than using the default one:

       BTranslatorRoster *roster = new BTranslatorRoster;
       roster->AddTranslators(NULL); // load default translators
       roster->AddTranslators(...);  // load additional translators

### Information

Applications typically ask the following questions of the Translation Kit:

1. Which translators are installed?

2. Which translations can a particular translator carry out?

3. Which translator is best suited for handling my conversion?

An application can determine the installed translators by calling `GetAllTranslators()`. `GetAllTranslators()` returns an array of translator_id values for the installed translators. A translator_id is an application-wide value assigned by BTranslatorRoster identifying a specific translator. The following snippet prints out the names of the default translators:

       BTranslatorRoster *roster = BTranslatorRoster::Default();
       int32 num_translators, i;
       translator_id *translators;
       const char *translator_name, *translator_info;
       int32 translator_version;

       roster->GetAllTranslators(&translators, &num_translators);
       for (i=0;i<num_translators;i++) {
          roster->GetTranslatorInfo(translators[i], &translator_name,
             &translator_info, &translator_version);
          printf("%s: %s (%.2f)\\n", translator_name, translator_info,
             translator_version/100.);
       }

       delete [] translators; // clean up our droppings

The translator_id is very valuable; it can be used to query BTranslatorRoster for specific information about a translator's capabilities. This information comes in two nearly identical flavors: translation_format and translator_info. They are defined in <be/translation/TranslationDefs.h>:

       struct translation_format {
          uint32 type;
          uint32 group;
          float  quality;
          float  capability;
          char   MIME[251];
          char   name[251];
       }

       struct translator_info {
          uint32        type;
          translator_id translator;
          uint32        group;
          float         quality;
          float         capability;
          char          name[251];
          char          MIME[251];
       }

The common fields:

- group. Defines the type of media the format represents, i.e. bitmap image, sound, or video. Constants for common media types can be found in <be/translation/TranslatorFormats.h>.

- type. Type constant defining the specific data format. For example, the type constant for tiff bitmaps differs from the constant for jpeg bitmaps.

- quality. Ability of the format to represent data of its media group. This value ranges from a low of 0.0 (utter inability) to a high of 1.0 (encodes all relevant information).

- capability. Ability of translator to decode the format. As with the quality, the value ranges from 0.0 (unable to decode) to 1.0 (can decode all variants and extensions).

- MIME. MIME type of the format. This is a more reliable indicator of the data format than the type field for those formats that have standard MIME names.

- name. Human-readable C string describing the format. May include information about the translator as well.

Additionally, translator_info defines an additional field:

- translator. translator_id for the translator associated with the structure.

To find the media formats supported by a particular translator, call `GetInputFormats()` or `GetOutputFormats()` as appropriate. These methods return a list of the supported input or output formats in an array of translation_format.

Many times, however, you don't really care about individual translators; you just want the translator best suited for handling your media stream. In these cases, you can just call `Identify()` on the BPositionIO. BTranslatorRoster will then return, in a translator_info, the translator most suited for carrying out the translation. If you are instead interested in finding all the translators capable of handling the data in your stream, use `GetTranslators()` instead.

Note that some translators do not publish their input and output formats. In these cases, `GetInputFormats()` and `GetOutputFormats()` return an empty list of formats. The only way to tell if such a translator supports a particular input or output format is to pass it to `Identify()`.

### Translation

Although the function of BTranslatorRoster is to provide translation services, carrying out the translation is simple. All it requires are the input and output `BPositionIO` streams and the type constant for the desired output. In the simplest case, if you know the type constant you want to convert the data into, you can let the BTranslatorRoster decide which translator to use:

       BPositionIO *in = ..., *out = ...;
       BTranslatorRoster *roster = BTranslatorRoster::Default();
       uint32 desired_format_constant = ...;

       roster->Translate(in, NULL, NULL, out, desired_format_constant);

Sometimes, however, you'd like the services of a specific translator. In these cases, you can use the alternate form of `Translate()`:

       BPositionIO *in = ..., *out = ...;
       BTranslatorRoster *roster = BTranslatorRoster::Default();
       uint32 desired_format_constant = ...;
       translator_id desired_translator_id = ...;

       roster->Translate(desired_translator_id, in, NULL, NULL, out,
          desired_format_constant);

### Configuration

BTranslatorRoster provides two mechanisms for configuring the behavior of translators: ioExtension and `MakeConfiguationView()`.

ioExtension is a BMessage that can be passed to most BTranslatorRoster members. It is used by the application to communicate format-specific information to the translator. For example, it could be used to ask a video translator to only translate the first 15 frames of the movie. The ioExtension field is also used by the translator to communicate information back to the application. The translator may use it, for example, to tell the application that it is returning a greyscale image.

A translator need not support any particular extension and there is no way for an application to tell if a translator supports any extensions.

A set of standard ioExtension messages can be found in <be/translation/TranslatorFormats.h> and are explained below:

Name | Type | Direction | Description
`kCommentExtension` | `string` | n/a | Text comment about data.
`kTimeExtension` | `bigtime_t` | app to translator | If one exists, it specifies a single instant in time. If two exist, they specify a range in time. Time is measured in microseconds.
`kFrameExtension` | `uint32` | app to translator | Same as kTimeExtension, except the unit of time is frames.
`kBitsRectExtension` | `BRect` | app to translator | Specifies subsection of a bitmap.
`kBitsSpaceExtension` | `color_space` | both | Specifies desired/actual color space of bitmap.
`kHeaderExtension` | `bool` | app to translator | Only output header if true
`kDataExtension` | `bool` | app to translator | Only output data if true
`kNoisChannelExtension` | `uint32` | app to translator | Only output specified channel of sound.
`kNoisMonoExtension` | `bool` | app to translator | Mix all audio channels to a single mono channel if true.
`kNoisMarkerExtension` | `uint32` | both | Specifies markers in sound data. Units are in frames. "1" specifies marker between first sample of last channel and second sample of first channel.
`kNoisLoopExtension` | `uint32` | both | If there is one value, loop from the end of the sample to the loop point. If there are two values, loop from the second value to the first. If there are more than two values, then there is a release loop.

BTranslatorRoster contains two methods to facilitate configuration of translators. The first method, `MakeConfigurationView()`, instructs the translator to create a BView in which configuration options may be changed. It is the responsibility of the application calling `MakeConfigurationView()` to attach the view to a BWindow. The second method, `GetConfigurationMessage()`, fills in a BMessage with the current settings for a specified translator. This BMessage can then be passed to `Translate()` to request a translation with the settings contained within.

### Example

The task of translating data often boils down to finding the right type constant. The following function will print the format type constants associated with a MIME string given a BTranslatorRoster:

       void find_constant(BTranslatorRoster *roster, const char *mime)
       {
          translator_id *translators;
          int32 num_translators;

          roster->GetAllTranslators(&translators, &num_translators);

          for (int32 i=0;i<num_translators;i++) {
             const translation_format *fmts;
             int32 num_fmts;

             roster->GetOutputFormats(translators[i], &fmts, &num_fmts);

             for (int32 j=0;j<num_fmts;j++) {
                if (!strcasecmp(fmts[j].MIME, mime))
                   printf("match: %s type %8.8x (%4.4s)\\n",
                      fmts[j].name, fmts[j].type, &fmts[j].type);
             }
          }
       }

## Constructor and Destructor

### BTranslatorRoster()

          BTranslatorRoster()

          BTranslatorRoster(BMessage *model)

Creates a new container for translators. The no-argument constructor creates an empty container. The BMessage constructor loads all the translators from the directories specified in the "be:translator_path" named fields in model.

If you just want to load the translators from the standard directories, you can instead use the static member `Default()` described below.

See also: `Default()` static function, `AddTranslators()`

### ~BTranslatorRoster()

          ~BTranslatorRoster()

Unloads any translators that were loaded and frees all memory allocated by the BTranslatorRoster.

## Static Functions

### Default()

          BTranslatorRoster *Default()

This returns a default set of translators, loaded from the colon-deliminated list of files and directories found in the environment variable `TRANSLATORS`. If no such variable exists, the translators are loaded from the default locations /boot/home/config/add-ons/Translators, /boot/home/config/add-ons/Datatypes, and /system/add-ons/Translators.

The instance of BTranslatorRoster returned by this function is global to the application and should not be deleted. Although you can add translators to the returned BTranslatorRoster, this is not recommended. It's better to use a new instance of the class.

See also: `AddTranslators()`

### Instantiate()

          BTranslatorRoster *Instantiate(BMessage *from)

Returns a new BTranslatorRoster object, allocated by `new` and created with the version of the constructor that takes a BMessage archive. However, if the archive doesn't contain data for a BTranslatorRoster object, `Instantiate()` returns `NULL`.

See also: `BArchivable::Instantiate()`, `instantiate_object()`, `Archive()`

### Version()

          const char *Version(int32 *outCurVersion, int32 *outMinVersion, int32 *inAppVersion = B_TRANSLATION_CURRENT_VERSION)

Sets outCurVersion to the Translation Kit protocol version number and outMinVersion to the minimum protocol version number supported. Returns a human-readable string containing version information. Currently, inAppVersion must be `B_TRANSLATION_CURRENT_VERSION`.

## Member Functions

### AddTranslators()

          virtual status_t AddTranslators(const char *load_path = NULL)

Loads all the translators located in the colon-deliminated list of files and directories found in load_path. All specified paths must be absolute. If load_path is `NULL`, it loads the translators from the locations specified in the `TRANSLATORS` environment variable. If the environment variable is not defined, then it loads all the files in the default directories /boot/home/config/add-ons/Translators, /boot/home/config/add-ons/Datatypes, and /system/add-ons/Translators.

RETURN CODES

``

- B_NO_ERROR. Identification of inSource was successful.``
- B_BAD_VALUE. Error parsing load_path.
- Anything else. Error loading add-ons.

See also: `Default()` static function

### Archive()

          virtual status_t Archive(BMessage *into, bool deep = true) const

Archives the BTranslatorRoster by recording its loaded add-ons in the BMessage into.

See also: `BArchivable::Archive()`, `Instantiate()` static function

### GetAllTranslators()

          virtual status_t GetAllTranslators(translator_id **outList, int32 *outCount)

Returns, in outList, an array of all the translators loaded by the BTranslationRoster. The number of elements in the array is placed in outCount. The application assumes responsibility for deallocating the array.

RETURN CODES

``

- B_NO_ERROR. Success.``
- B_NOT_INITIALIZED. Internal Translation Kit error.``
- B_BAD_VALUE. outList or outCount is `NULL`.

See also: `Identify()`, `GetTranslators()`, `GetAllTranslators()`

### GetConfigurationMessage()

          virtual status_t GetConfigurationMessage(translator_id forTranslator, BMessage *ioExtension)

Saves the current configuration information in ioExtension. This information may be flattened, unflattened, and passed to `Translate()` to configure it.

RETURN CODES

``

- B_NO_ERROR. Success.``
- B_NO_TRANSLATOR. forTranslator not a valid translator_id.``
- B_NOT_INITIALIZED. Internal Translation Kit error.``
- B_BAD_VALUE. ioExtension is `NULL`.
- Anything else. Error passed on from add-on.

See also: `GetConfigurationView()`, `Translate()`

### GetOutputFormats

### GetTranslatorInfo()

          virtual status_t GetTranslatorInfo(translator_id forTranslator, const char **outName,
             const char **outInfo, int32 *outVersion)

Returns public information about translator forTranslator. Sets outName with a short description of the translator, outInfo with a longer description, and outVersion with the translator's version number.

RETURN CODES

``

- B_NO_ERROR. Success.``
- B_NO_TRANSLATOR. forTranslator not a valid translator_id.``
- B_NOT_INITIALIZED. Internal Translation Kit error.

See also: `GetInputFormats()`, `GetOutputFormats()`

### GetTranslators()

          virtual status_t GetTranslators(BPositionIO *inSource, BMessage *ioExtension,
             translator_info **outInfo, int32 *outNumInfo,
             uint32 inHintType = 0, const char *inHintMIME = NULL,
             uint32 inWantType = 0)

Identifies the media in inSource, returning an array of valid formats and translators equipped to handle them in outInfo. outNumInfo holds the number of elements in the array. If inHintType or inHintMIME is specified, only those translators that can accept data of the specified type are searched. If inWantType is specified, only those translators that can output data of that type are searched. ioExtension offers an opportunity for the application to specify additional configuration information to the add-ons. The application assumes responsibility for deallocating the array.

RETURN CODES

``

- B_NO_ERROR. Identification of inSource was successful.``
- B_NO_TRANSLATOR. No suitable translators found.``
- B_NOT_INITIALIZED. Internal Translation Kit error.``
- B_BAD_VALUE. inSource, outInfo, or outNumInfo is `NULL`.
- Anything else. Error operating on inSource.

See also: `Identify()`, `GetAllTranslators()`

### GetInputFormats(), GetOutputFormats()

          virtual status_t GetInputFormats(translator_id forTranslator,
             const char **outFormats, const char **outNumFormats)

          virtual status_t GetOutputFormats(translator_id forTranslator,
             const char **outFormats, const char **outNumFormats)

Returns an array of the published accepted input or output formats for translator forTranslator. outNumFormats is filled with the number of elements in the array.

RETURN CODES

``

- B_NO_ERROR. Success.``
- B_NO_TRANSLATOR. forTranslator not a valid translator_id.``
- B_NOT_INITIALIZED. Internal Translation Kit error.``
- B_BAD_VALUE. outFormats or outNumFormats is `NULL`.

See also: `GetTranslatorInfo()`

### Identify()

          virtual status_t Identify(BPositionIO *inSource, BMessage *ioExtension,
             translator_info *outInfo, uint32 inHintType = 0,
             const char *inHintMIME = NULL, uint32 inWantType = 0)

Identifies the media in inSource, returning a best guess of the format and the translator best equipped to handle it in outInfo. If inHintType or inHintMIME is specified, only those translators that can accept data of the specified type are searched. If inWantType is specified, only those translators that can output data of that type are searched. ioExtension offers an opportunity for the application to specify additional configuration information to the add-ons.

If more than one translator can identify inSource, then the one with the highest quality*capability is returned.

RETURN CODES

``

- B_NO_ERROR. Identification of inSource was successful.``
- B_NO_TRANSLATOR. No suitable translator found.``
- B_NOT_INITIALIZED. Internal Translation Kit error.``
- B_BAD_VALUE. inSource or outInfo is `NULL`.
- Anything else. Error operating on inSource.

See also: `GetTranslators()`, `GetAllTranslators()`

### MakeConfigurationView()

          virtual status_t MakeConfigurationView(translator_id forTranslator, BMessage *ioExtension, BView **outView, BRect *outExtent)

Returns, in outView, a BView containing controls to configure translator forTranslator. It is the application's responsibility to attach the BView to a BWindow. The initial size of the BView is given in outExtent but may be resized by the application.

RETURN CODES

``

- B_NO_ERROR. Success.``
- B_NO_TRANSLATOR. forTranslator not a valid translator_id.``
- B_NOT_INITIALIZED. Internal Translation Kit error.``
- B_BAD_VALUE. outView or outExtent is `NULL`.
- Anything else. Error passed on from add-on.

See also: `GetConfigurationMessage()`, `Translate()`

### Translate()

          virtual status_t Translate(BPositionIO *inSource, const translator_info *inInfo,
             BMessage *ioExtension, BPositionIO *outDestination,
             uint32 inWantOutType, uint32 inHintType = 0,
             const char *inHintMIME = NULL)

          virtual status_t Translate(translator_id inTranslator, BPositionIO *inSource,
             BMessage *ioExtension, BPositionIO *outDestination,
             uint32 inWantOutType)

These two functions carry out data conversion, converting the data in inSource to type inWantoutType and placing the resulting output in outDestination. inInfo should always contain either the output of an `Identify()` call or `NULL`. The translation uses the translator identified by inInfo->infoTranslator or inTranslator as appropriate. If inInfo is `NULL`, `Translate()` will call first `Identify()` to discover the format of the input stream. ioExtension, if it is not `NULL`, provides a communication path between the translator and the application. inHintType and inHintMIME, if provided, are passed as hints to the translator.

RETURN CODES

``

- B_NO_ERROR. Success.``
- B_NO_TRANSLATOR. No suitable translators found.``
- B_NOT_INITIALIZED. Internal Translation Kit error.``
- B_BAD_VALUE. inSource or outSource is `NULL`.
- Anything else. Error passed on from add-on.

## Archived Fields

The `Archive()` function adds the following field to its BMessage argument:

Field | Type code | Meaning
"be:translator_path" (array) | `B_STRING_TYPE` | The location of the Translation Kit add-on (one field per add-on).

The Be Book, in lovely HTML, for BeOS Release 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.