Abstract class that defines the necessary functionality of a translator. More...

Inherits BArchivable.

Public Member Functions
Constructor and reference counting
	BTranslator ()
	Creates a new BTranslator and sets its reference count to 1.

BTranslator *	Acquire ()
	Increments the reference count by 1 and returns a pointer to itself.

BTranslator *	Release ()
	Decrements the reference count by 1. If the reference count is decreased to zero, the object is deleted.

int32	ReferenceCount ()
	Gets the current reference count.

Accessors
virtual const char *	TranslatorName () const =0
	Pure virtual. Returns the name of the translator.

virtual const char *	TranslatorInfo () const =0
	Pure virtual. Returns a brief description of the translator.

virtual int32	TranslatorVersion () const =0
	Pure virtual. Returns the version of the translator.

virtual const translation_format *	InputFormats (int32 *_count) const =0
	Pure virtual. Returns an array containing information about all input formats the translator can handle.

virtual const translation_format *	OutputFormats (int32 *_count) const =0
	Pure virtual. Returns an array containing information about all output formats the translator can produce.

Core methods
virtual status_t	Identify (BPositionIO source, const translation_format format, BMessage extension, translator_info info, uint32 outType)=0
	Pure virtual. Analyzes source and decides whether this translator can work with the provided format.

virtual status_t	Translate (BPositionIO source, const translator_info info, BMessage extension, uint32 outType, BPositionIO destination)=0
	Pure virtual. Reads the provided data and tries to translate it to a given format.

Configuration methods
virtual status_t	MakeConfigurationView (BMessage extension, BView _view, BRect _extent)
	Virtual. Creates a BView that contains information and configuration options for the translator.

virtual status_t	GetConfigurationMessage (BMessage *extension)
	Populates a BMessage with the settings of the translator.

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

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

Detailed Description

Abstract class that defines the necessary functionality of a translator.

BTranslator is the core class of the translation kit. Every translator defines input and output data types it can work with. A BTranslator uses BPositionIO as an abstraction for the data it operates on. It is able to decide wether incoming data is of any of its known input types and, upon successful identification, translate it to any of its output formats. It may also provide a config view that appears in the DataTranslations preference app.

Usually, a translator is very specific. It only offers translations between the format it was created for and the basic format for that media type. As an example, the translator for GIF images only translates between GIF images and bitmaps, the baseline format for images.

The function make_nth_translator enables add-ons to expose translators. Communication between applications and BTranslators is carried out by the BTranslatorRoster class.

Note: Another option to create a translator is using a BFuncTranslator.

Remarks: In most cases it is easier to derive from BaseTranslator instead of BTranslator. BaseTranslator provides a lot of functionality that is common for most translators as well as a unified method to save settings and routines for handling bitmaps.

Since: BeOS R3

Constructor & Destructor Documentation

◆ BTranslator()

BTranslator::BTranslator ( )

Creates a new BTranslator and sets its reference count to 1.

Since: BeOS R3

Member Function Documentation

◆ Acquire()

BTranslator * BTranslator::Acquire ( )

Increments the reference count by 1 and returns a pointer to itself.

Returns: this.

Since: BeOS R3

◆ GetConfigurationMessage()

status_t BTranslator::GetConfigurationMessage ( BMessage * extension )

virtual

Populates a BMessage with the settings of the translator.

A standard set of possible fields is defined in TranslatorFormats.h. This method is optional. If the translator chose not to implement it, B_ERROR will be returned.

Parameters

extension The BMessage that is populated.

Return values

B_OK	Everything went well.
B_ERROR	An error occurred or the method was not overriden by the translator.
B_BAD_VALUE	extension was `NULL`.

Since: BeOS R3

◆ Identify()

status_t BTranslator::Identify	(	BPositionIO *	source,
		const translation_format *	format,
		BMessage *	extension,
		translator_info *	info,
		uint32	outType
	)

pure virtual

Pure virtual. Analyzes source and decides whether this translator can work with the provided format.

The translator examines the data in source and tries to identify its format (for instance by checking for magic numbers). It may use the hints provided by format. If it is successful, and it is able to translate the data at hand to outType, it populates info with information about the input format and returns B_OK. If it is unable to identify the data or cannot translate it to outType, it returns B_NO_TRANSLATOR.

Parameters

source	Read and seek interface to the input data.
format	Hints about the incoming data.
extension	A message containing configuration information for the translator. A standard set of possible fields is defined in TranslatorFormats.h.
info	Where the translator will write information about the determined input format in case identification is successful.
outType	If outType is non-zero, identification will only be successful if the translator can transform the data in source to the format denoted by outType.

