List of all members
BTranslatorRoster Class Reference

Class that serves as an interface between applications and translators. More...

Inherits BArchivable.

Public Member Functions

Roster Management
status_t AddTranslators (const char *loadPath=NULL)
 Adds translators from a directory to the roster. More...
 
status_t AddTranslator (BTranslator *translator)
 Adds a single BTranslator to the roster. More...
 
Core Methods
virtual status_t Identify (BPositionIO *source, BMessage *ioExtension, translator_info *_info, uint32 hintType=0, const char *hintMIME=NULL, uint32 wantType=0)
 Determines the best translator in the roster to perform a certain conversion. More...
 
virtual status_t Translate (BPositionIO *source, const translator_info *info, BMessage *ioExtension, BPositionIO *destination, uint32 wantOutType, uint32 hintType=0, const char *hintMIME=NULL)
 Finds and invokes the best translator for a conversion. More...
 
virtual status_t Translate (translator_id translatorID, BPositionIO *source, BMessage *ioExtension, BPositionIO *destination, uint32 wantOutType)
 Uses a specified translator from the roster to perform a conversion. More...
 
Translator Access
virtual status_t GetTranslators (BPositionIO *source, BMessage *ioExtension, translator_info **_info, int32 *_numInfo, uint32 hintType=0, const char *hintMIME=NULL, uint32 wantType=0)
 Collects information about all translators that are able to perform a certain conversion in an array. More...
 
virtual status_t GetAllTranslators (translator_id **_list, int32 *_count)
 Collects the IDs of all translators in the roster in an array. More...
 
virtual status_t GetTranslatorInfo (translator_id translatorID, const char **_name, const char **_info, int32 *_version)
 Looks up general information of the translator with a given ID. More...
 
virtual status_t GetInputFormats (translator_id translatorID, const translation_format **_formats, int32 *_numFormats)
 Looks up the input formats of the translator with a given ID. More...
 
virtual status_t GetOutputFormats (translator_id translatorID, const translation_format **_formats, int32 *_numFormats)
 Looks up the output formats of the translator with a given ID. More...
 
virtual status_t MakeConfigurationView (translator_id translatorID, BMessage *ioExtension, BView **_view, BRect *_extent)
 Creates the configuration view of a specified translator from the roster. More...
 
virtual status_t GetConfigurationMessage (translator_id translatorID, BMessage *ioExtension)
 Populates a BMessage with the settings of the specified translator. More...
 
status_t GetRefFor (translator_id translatorID, entry_ref *ref)
 Returns the entry_ref of the specified translator. More...
 
Miscellaneous
bool IsTranslator (entry_ref *ref)
 Determines whether the specified add-on contains at least one translator. More...
 
Notifications
status_t StartWatching (BMessenger target)
 Register a messenger to be notified when the roster changes. More...
 
status_t StopWatching (BMessenger target)
 Unregister a messenger from the notification list. More...
 
- Public Member Functions inherited from BArchivable
 BArchivable (BMessage *from)
 Constructor. Does important behind-the-scenes work in the unarchiving process. More...
 
 BArchivable ()
 Constructor. Does nothing. More...
 
virtual ~BArchivable ()
 Destructor. Does nothing. More...
 
virtual status_t AllArchived (BMessage *archive) const
 Method relating to the use of BArchiver. More...
 
virtual status_t AllUnarchived (const BMessage *archive)
 Method relating to the use of BUnarchiver. More...
 
virtual status_t Perform (perform_code d, void *arg)
 Perform some action (Internal method defined for binary compatibility purposes).
 

Constructors and Destructor

 BTranslatorRoster ()
 Constructs an empty BTranslatorRoster. More...
 
 BTranslatorRoster (BMessage *model)
 Constructs a BTranslatorRoster and fills it. More...
 
virtual ~BTranslatorRoster ()
 Deletes this BTranslatorRoster. More...
 
static BTranslatorRosterDefault ()
 Gets the default BTranslatorRoster. More...
 

Archiving

virtual status_t Archive (BMessage *into, bool deep=true) const
 Archive this BTranslatorRoster into a BMessage. More...
 
static BArchivableInstantiate (BMessage *from)
 Creates a new BTranslatorRoster from a message. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from BArchivable
static BArchivableInstantiate (BMessage *archive)
 Static member to restore objects from messages. More...
 

Detailed Description

Class that serves as an interface between applications and translators.

BTranslatorRoster gives applications access to the translation kit. Applications can request translations and BTranslatorRoster will automatically search for a matching translator and have it perfrom the translation.

Warning
BTranslatorRoster does not perform chaining of any sort. Only translations that can be made by invoking a single translator are supported.
Note
BTranslationUtils provides some helper methods that perform the interaction with BTranslatorRoster for you.

