The Be Book The Translation Kit The Translation Kit Index

BTranslatorRoster

Derived from: (none)
Mix-in classes: BArchivable
Declared in:  be/translation/TranslatorRoster.h
Library: libtranslation.so
Summary:  more...


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:

translator_info defines an additional field:

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);

The Translation Kit won't chain translators for you. If you want to translate from GIF to PNG, you either need a translator that can convert GIF to PNG, or you need to perform two translations: one from GIF to an interchange format, then another from that format to PNG.

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
B_TRANSLATOR_EX T_HEADER_ONLY bool app to translator Only output header if true
B_TRANSLATOR_EX T_DATA_ONLY bool app to translator Only output data if true
B_TRANSLATOR_EX T_COMMENT string n/a Text comment about data.
B_TRANSLATOR_EX T_TIME 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.
B_TRANSLATOR_EX T_FRAME uint32 app to translator Same as kTimeExtension, except the unit of time is frames.
B_TRANSLATOR_EX T_BITMAP_RECT BRect app to translator Specifies subsection of a bitmap.
B_TRANSLATOR_EX T_BITMAP_COLOR_SPACE uint32 both Specifies desired/actual color space of bitmap.
B_TRANSLATOR_EX T_SOUND_CHANNEL uint32 app to translator Only output specified channel of sound.
B_TRANSLATOR_EX T_SOUND_MONO bool app to translator Mix all audio channels to a single mono channel if true.
B_TRANSLATOR_EX T_SOUND_MARKER 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.
B_TRANSLATOR_EX T_SOUND_LOOP 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 BTranslatorRoster loaded with the 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

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

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

GetConfigurationMessage()

virtual status_t GetConfigurationMessage(translator_id forTranslator, BMessage *ioExtension)

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

RETURN CODES

See also: GetConfigurationView(), Translate()

GetInputFormats() , GetOutputFormats()

virtual status_t GetInputFormats(translator_id forTranslator,
      const translation_format **outFormats,
      int32 *outNumFormats)
virtual status_t GetOutputFormats(translator_id forTranslator,
      const translation_format **outFormats,
      int32 *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

See also: GetTranslatorInfo()

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

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

See also: Identify(), GetAllTranslators()

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

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

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

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 The Translation Kit The Translation Kit Index

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

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