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.

status_t	AddTranslator (BTranslator *translator)
	Adds a single BTranslator to the roster.

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.

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.

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.

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.

virtual status_t	GetAllTranslators (translator_id *_list, int32 _count)
	Collects the IDs of all translators in the roster in an array.

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.

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.

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.

virtual status_t	MakeConfigurationView (translator_id translatorID, BMessage ioExtension, BView _view, BRect _extent)
	Creates the configuration view of a specified translator from the roster.

virtual status_t	GetConfigurationMessage (translator_id translatorID, BMessage *ioExtension)
	Populates a BMessage with the settings of the specified translator.

status_t	GetRefFor (translator_id translatorID, entry_ref *ref)
	Returns the entry_ref of the specified translator.

Miscellaneous
bool	IsTranslator (entry_ref *ref)
	Determines whether the specified add-on contains at least one translator.

Notifications
status_t	StartWatching (BMessenger target)
	Register a messenger to be notified when the roster changes.

status_t	StopWatching (BMessenger target)
	Unregister a messenger from the notification list.

Public Member Functions inherited from BArchivable
	BArchivable ()
	Constructor. Does nothing.

	BArchivable (BMessage *from)
	Constructor. Does important behind-the-scenes work in the unarchiving process.

virtual	~BArchivable ()
	Destructor. Does nothing.

virtual status_t	AllArchived (BMessage *archive) const
	Method relating to the use of `BArchiver`.

virtual status_t	AllUnarchived (const BMessage *archive)
	Method relating to the use of `BUnarchiver`.

virtual status_t	Archive (BMessage *into, bool deep=true) const
	Archive the object into a BMessage.

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.

	BTranslatorRoster (BMessage *model)
	Constructs a BTranslatorRoster and fills it.

virtual	~BTranslatorRoster ()
	Deletes this BTranslatorRoster.

static BTranslatorRoster *	Default ()
	Gets the default BTranslatorRoster.

Archiving
virtual status_t	Archive (BMessage *into, bool deep=true) const
	Archive this BTranslatorRoster into a BMessage.

static BArchivable *	Instantiate (BMessage *from)
	Creates a new BTranslatorRoster from a message.

Additional Inherited Members
Static Public Member Functions inherited from BArchivable
static BArchivable *	Instantiate (BMessage *archive)
	Static member to restore objects from messages.

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

model A 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

translator The 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_OK	The translator was successfully added to the roster.
B_NO_MEMORY	There was no memory to enlarge the roster.
B_BAD_VALUE	translator was `NULL`.

◆ AddTranslators()

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

Adds translators from a directory to the roster.

Parameters

loadPath A 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

into	Where the BTranslatorRoster will be stored.
deep	Unused.

Return values

B_OK	The operation was successful.
B_BAD_VALUE	into was NULL.
B_ERROR	The 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

_list	Where the resulting array will be stored.
_count	Where 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_MEMORY	Could 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

translatorID	The ID of the translator whose settings ioExtension should be populated with.
ioExtension	The message that should be populated.

Return values

B_OK	ioExtension was populated successfully.
B_NO_TRANSLATOR	The roster does not contain any translator with the ID translatorID.
B_BAD_VALUE	ioExtension was `NULL`.
B_ERROR	An 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

translatorID	The ID of the translator whose input formats are requested.
_formats	Where the array of input formats will be stored.
_numFormats	Where 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_TRANSLATOR	The 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

translatorID	The ID of the translator whose output formats are requested.
_formats	Where the array of output formats will be stored.
_numFormats	Where 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_TRANSLATOR	The 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

translatorID	The ID of the translator whose entry_ref is to be found.
ref	Where the entry_ref will be written.

Return values

B_OK	Everything went well.
B_BAD_VALUE	ref was `NULL`.
B_NO_TRANSLATOR	The roster does not contain any translator with the ID translatorID.
B_ERROR	An 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

translatorID	The ID of the translator whose information is requested.
_name	Where the name of the translator will be stored.
_info	Where the description of the translator will be stored.
_version	Where 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_OK	All non-null pointers were written to successfully.
B_BAD_VALUE	All three pointers were `NULL`.
B_NO_TRANSLATOR	The 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