BTranslationRoster acts as a container. While in most cases the default roster is used, it is possible to create a roster that interacts with a custom set of translators.

Constructor & Destructor Documentation

◆ BTranslatorRoster() [1/2]

BTranslatorRoster::BTranslatorRoster ( )

Constructs an empty BTranslatorRoster.

Warning
Only call the contructor if you want to use a custom collection of translators. Use Default() if you don't.

◆ BTranslatorRoster() [2/2]

BTranslatorRoster::BTranslatorRoster ( BMessage model)

Constructs a BTranslatorRoster and fills it.

Parameters
modelA message that contains information about a BTranslatorRoster.

After initialization, model is searched for strings with the name "be:translator_path". The translators that are located at each path are added to the roster. If multiple paths point to translators with the same name, the translator at the path with the lowest index within the message will be kept.

Warning
Use Instantiate() instead of this constructor if model was created using Archive().

◆ ~BTranslatorRoster()

BTranslatorRoster::~BTranslatorRoster ( )
virtual

Deletes this BTranslatorRoster.

If the BTranslatorRoster that is deleted is the default roster, a new default roster will be created when BTranslatorRoster::Default() is called for the next time.

Release() is called on all translators in the roster.

Member Function Documentation

◆ AddTranslator()

status_t BTranslatorRoster::AddTranslator ( BTranslator translator)

Adds a single BTranslator to the roster.

Parameters
translatorThe translator that should be added.
Remarks
AddTranslator() calls Acquire() on the translator, so it is safe to release it if you had acquired it before.
Return values
B_OKThe translator was successfully added to the roster.
B_NO_MEMORYThere was no memory to enlarge the roster.
B_BAD_VALUEtranslator was NULL.

◆ AddTranslators()

status_t BTranslatorRoster::AddTranslators ( const char *  loadPath = NULL)

Adds translators from a directory to the roster.

Parameters
loadPathA colon-separated list of directories to search for translators in.

The following method is used to determine which translators to add:

If loadPath is not NULL, the roster will be populated with all translators that are present in the directores denoted by loadPath. The paths are separated by a colon (:). If multiple paths contain a translator with the same name, the translator that is located in the path that appears earliest in loadPath will be kept.

If loadPath is NULL and the environment variable TRANSLATORS is set, it will be populated with all translators that are present in the directories denoted by TRANSLATORS. The paths are separated by a colon (:). If multiple paths contain a translator with the same name, the translator that is located in the path that appears earliest in TRANSLATORS will be kept.

If loadPath is NULL and TRANSLATORS is unset, the user non-packaged add-ons directory, the user add-ons directory, the system non-packaged add-ons directory and the system add-ons directory will be used. If those directories do not contain a subdirectory Translators, it will be created. The subdirectories are then added in the above order. If multiple directories contain a translator with the same name, the translator that is located in the path that appears earliest in the above list will be kept.

Returns
B_OK if everything went well, an error code specific to the operation that failed otherwise.

◆ Archive()

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

Archive this BTranslatorRoster into a BMessage.

Parameters
intoWhere the BTranslatorRoster will be stored.
deepUnused.
Return values
B_OKThe operation was successful.
B_BAD_VALUEinto was NULL.
B_ERRORThe operation failed.

Reimplemented from BArchivable.

◆ Default()

static BTranslatorRoster * BTranslatorRoster::Default ( )
static

Gets the default BTranslatorRoster.

At any point, there is only one default roster. It is created when this method is called for the first time (possibly after being deleted) and is populated according to the following rules:

If the environment variable TRANSLATORS is set, the default roster will be populated with all translators that are present in the directories denoted by TRANSLATORS. The paths are separated by a colon (:). If multiple paths contain a translator with the same name, the translator that is located in the path that appears earliest in TRANSLATORS will be kept.

If TRANSLATORS is not set, the user non-packaged add-ons directory, the user add-ons directory, the system non-packaged add-ons directory and the system add-ons directory will be used. If those directories do not contain a subdirectory Translators, it will be created. The subdirectories are then added in the above order. If multiple directories contain a translator with the same name, the translator that is located in the path that appears earliest in the above list will be kept.

◆ GetAllTranslators()

status_t BTranslatorRoster::GetAllTranslators ( translator_id **  _list,
int32 *  _count 
)
virtual

Collects the IDs of all translators in the roster in an array.

Parameters
_listWhere the resulting array will be stored.
_countWhere the number of elements in the resulting array will be stored.

If this function returns B_OK the caller has to call delete[] when they are done using _info.

Return values
B_OK_list and _count were populated successfully.
B_NO_MEMORYCould not allocate the memory for the array.

◆ GetConfigurationMessage()

status_t BTranslatorRoster::GetConfigurationMessage ( translator_id  translatorID,
BMessage ioExtension 
)
virtual

Populates a BMessage with the settings of the specified translator.

