1/* 2 * Copyright 2014-2015 Markus Himmel. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Markus Himmel, markus@himmel-villmar.de 7 * 8 * Corresponds to: 9 * headers/os/translation/Translator.h hrev48573 10 * src/kits/translation/Translator.cpp hrev48573 11 */ 12 13/*! 14 \file Translator.h 15 \ingroup translation 16 \ingroup libtranslation 17 \brief BTranslator class definition. 18*/ 19 20/*! 21 \file TranslationDefs.h 22 \ingroup translation 23 \ingroup libtranslation 24 \brief Defines structures and preprocessor macros that are used by the 25 translation kit. 26*/ 27 28/*! 29 \file TranslatorFormats.h 30 \ingroup translation 31 \ingroup libtranslation 32 \brief Defines identifiers and structures for data formats and configuration 33 messages. 34*/ 35 36/*! 37 \class BTranslator 38 \ingroup translation 39 \ingroup libtranslation 40 \brief Abstract class that defines the necessary functionality of a 41 translator. 42 43 BTranslator is the core class of the translation kit. 44 Every translator defines input and output data types it can work with. A 45 BTranslator uses BPositionIO as an abstraction for the data it operates on. 46 It is able to 47 decide wether incoming data is of any of its known input types and, upon 48 successful identification, translate it to any of its output formats. It 49 may also provide a config view that appears in the DataTranslations 50 preference app. 51 52 Usually, a translator is very specific. It only offers translations 53 between the format it was created for and the basic format for that media 54 type. As an example, the translator for GIF images only translates between 55 GIF images and bitmaps, the baseline format for images. 56 57 The function \c make_nth_translator enables add-ons to expose translators. 58 Communication between applications and BTranslators is carried 59 out by the BTranslatorRoster class. 60 61 \note Another option to create a translator is using a BFuncTranslator. 62 63 \remark In most cases it is easier to derive from BaseTranslator instead 64 of BTranslator. BaseTranslator provides a lot of functionality that is 65 common for most translators as well as a unified method to save settings 66 and routines for handling bitmaps. 67 68 \since BeOS R3 69*/ 70 71/*! 72 \name Constructor and reference counting 73*/ 74 75//! @{ 76 77/*! 78 \fn BTranslator::BTranslator() 79 \brief Creates a new BTranslator and sets its reference count to 1. 80 81 \since BeOS R3 82*/ 83 84/*! 85 \fn BTranslator* BTranslator::Acquire() 86 \brief Increments the reference count by 1 and returns a pointer to 87 itself. 88 89 \returns \c this. 90 91 \since BeOS R3 92*/ 93 94/*! 95 \fn BTranslator* BTranslator::Release() 96 \brief Decrements the reference count by 1. If the reference count is 97 decreased to zero, the object is deleted. 98 99 \returns \c this if the object was not destroyed, \c NULL if it was. 100 101 \since BeOS R3 102*/ 103 104/*! 105 \fn int32 BTranslator::ReferenceCount() 106 \brief Gets the current reference count. 107 108 \returns The current reference count. 109 110 \since BeOS R3 111*/ 112 113//! @} 114 115/*! 116 \name Accessors 117*/ 118 119//! @{ 120 121/*! 122 \fn virtual const char* BTranslator::TranslatorName() const = 0 123 \brief Pure virtual. Returns the name of the translator. 124 125 Amongst other uses, the name is used to populate Save as-dropdowns and for 126 the preference window. 127 128 \returns The name of the translator. 129 130 \since BeOS R3 131*/ 132 133/*! 134 \fn virtual const char* BTranslator::TranslatorInfo() const = 0 135 \brief Pure virtual. Returns a brief description of the translator. 136 137 \returns A brief description of the translator. 138 139 \since BeOS R3 140*/ 141 142/*! 143 \fn virtual int32 BTranslator::TranslatorVersion() const = 0 144 \brief Pure virtual. Returns the version of the translator. 145 146 The correct way to format the version is using the 147 \c B_TRANSLATION_MAKE_VERSION macro from TranslationDefs.h. 148 149 \returns The version of the translator. 150 151 \since BeOS R3 152*/ 153 154/*! 155 \fn virtual const translation_format*\ 156 BTranslator::InputFormats(int32* _count) const = 0 157 \brief Pure virtual. Returns an array containing information about all 158 input formats the translator can handle. 159 160 \param _count Where the number of input formats that are returned will be 161 written. 162 163 \returns A pointer to the first element of the array of input formats. 164 165 \since BeOS R3 166*/ 167 168/*! 169 \fn virtual const translation_format*\ 170 BTranslator::OutputFormats(int32* _count) const = 0 171 \brief Pure virtual. Returns an array containing information about all 172 output formats the translator can produce. 173 174 \param _count Where the number of output formats that are returned will be 175 written. 176 177 \returns A pointer to the first element of the array of output formats. 178 179 \since BeOS R3 180*/ 181 182//! @} 183 184/*! 185 \name Core methods 186*/ 187 188//! @{ 189 190/*! 191 \fn virtual status_t BTranslator::Identify(BPositionIO* source, const\ 192 translation_format* format, BMessage* extension, translator_info* info,\ 193 uint32 outType) = 0; 194 \brief Pure virtual. Analyzes \a source and decides whether this translator 195 can work with the provided format. 196 197 The translator examines the data in source and tries to identify its format 198 (for instance by checking for magic numbers). It may use the hints provided 199 by \a format. If it is successful, and it is able to translate the data at 200 hand to \a outType, it populates \a info with information about the input 201 format and returns \c B_OK. If it is unable to identify the data or cannot 202 translate it to \a outType, it returns \c B_NO_TRANSLATOR. 203 204 \param source Read and seek interface to the input data. 205 \param format Hints about the incoming data. 206 \param extension A message containing configuration information for the 207 translator. A standard set of possible fields is defined in 208 TranslatorFormats.h. 209 \param info Where the translator will write information about the determined 210 input format in case identification is successful. 211 \param outType If \a outType is non-zero, identification will only be 212 successful if the translator can transform the data in source to the 213 format denoted by \a outType. 214 \warning When creating a translator, be prepared for the information 215 in \a format to be inaccurate or wrong. 216 217 \retval B_OK The translator has identified the data in \a source, has 218 verified its ability to translate it to \a outType and has 219 written information describing it to \a info. 220 \retval B_NO_TRANSLATOR The translator does not know how to handle the 221 data in \a source or cannot translate it to \a outType. 222 \retval B_BAD_VALUE \a extension was \c NULL or contained bad data. 223 \retval B_ERROR An error occurred. 224 225 \since BeOS R3 226*/ 227 228/*! 229 \fn virtual status_t BTranslator::Translate(BPositionIO* source, const\ 230 translator_info* info, BMessage* extension, uint32 outType,\ 231 BPositionIO* destination) = 0 232 \brief Pure virtual. Reads the provided data and tries to translate it 233 to a given format. 234 235 The translator attempts to translate the data in \a source, which may or may 236 not have the format represented by \a info, to \a outType and then write 237 the result to destination. Upon success, it returns \c B_OK. 238 239 \param source Read and seek interface to the input data. 240 \param info Hints about the incoming data. 241 \param extension A message containing configuration information for the 242 translator. A standard set of possible fields is defined in 243 TranslatorFormats.h. 244 \param outType The identifier of the desired output format. An \a outType of 245 0 is equivalent to the defualt format for the media type if the 246 translator. 247 \param destination Write interface for the destination of the data. 248 \warning When creating a translator, be prepared for the information 249 in \a format to be inaccurate or wrong. 250 251 \retval B_OK The translated data was successfully written to destination. 252 \retval B_ERROR An error occurred during memory allocation or the 253 conversion itself. 254 \retval B_BAD_VALUE \a extension was \c NULL or contained bad data. 255 \retval B_NO_TRANSLATOR The translator cannot handle the input. 256 257 \since BeOS R3 258*/ 259 260//! @} 261 262/*! 263 \name Configuration methods 264*/ 265 266//! @{ 267 268/*! 269 \fn virtual status_t BTranslator::MakeConfigurationView(BMessage*\ 270 extension, BView** _view, BRect* _extent) 271 \brief Virtual. Creates a BView that contains information and configuration 272 options for the translator. 273 274 This method is optional. If the translator chose not to implement 275 it, \c B_ERROR will be returned. 276 277 \param extension A message containing configuration information for the 278 translator. A standard set of possible fields is defined in 279 TranslatorFormats.h. 280 \param _view Where a pointer to the newly created configuration view will 281 be stored. 282 \param _extent Where the size of the newly created configuration view will 283 be stored. 284 \retval B_OK Everything went well. 285 \retval B_ERROR An error occurred or the method was not overriden by the 286 translator. 287 \retval B_BAD_VALUE \a _view or \a _extent were \c NULL or \a extension 288 was \c NULL or contained bad data. 289 290 \since BeOS R3 291*/ 292 293/*! 294 \fn virtual status_t BTranslator::GetConfigurationMessage(BMessage*\ 295 extension) 296 \brief Populates a BMessage with the settings of the translator. 297 298 A standard set of possible fields is defined in TranslatorFormats.h. This 299 method is optional. If the translator chose not to implement it, \c B_ERROR 300 will be returned. 301 302 \param extension The BMessage that is populated. 303 304 \retval B_OK Everything went well. 305 \retval B_ERROR An error occurred or the method was not overriden by the 306 translator. 307 \retval B_BAD_VALUE \a extension was \c NULL. 308 309 \since BeOS R3 310*/ 311 312//! @} 313