source	Read and seek interface to the data to be examinded.
ioExtension	A message containing configuration information for the translators.
_info	Where the resulting array will be stored.
_numInfo	Where the number of elements in the resulting array will be stored.
hintType	A hint about the data format in source. `0` represents an unknown type.
hintMIME	A hint about the MIME type of source. `NULL` represents an unknown type.
wantType	The 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_TRANSLATOR	No suitable translator was found.
B_BAD_VALUE	source, _info or _numInfo was `NULL`.
B_IO_ERROR	There was an error interacting with source.
B_NO_MEMORY	Could 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

source	Read and seek interface to the data to be examined.
ioExtension	A message containing configuration infortmation for the translators.
_info	Where information about the best translator will be written.
hintType	A hint about the data format in source. `0` represents an unknown type.
hintMIME	A hint about the MIME type of source. `NULL` represents an unknown type.
wantType	The 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_OK	Identification was successful. Information about the chosen translator was written to _info.
B_NO_TRANSLATOR	No suitable translator was found.
B_BAD_VALUE	source or _info was `NULL`.
B_IO_ERROR	There was an error interacting with source.

◆ Instantiate()

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

static

Creates a new BTranslatorRoster from a message.

Parameters

from	The 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

ref	The entry_ref to be tested.

Return values

true	The add-on exposes translators.
false	The 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

translatorID	The ID of the translator whose configuration view should be created.
ioExtension	A message containing configuration information for the translator.
_view	Where a pointer to the newly created configuration view will be stored.
_extent	Where the size of of the newly created configuration view will be stored.

Return values

B_OK	Everything went well.
B_BAD_VALUE	_view or _extent were `NULL` or ioExtension was `NULL` or contained bad data.
B_NO_TRANSLATOR	The roster does not contain any translator with the ID translatorID.
B_ERROR	An 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

target The 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_OK	target was successfully registered.
B_NO_MEMORY	Unable to allocate more memory for the list of targets.

◆ StopWatching()

status_t BTranslatorRoster::StopWatching ( BMessenger target )

Unregister a messenger from the notification list.

Parameters

target The BMessenger to be removed.

Return values

B_OK	target was successfully unsubscribed.
B_BAD_VALUE	target 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

source	Read and seek interface to the input data.
info	Information about wich translator should be used. If info is `NULL`, Identify() will be used to find a suitable translator.
ioExtension	A message containing configuration information for the translator.
destination	Write interface to the output location.
wantOutType	The desired output format. If this is `0`, any type is permitted.
hintType	A hint about the type of the data in source.
hintMIME	A hint about the MIME type of the data in source.

Return values

B_OK	The translated data was successfully written to destination.
B_NO_TRANSLATOR	When info was non-null, it did not match to any translator in the roster. If info was `NULL`, then no suitable translator was found.
B_ERROR	An error occurred.
B_BAD_VALUE	source or destination was `NULL` or ioExtension was `NULL` or contained bad data.
B_IO_ERROR	An 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

translatorID	The ID of the translator that should be used.
source	Read and seek interface to the input data.
ioExtension	A message containing configuration information for the translator.
destination	Write interface to the output location.
wantOutType	The desired output format. If this is `0`, any type is permitted.

Return values

B_OK	The translated data was successfully written to destination.
B_NO_TRANSLATOR	The specified translator cannot handle the data in source.
B_ERROR	An error occurred.
B_BAD_VALUE	source or destination was `NULL` or ioExtension was `NULL` or contained bad data.
B_IO_ERROR	An error occurred accessing source or destination.

Public Member Functions

Constructors and Destructor

Archiving

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BTranslatorRoster() [1/2]

◆ BTranslatorRoster() [2/2]

◆ ~BTranslatorRoster()

Member Function Documentation

◆ AddTranslator()

◆ AddTranslators()

◆ Archive()

◆ Default()

◆ GetAllTranslators()

◆ GetConfigurationMessage()

◆ GetInputFormats()

◆ GetOutputFormats()

◆ GetRefFor()

◆ GetTranslatorInfo()

◆ GetTranslators()

◆ Identify()

◆ Instantiate()

◆ IsTranslator()

◆ MakeConfigurationView()

◆ StartWatching()

◆ StopWatching()

◆ Translate() [1/2]

◆ Translate() [2/2]