Parameters
translatorIDThe ID of the translator whose settings ioExtension should be populated with.
ioExtensionThe message that should be populated.
Return values
B_OKioExtension was populated successfully.
B_NO_TRANSLATORThe roster does not contain any translator with the ID translatorID.
B_BAD_VALUEioExtension was NULL.
B_ERRORAn error occurred or the translator chose not to provide this functionality.

◆ GetInputFormats()

status_t BTranslatorRoster::GetInputFormats ( translator_id  translatorID,
const translation_format **  _formats,
int32 *  _numFormats 
)
virtual

Looks up the input formats of the translator with a given ID.

Parameters
translatorIDThe ID of the translator whose input formats are requested.
_formatsWhere the array of input formats will be stored.
_numFormatsWhere the number of elements in the array of input formats will be stored.

Do not free any of the returned data.

Return values
B_OK_formats and _numFormats were successfully set.
B_BAD_VALUE_formats or _numFormats was NULL.
B_NO_TRANSLATORThe roster does not contain any translator with the ID translatorID.

◆ GetOutputFormats()

status_t BTranslatorRoster::GetOutputFormats ( translator_id  translatorID,
const translation_format **  _formats,
int32 *  _numFormats 
)
virtual

Looks up the output formats of the translator with a given ID.

Parameters
translatorIDThe ID of the translator whose output formats are requested.
_formatsWhere the array of output formats will be stored.
_numFormatsWhere the number of elements in the array of output formats will be stored.

Do not free any of the returned data.

Return values
B_OK_formats and _numFormats were successfully set.
B_BAD_VALUE_formats or _numFormats was NULL.
B_NO_TRANSLATORThe roster does not contain any translator with the ID translatorID.

◆ GetRefFor()

status_t BTranslatorRoster::GetRefFor ( translator_id  translatorID,
entry_ref ref 
)

Returns the entry_ref of the specified translator.

Parameters
translatorIDThe ID of the translator whose entry_ref is to be found.
refWhere the entry_ref will be written.
Return values
B_OKEverything went well.
B_BAD_VALUEref was NULL.
B_NO_TRANSLATORThe roster does not contain any translator with the ID translatorID.
B_ERRORAn error occurred.

◆ GetTranslatorInfo()

status_t BTranslatorRoster::GetTranslatorInfo ( translator_id  translatorID,
const char **  _name,
const char **  _info,
int32 *  _version 
)
virtual

Looks up general information of the translator with a given ID.

Parameters
translatorIDThe ID of the translator whose information is requested.
_nameWhere the name of the translator will be stored.
_infoWhere the description of the translator will be stored.
_versionWhere the version of the translator will be stored.

Do not free any returned data. If any of _name, _info and _version are NULL, the non-null pointers will still be written to.

Return values
B_OKAll non-null pointers were written to successfully.
B_BAD_VALUEAll three pointers were NULL.
B_NO_TRANSLATORThe roster does not contain any translator with the ID translatorID.

◆ GetTranslators()

status_t BTranslatorRoster::GetTranslators ( BPositionIO source,
BMessage ioExtension,
translator_info **  _info,
int32 *  _numInfo,
uint32  hintType = 0,
const char *  hintMIME = NULL,
uint32  wantType = 0 
)
virtual

Collects information about all translators that are able to perform a certain conversion in an array.

Parameters
sourceRead and seek interface to the data to be examinded.
ioExtensionA message containing configuration information for the translators.
_infoWhere the resulting array will be stored.
_numInfoWhere the number of elements in the resulting array will be stored.
hintTypeA hint about the data format in source. 0 represents an unknown type.
hintMIMEA hint about the MIME type of source. NULL represents an unknown type.
wantTypeThe format that source needs to be translated into. 0 permits any output type.

If this function returns B_OK the caller has to call delete[] when they are done using _info.

Return values
B_OK_info and _numInfo were successfully populated.
B_NO_TRANSLATORNo suitable translator was found.
B_BAD_VALUEsource, _info or _numInfo was NULL.
B_IO_ERRORThere was an error interacting with source.
B_NO_MEMORYCould not allocate enough memory for the array.

◆ Identify()

status_t BTranslatorRoster::Identify ( BPositionIO source,
BMessage ioExtension,
translator_info *  _info,
uint32  hintType = 0,
const char *  hintMIME = NULL,
uint32  wantType = 0 
)
virtual

Determines the best translator in the roster to perform a certain conversion.

Parameters
sourceRead and seek interface to the data to be examined.
ioExtensionA message containing configuration infortmation for the translators.
_infoWhere information about the best translator will be written.
hintTypeA hint about the data format in source. 0 represents an unknown type.
hintMIMEA hint about the MIME type of source. NULL represents an unknown type.
wantTypeThe format that source needs to be translated into. 0 permits any output type.