Warning: When creating a translator, be prepared for the information in format to be inaccurate or wrong.

Return values

B_OK	The translator has identified the data in source, has verified its ability to translate it to outType and has written information describing it to info.
B_NO_TRANSLATOR	The translator does not know how to handle the data in source or cannot translate it to outType.
B_BAD_VALUE	extension was `NULL` or contained bad data.
B_ERROR	An error occurred.

Since: BeOS R3

◆ InputFormats()

const translation_format * BTranslator::InputFormats ( int32 * _count ) const

pure virtual

Pure virtual. Returns an array containing information about all input formats the translator can handle.

Parameters

_count Where the number of input formats that are returned will be written.

Returns: A pointer to the first element of the array of input formats.

Since: BeOS R3

◆ MakeConfigurationView()

status_t BTranslator::MakeConfigurationView	(	BMessage *	extension,
		BView **	_view,
		BRect *	_extent
	)

virtual

Virtual. Creates a BView that contains information and configuration options for the translator.

This method is optional. If the translator chose not to implement it, B_ERROR will be returned.

Parameters

extension	A message containing configuration information for the translator. A standard set of possible fields is defined in TranslatorFormats.h.
_view	Where a pointer to the newly created configuration view will be stored.
_extent	Where the size of the newly created configuration view will be stored.

Return values

B_OK	Everything went well.
B_ERROR	An error occurred or the method was not overriden by the translator.
B_BAD_VALUE	_view or _extent were `NULL` or extension was `NULL` or contained bad data.

Since: BeOS R3

◆ OutputFormats()

const translation_format * BTranslator::OutputFormats ( int32 * _count ) const

pure virtual

Pure virtual. Returns an array containing information about all output formats the translator can produce.

Parameters

_count Where the number of output formats that are returned will be written.

Returns: A pointer to the first element of the array of output formats.

Since: BeOS R3

◆ ReferenceCount()

int32 BTranslator::ReferenceCount ( )

Gets the current reference count.

Returns: The current reference count.

Since: BeOS R3

◆ Release()

BTranslator * BTranslator::Release ( )

Decrements the reference count by 1. If the reference count is decreased to zero, the object is deleted.

Returns: this if the object was not destroyed, NULL if it was.

Since: BeOS R3

◆ Translate()

status_t BTranslator::Translate	(	BPositionIO *	source,
		const translator_info *	info,
		BMessage *	extension,
		uint32	outType,
		BPositionIO *	destination
	)

pure virtual

Pure virtual. Reads the provided data and tries to translate it to a given format.

The translator attempts to translate the data in source, which may or may not have the format represented by info, to outType and then write the result to destination. Upon success, it returns B_OK.

Parameters

source	Read and seek interface to the input data.
info	Hints about the incoming data.
extension	A message containing configuration information for the translator. A standard set of possible fields is defined in TranslatorFormats.h.
outType	The identifier of the desired output format. An outType of 0 is equivalent to the defualt format for the media type if the translator.
destination	Write interface for the destination of the data.

Warning: When creating a translator, be prepared for the information in format to be inaccurate or wrong.

Return values

B_OK	The translated data was successfully written to destination.
B_ERROR	An error occurred during memory allocation or the conversion itself.
B_BAD_VALUE	extension was `NULL` or contained bad data.
B_NO_TRANSLATOR	The translator cannot handle the input.

Since: BeOS R3

◆ TranslatorInfo()

const char * BTranslator::TranslatorInfo ( ) const

pure virtual

Pure virtual. Returns a brief description of the translator.

Returns: A brief description of the translator.

Since: BeOS R3

◆ TranslatorName()

const char * BTranslator::TranslatorName ( ) const

pure virtual

Pure virtual. Returns the name of the translator.

Amongst other uses, the name is used to populate Save as-dropdowns and for the preference window.

Returns: The name of the translator.

Since: BeOS R3

◆ TranslatorVersion()

int32 BTranslator::TranslatorVersion ( ) const

pure virtual

Pure virtual. Returns the version of the translator.

The correct way to format the version is using the B_TRANSLATION_MAKE_VERSION macro from TranslationDefs.h.

Returns: The version of the translator.

Since: BeOS R3

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BTranslator()

Member Function Documentation

◆ Acquire()

◆ GetConfigurationMessage()

◆ Identify()

◆ InputFormats()

◆ MakeConfigurationView()

◆ OutputFormats()

◆ ReferenceCount()

◆ Release()

◆ Translate()

◆ TranslatorInfo()

◆ TranslatorName()

◆ TranslatorVersion()