The Translation Kit: Translator Add-ons

The Translation Kit Table of Contents | The Translation Kit Index

# Translator Add-ons

Declared in: be/translation/TranslatorAddOn.h

Library: libtranslation.so

This section describes the functions and data that a translator add-on must (or can) supply. The translator add-ons that you create and install are loaded into a BTranslatorRoster object through its `Default()` or `AddTranslators()` function.

You compile your add-on as a shared library, link against libtranslation.so, and install the add-on object file in the Translators subdirectory of `B_USER_ADDONS_DIRECTORY`.

The table below briefly lists the translator add-on symbols:

Symbol | Required? | Description
--- | --- | ---
`translatorInfo` | yes | long description of translator
`translatorName` | yes | short name of translator
`translatorVersion` | yes | translator version number
`Identify()` | yes | identify data in a BPositionIO
`Translate()` | yes | translate data from one format to another
`inputFormats` | no | list of supported input formats
`outputFormats` | no | list of supported output formats
`GetConfigMessage()` | no | save current configuration in a BMessage
`MakeConfig()` | no | create a view for user-configuration of translator

## Translator Add-on Functions

### GetConfigMessage()

status_t `GetConfigMessage(` BMessage *ioExtension`) `

| Optional

This function stores the current configuration in the ioExtension in such a manner that it may be flattened, unflattened, and then passed to `Translate()` as an ioExtension.

### Identify()

status_t `Identify(`BPositionIO *inSource,
const translation_format *inFormat,
BMessage *ioExtension,
translator_info *outInfo,
uint32 outType`)

`

| Required

If the translator understands how to convert the data contained in inSource to media type outType, it fills outInfo with details about the input format and return `B_OK`. If it doesn't know how to translate the data, it returns `B_NO_TRANSLATOR`.

The quality and capability fields in outInfo are used by the Translation Kit in selecting the best suited translator for a given translation, so it is best to be conservative in choosing these values.

If the media format doesn't have a type code in <be/support/TypeConstants.h> (as will most likely be the case), choose a reasonable value. For example, the Targa handler included with the BeOS distribution uses the type code 'TGA '.

The translator need not fill in the translator field in outInfo; BTranslatorRoster fills in this value for you.

Remember that inSource may be arriving from any source, including a live network feed. It's therefore best to steer clear of calls such as `BPositionIO::Size()` which force all the data out of the stream. Similarly, it is good practice to read only as much of the stream as you need.

inFormat, if it is not `NULL`, is provided as a hint to the format of the data in inSource. Since it is only a hint, the data may very well be in some other format.

ioExtension, if it is not `NULL`, contains additional information for the add-on. It is described at length in the section in BTranslatorRoster titled "Configuration".

outType may be zero, in which case any output format is acceptable.

### MakeConfig()

status_t `MakeConfig(` BMessage *ioExtension, BView **outView, BRect *outExtent`) `

| Optional

This function creates a new BView through which the user configures the add-on. For example, it could be used to control the degree of image compression used or the video frame rate. The bounds of the view are returned in outExtent, although it can be resized at will by an external source. Changes to the configuration take effect immediately, although translations should be carried out with the same parameters throughout.

### Translate()

status_t `Translate(`BPositionIO *inSource,
const translator_info *inInfo,
BMessage *ioExtension,
uint32 outType,
BPositionIO *outDestination`)

`

| Required

The translator translates data from inSource to format outType, writing the output to outDestination. outType may be zero, in which case it is assumed to be the default format type for the media group. As in `Identify()`, inInfo serves as a hint to the format of the data in inSource. ioExtension fills its usual role as a container of configuration information. The function returns `B_OK` if it's able to convert the data successfully. If it's unable to do so, it returns either `B_NO_TRANSLATOR` or an error value as appropriate.

## Translator Add-on Data

### inputFormats , outputFormats

translation_format `inputFormats`[];
translation_format `outputFormats`[];

| Optional

These arrays tell BTranslatorRoster which formats the add-on supports. If they are not exported by the translator, the add-on's `Identify()` will be called each time an application requests a translation. Each array ends in an empty `translation_format` structure, so a typical inputFormats would look like:

       translation_format inputFormats[] = {
          { 'TGA ', B_TRANSLATOR_BITMAP, 0.6, 0.5, "image/targa",
            "Targa bitmap format" },
          { B_TRANSLATOR_BITMAP, B_TRANSLATOR_BITMAP, 0.4, 0.6, "image/x-be-bitmap",
            "Be Bitmap format" },
          { 0, 0, 0, 0, 0, 0 }
       };

and similarly for outputFormats.

### translatorInfo , translatorName , translatorVersion

char `translatorInfo`[];
char `translatorName`[];
int32 `translatorVersion`;

| Required

`translatorInfo` returns a pointer to the translator's long name, e.g. "aiff translator by the Pie Man (pie@the.man)".

`translatorName` returns a pointer to the translator's short name, e.g. "aiff translator". The short name should be appropriate for display in a menu.

`translatorVersion` gives an "MM.mm" version number for the translator. For example, a `TranslatorVersion()` of 314 is interpreted as version 3.14.

The Translation Kit Table of Contents | The Translation Kit Index

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

Copyright © 2000 Be, Inc. All rights reserved..