To determine the best translator, for all translators that report that they are able to perform the translation, the values they return for quality and capability are multiplied. The translator with the highest value gets returned. Note that quality and capability for the output format are not taken into consideration.

Return values
B_OKIdentification was successful. Information about the chosen translator was written to _info.
B_NO_TRANSLATORNo suitable translator was found.
B_BAD_VALUEsource or _info was NULL.
B_IO_ERRORThere was an error interacting with source.

◆ Instantiate()

static BArchivable * BTranslatorRoster::Instantiate ( BMessage from)
static

Creates a new BTranslatorRoster from a message.

Parameters
fromThe message that contains information about a BTranslatorRoster.
Returns
NULL if from was NULL, contained invalid archive data or archive data of a class that is not BTranslatorRoster. A pointer to a new BTranslatorRoster containing the information from from otherwise.

◆ IsTranslator()

bool BTranslatorRoster::IsTranslator ( entry_ref ref)

Determines whether the specified add-on contains at least one translator.

Parameters
refThe entry_ref to be tested.
Return values
trueThe add-on exposes translators.
falseThe add-on exposes no translators or an error occurred.

◆ MakeConfigurationView()

status_t BTranslatorRoster::MakeConfigurationView ( translator_id  translatorID,
BMessage ioExtension,
BView **  _view,
BRect _extent 
)
virtual

Creates the configuration view of a specified translator from the roster.

Parameters
translatorIDThe ID of the translator whose configuration view should be created.
ioExtensionA message containing configuration information for the translator.
_viewWhere a pointer to the newly created configuration view will be stored.
_extentWhere the size of of the newly created configuration view will be stored.
Return values
B_OKEverything went well.
B_BAD_VALUE_view or _extent were NULL or ioExtension was NULL or contained bad data.
B_NO_TRANSLATORThe roster does not contain any translator with the ID translatorID.
B_ERRORAn error occurred or the translator chose not to supply a configuration view.

◆ StartWatching()

status_t BTranslatorRoster::StartWatching ( BMessenger  target)

Register a messenger to be notified when the roster changes.

Parameters
targetThe BMessenger to be registered.

Whenever a translator is added to or removed from the roster, all messengers that were registered through this method are sent a message. message->what will be B_TRANSLATOR_ADDED or B_TRANSLATOR_REMOVED (as defined in AppDefs.h) respectively.

Return values
B_OKtarget was successfully registered.
B_NO_MEMORYUnable to allocate more memory for the list of targets.

◆ StopWatching()

status_t BTranslatorRoster::StopWatching ( BMessenger  target)

Unregister a messenger from the notification list.

Parameters
targetThe BMessenger to be removed.
Return values
B_OKtarget was successfully unsubscribed.
B_BAD_VALUEtarget could not be found on the notification list.
See also
StartWatching(BMessenger target)

◆ Translate() [1/2]

status_t BTranslatorRoster::Translate ( BPositionIO source,
const translator_info *  info,
BMessage ioExtension,
BPositionIO destination,
uint32  wantOutType,
uint32  hintType = 0,
const char *  hintMIME = NULL 
)
virtual

Finds and invokes the best translator for a conversion.

Parameters
sourceRead and seek interface to the input data.
infoInformation about wich translator should be used. If info is NULL, Identify() will be used to find a suitable translator.
ioExtensionA message containing configuration information for the translator.
destinationWrite interface to the output location.
wantOutTypeThe desired output format. If this is 0, any type is permitted.
hintTypeA hint about the type of the data in source.
hintMIMEA hint about the MIME type of the data in source.
Return values
B_OKThe translated data was successfully written to destination.
B_NO_TRANSLATORinfo was non-null but did not match to any translator in the roster.
B_NO_TRANSLATORinfo was NULL and no suitable translator was found.
B_ERRORAn error occurred.
B_BAD_VALUEsource or destination was NULL or ioExtension was NULL or contained bad data.
B_IO_ERRORAn error occurred accessing source or destination.

◆ Translate() [2/2]

status_t BTranslatorRoster::Translate ( translator_id  translatorID,
BPositionIO source,
BMessage ioExtension,
BPositionIO destination,
uint32  wantOutType 
)
virtual

Uses a specified translator from the roster to perform a conversion.

Parameters
translatorIDThe ID of the translator that should be used.
sourceRead and seek interface to the input data.
ioExtensionA message containing configuration information for the translator.
destinationWrite interface to the output location.
wantOutTypeThe desired output format. If this is 0, any type is permitted.
Return values
B_OKThe translated data was successfully written to destination.
B_NO_TRANSLATORThe specified translator cannot handle the data in source.
B_ERRORAn error occurred.
B_BAD_VALUEsource or destination was NULL or ioExtension was NULL or contained bad data.
B_IO_ERRORAn error occurred accessing source or destination.