/* * Copyright 2014 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 libbe \brief BTranslator class definition. */ /*! \file TranslationDefs.h \ingroup translation \ingroup libbe \brief Defines structures and preprocessor macros that are used by the translation kit. */ /*! \file TranslatorFormats.h \ingroup translation \ingroup libbe \brief Defines identifiers and structures for data formats and configuration messages. */ /*! \class BTranslator \ingroup translation \ingroup libbe \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 configureation 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 */ //! @}