haiku/docs/user/translation/Translator.dox

/*
 * Copyright 2014-2015 Markus Himmel. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Markus Himmel, markus@himmel-villmar.de
 *
 * Corresponds to:
 *		headers/os/translation/Translator.h	hrev48573
 *		src/kits/translation/Translator.cpp	hrev48573
 */

/*!
	\file Translator.h
	\ingroup translation
	\ingroup libtranslation
	\brief BTranslator class definition.
*/

/*!
	\file TranslationDefs.h
	\ingroup translation
	\ingroup libtranslation
	\brief Defines structures and preprocessor macros that are used by the
		translation kit.
*/

/*!
	\file TranslatorFormats.h
	\ingroup translation
	\ingroup libtranslation
	\brief Defines identifiers and structures for data formats and configuration
		messages.
*/

/*!
	\class BTranslator
	\ingroup translation
	\ingroup libtranslation
	\brief 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 \c 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.

	\remark 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
*/

/*!
	\name Constructor and reference counting
*/

//! @{

/*!
	\fn BTranslator::BTranslator()
	\brief Creates a new BTranslator and sets its reference count to 1.

	\since BeOS R3
*/

/*!
	\fn BTranslator* BTranslator::Acquire()
	\brief Increments the reference count by 1 and returns a pointer to
		itself.

	\returns \c this.

	\since BeOS R3
*/

/*!
	\fn BTranslator* BTranslator::Release()
	\brief Decrements the reference count by 1. If the reference count is
		decreased to zero, the object is deleted.

	\returns \c this if the object was not destroyed, \c NULL if it was.

	\since BeOS R3
*/

/*!
	\fn int32 BTranslator::ReferenceCount()
	\brief Gets the current reference count.

	\returns The current reference count.

	\since BeOS R3
*/

//! @}

/*!
	\name Accessors
*/

//! @{

/*!
	\fn virtual const char* BTranslator::TranslatorName() const = 0
	\brief 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
*/

/*!
	\fn virtual const char* BTranslator::TranslatorInfo() const = 0
	\brief Pure virtual. Returns a brief description of the translator.

	\returns A brief description of the translator.

	\since BeOS R3
*/

/*!
	\fn virtual int32 BTranslator::TranslatorVersion() const = 0
	\brief Pure virtual. Returns the version of the translator.

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

	\returns The version of the translator.

	\since BeOS R3
*/

/*!
	\fn virtual const translation_format*\
		BTranslator::InputFormats(int32* _count) const = 0
	\brief Pure virtual. Returns an array containing information about all
		input formats the translator can handle.

	\param _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
*/

/*!
	\fn virtual const translation_format*\
		BTranslator::OutputFormats(int32* _count) const = 0
	\brief Pure virtual. Returns an array containing information about all
		output formats the translator can produce.

	\param _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
*/

//! @}

/*!
	\name Core methods
*/

//! @{

/*!
	\fn virtual status_t BTranslator::Identify(BPositionIO* source, const\
		translation_format* format, BMessage* extension, translator_info* info,\
		uint32 outType) = 0;
	\brief Pure virtual. Analyzes \a 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 \a format. If it is successful, and it is able to translate the data at
	hand to \a outType, it populates \a info with information about the input
	format and returns \c B_OK. If it is unable to identify the data or cannot
	translate it to \a outType, it returns \c B_NO_TRANSLATOR.

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

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

	\since BeOS R3
*/

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

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

	\param source Read and seek interface to the input data.
	\param info Hints about the incoming data.
	\param extension A message containing configuration information for the
		translator. A standard set of possible fields is defined in
		TranslatorFormats.h.
	\param outType The identifier of the desired output format. An \a outType of
		0 is equivalent to the defualt format for the media type if the
		translator.
	\param destination Write interface for the destination of the data.
	\warning When creating a translator, be prepared for the information
		in \a format to be inaccurate or wrong.

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

	\since BeOS R3
*/

//! @}

/*!
	\name Configuration methods
*/

//! @{

/*!
	\fn virtual status_t BTranslator::MakeConfigurationView(BMessage*\
		extension, BView** _view, BRect* _extent)
	\brief 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, \c B_ERROR will be returned.

	\param extension A message containing configuration information for the
		translator. A standard set of possible fields is defined in
		TranslatorFormats.h.
	\param _view Where a pointer to the newly created configuration view will
		be stored.
	\param _extent Where the size of the newly created configuration view will
		be stored.
	\retval B_OK Everything went well.
	\retval B_ERROR An error occurred or the method was not overriden by the
		translator.
	\retval B_BAD_VALUE \a _view or \a _extent were \c NULL or \a extension
		was \c NULL or contained bad data.

	\since BeOS R3
*/

/*!
	\fn virtual status_t BTranslator::GetConfigurationMessage(BMessage*\
		extension)
	\brief 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, \c B_ERROR
	will be returned.

	\param extension The BMessage that is populated.

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

	\since BeOS R3
*/

//! @}