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/TranslatorRoster.h hrev48588 10 * src/kits/translation/TranslatorRoster.cpp hrev48588 11 */ 12 13/*! 14 \file TranslatorRoster.h 15 \ingroup translation 16 \ingroup libtranslation 17 \brief BTranslatorRoster class definition 18*/ 19 20/*! 21 \class BTranslatorRoster 22 \ingroup translation 23 \ingroup libtranslation 24 \brief Class that serves as an interface between applications and 25 translators. 26 27 BTranslatorRoster gives applications access to the translation kit. 28 Applications can request translations and BTranslatorRoster will 29 automatically search for a matching translator and have it perfrom the 30 translation. 31 32 \warning BTranslatorRoster does not perform chaining of any sort. Only 33 translations that can be made by invoking a single translator are 34 supported. 35 36 \note BTranslationUtils provides some helper methods that perform the 37 interaction with BTranslatorRoster for you. 38 39 BTranslationRoster acts as a container. While in most cases the default 40 roster is used, it is possible to create a roster that interacts with a 41 custom set of translators. 42*/ 43 44/*! 45 \name Constructors and Destructor 46*/ 47 48//! @{ 49 50/*! 51 \fn BTranslatorRoster::BTranslatorRoster() 52 \brief Constructs an empty BTranslatorRoster. 53 54 \warning Only call the contructor if you want to use a custom collection of 55 translators. Use Default() if you don't. 56*/ 57 58/*! 59 \fn BTranslatorRoster::BTranslatorRoster(BMessage* model); 60 \brief Constructs a BTranslatorRoster and fills it. 61 62 \param model A message that contains information about a 63 BTranslatorRoster. 64 65 After initialization, \a model is searched for strings with the name 66 \c "be:translator_path". The translators that are located at each path 67 are added to the roster. If multiple paths point to translators with the 68 same name, the translator at the path with the lowest index within the 69 message will be kept. 70 71 \warning Use Instantiate() instead of this constructor if \a model was 72 created using Archive(). 73*/ 74 75/*! 76 \fn BTranslatorRoster::~BTranslatorRoster(); 77 \brief Deletes this BTranslatorRoster. 78 79 If the BTranslatorRoster that is deleted is the default roster, a new 80 default roster will be created when BTranslatorRoster::Default() is called 81 for the next time. 82 83 Release() is called on all translators in the roster. 84*/ 85 86/*! 87 \fn static BTranslatorRoster* BTranslatorRoster::Default(); 88 \brief Gets the default BTranslatorRoster. 89 90 There is only one default translator. It is created when it is first 91 requested. It is poplated according to the following rules: 92 93 If the environment variable \c TRANSLATORS is set, it will be populated 94 with all translators that are present in the directories denoted by 95 \c TRANSLATORS. The paths are separated by a colon (<tt>:</tt>). If 96 multiple paths contain a translator with the same name, the translator 97 that is located in the path that appears earliest in \c TRANSLATORS will 98 be kept. 99 100 If \c TRANSLATORS is unset, the user non-packaged add-ons directory, the 101 user add-ons directory, the system non-packaged add-ons directory and the 102 system add-ons directory will be used. If those directories do not contain 103 a subdirectory \c Translators, it will be created. The subdirectories are 104 then added in the above order. If multiple directories contain a translator 105 with the same name, the translator that is located in the path that appears 106 earliest in the above list will be kept. 107*/ 108 109//! @} 110 111/*! 112 \name Archiving 113*/ 114 115//! @{ 116 117/*! 118 \fn virtual status_t BTranslatorRoster::Archive(BMessage* into, bool deep\ 119 = true) const; 120 \brief Archive this BTranslatorRoster into a BMessage. 121 122 \param into Where the BTranslatorRoster will be stored. 123 \param deep Unused. 124 125 \retval B_OK The operation was successful. 126 \retval B_BAD_VALUE \a into was NULL. 127 \retval B_ERROR The operation failed. 128*/ 129 130/*! 131 \fn static BArchivable* BTranslatorRoster::Instantiate(BMessage* from); 132 \brief Creates a new BTranslatorRoster from a message. 133 134 \param from The message that contains information about a 135 BTranslatorRoster. 136 137 \returns \c NULL if \a from was \c NULL, contained invalid archive data or 138 archive data of a class that is not BTranslatorRoster. A pointer to a 139 new BTranslatorRoster containing the information from \a from 140 otherwise. 141*/ 142 143//! @} 144 145/*! 146 \name Roster Management 147*/ 148 149//! @{ 150 151/*! 152 \fn status_t BTranslatorRoster::AddTranslators(const char* loadPath =\ 153 NULL); 154 \brief Adds translators from a directory to the roster. 155 156 \param loadPath A colon-separated list of directories to search for 157 translators in. 158 159 The following method is used to determine which translators to add: 160 161 If \a loadPath is not \c NULL, the roster will be populated with all 162 translators that are present in the directores denoted by \a loadPath. The 163 paths are separated by a colon (<tt>:</tt>). If multiple paths contain a 164 translator with the same name, the translator that is located in the path 165 that appears earliest in \a loadPath will be kept. 166 167 If \a loadPath is \c NULL and the environment variable \c TRANSLATORS is 168 set, it will be populated with all translators that are present in the 169 directories denoted by \c TRANSLATORS. The paths are separated by a colon 170 (<tt>:</tt>). If multiple paths contain a translator with the same name, 171 the translator that is located in the path that appears earliest in 172 \c TRANSLATORS will be kept. 173 174 If \a loadPath is \c NULL and \c TRANSLATORS is unset, the user 175 non-packaged add-ons directory, the user add-ons directory, the system 176 non-packaged add-ons directory and the system add-ons directory will be 177 used. If those directories do not contain a subdirectory \c Translators, it 178 will be created. The subdirectories are then added in the above order. If 179 multiple directories contain a translator with the same name, the 180 translator that is located in the path that appears earliest in the above 181 list will be kept. 182 183 \returns \c B_OK if everything went well, an error code specific to the 184 operation that failed otherwise. 185*/ 186 187/*! 188 \fn status_t BTranslatorRoster::AddTranslator(BTranslator* translator); 189 \brief Adds a single BTranslator to the roster. 190 191 \param translator The translator that should be added. 192 193 \remark AddTranslator() calls Acquire() on the translator, so it is safe 194 to release it if you had acquired it before. 195 196 \retval B_OK The translator was successfully added to the roster. 197 \retval B_NO_MEMORY There was no memory to enlarge the roster. 198 \retval B_BAD_VALUE \a translator was \c NULL. 199*/ 200 201//! @} 202 203/*! 204 \name Translator Access 205*/ 206 207//! @{ 208 209/*! 210 \fn virtual status_t BTranslatorRoster::GetTranslators(BPositionIO*\ 211 source, BMessage* ioExtension, translator_info** _info, int32*\ 212 _numInfo, uint32 hintType = 0, const char* hintMIME = NULL, uint32\ 213 wantType = 0); 214 \brief Collects information about all translators that are able to perform 215 a certain conversion in an array. 216 217 \param source Read and seek interface to the data to be examinded. 218 \param ioExtension A message containing configuration information for the 219 translators. 220 \param _info Where the resulting array will be stored. 221 \param _numInfo Where the number of elements in the resulting array will 222 be stored. 223 \param hintType A hint about the data format in \a source. \c 0 represents 224 an unknown type. 225 \param hintMIME A hint about the MIME type of \a source. \c NULL represents 226 an unknown type. 227 \param wantType The format that \a source needs to be translated into. \c 0 228 permits any output type. 229 230 If this function returns \c B_OK the caller has to call \c delete[] when 231 they are done using \a _info. 232 233 \retval B_OK \a _info and \a _numInfo were successfully populated. 234 \retval B_NO_TRANSLATOR No suitable translator was found. 235 \retval B_BAD_VALUE \a source, \a _info or \a _numInfo was \c NULL. 236 \retval B_IO_ERROR There was an error interacting with \a source. 237 \retval B_NO_MEMORY Could not allocate enough memory for the array. 238*/ 239 240/*! 241 \fn virtual status_t BTranslatorRoster::GetAllTranslators(translator_id**\ 242 _list, int32* _count); 243 \brief Collects the IDs of all translators in the roster in an array. 244 245 \param _list Where the resulting array will be stored. 246 \param _count Where the number of elements in the resulting array will be 247 stored. 248 249 If this function returns \c B_OK the caller has to call \c delete[] when 250 they are done using \a _info. 251 252 \retval B_OK \a _list and \a _count were populated successfully. 253 \retval B_NO_MEMORY Could not allocate the memory for the array. 254*/ 255 256/*! 257 \fn virtual status_t BTranslatorRoster::GetTranslatorInfo(translator_id\ 258 translatorID, const char** _name, const char** _info, int32* _version); 259 \brief Looks up general information of the translator with a given ID. 260 261 \param translatorID The ID of the translator whose information is 262 requested. 263 \param _name Where the name of the translator will be stored. 264 \param _info Where the description of the translator will be stored. 265 \param _version Where the version of the translator will be stored. 266 267 Do not free any returned data. If any of \a _name, \a _info and \a _version 268 are \c NULL, the non-null pointers will still be written to. 269 270 \retval B_OK All non-null pointers were written to successfully. 271 \retval B_BAD_VALUE All three pointers were \c NULL. 272 \retval B_NO_TRANSLATOR The roster does not contain any translator with the 273 ID \a translatorID. 274*/ 275 276/*! 277 \fn virtual status_t BTranslatorRoster::GetInputFormats(translator_id\ 278 translatorID, const translation_format** _formats, int32* _numFormats); 279 \brief Looks up the input formats of the translator with a given ID. 280 281 \param translatorID The ID of the translator whose input formats are 282 requested. 283 \param _formats Where the array of input formats will be stored. 284 \param _numFormats Where the number of elements in the array of input 285 formats will be stored. 286 287 Do not free any of the returned data. 288 289 \retval B_OK \a _formats and \a _numFormats were successfully set. 290 \retval B_BAD_VALUE \a _formats or \a _numFormats was \c NULL. 291 \retval B_NO_TRANSLATOR The roster does not contain any translator with the 292 ID \a translatorID. 293*/ 294 295/*! 296 \fn virtual status_t BTranslatorRoster::GetOutputFormats(translator_id\ 297 translatorID, const translation_format** _formats, int32* _numFormats); 298 \brief Looks up the output formats of the translator with a given ID. 299 300 \param translatorID The ID of the translator whose output formats are 301 requested. 302 \param _formats Where the array of output formats will be stored. 303 \param _numFormats Where the number of elements in the array of output 304 formats will be stored. 305 306 Do not free any of the returned data. 307 308 \retval B_OK \a _formats and \a _numFormats were successfully set. 309 \retval B_BAD_VALUE \a _formats or \a _numFormats was \c NULL. 310 \retval B_NO_TRANSLATOR The roster does not contain any translator with the 311 ID \a translatorID. 312*/ 313 314/*! 315 \fn virtual status_t BTranslatorRoster::MakeConfigurationView(\ 316 translator_id translatorID, BMessage* ioExtension, BView** _view,\ 317 BRect* _extent); 318 \brief Creates the configuration view of a specified translator from the 319 roster. 320 321 \param translatorID The ID of the translator whose configuration view 322 should be created. 323 \param ioExtension A message containing configuration information for the 324 translator. 325 \param _view Where a pointer to the newly created configuration view will 326 be stored. 327 \param _extent Where the size of of the newly created configuration view 328 will be stored. 329 330 \retval B_OK Everything went well. 331 \retval B_BAD_VALUE \a _view or \a _extent were \c NULL or \a ioExtension 332 was \c NULL or contained bad data. 333 \retval B_NO_TRANSLATOR The roster does not contain any translator with the 334 ID \a translatorID. 335 \retval B_ERROR An error occurred or the translator chose not to supply 336 a configuration view. 337*/ 338 339/*! 340 \fn virtual status_t BTranslatorRoster::GetConfigurationMessage(\ 341 translator_id translatorID, BMessage* ioExtension) 342 \brief Populates a BMessage with the settings of the specified translator. 343 344 \param translatorID The ID of the translator whose settings \a ioExtension 345 should be populated with. 346 \param ioExtension The message that should be populated. 347 348 \retval B_OK \a ioExtension was populated successfully. 349 \retval B_NO_TRANSLATOR The roster does not contain any translator with the 350 ID \a translatorID. 351 \retval B_BAD_VALUE \a ioExtension was \c NULL. 352 \retval B_ERROR An error occurred or the translator chose not to provide 353 this functionality. 354*/ 355 356/*! 357 \fn status_t BTranslatorRoster::GetRefFor(translator_id translatorID,\ 358 entry_ref* ref); 359 \brief Returns the entry_ref of the specified translator. 360 361 \param translatorID The ID of the translator whose entry_ref is to be 362 found. 363 \param ref Where the entry_ref will be written. 364 365 \retval B_OK Everything went well. 366 \retval B_BAD_VALUE \a ref was \c NULL. 367 \retval B_NO_TRANSLATOR The roster does not contain any translator with the 368 ID \a translatorID. 369 \retval B_ERROR An error occurred. 370*/ 371 372//! @} 373 374/*! 375 \name Core Methods 376*/ 377 378//! @{ 379 380/*! 381 \fn virtual status_t BTranslatorRoster::Identify(BPositionIO* source,\ 382 BMessage* ioExtension, translator_info* _info, uint32 hintType = 0,\ 383 const char* hintMIME = NULL, uint32 wantType = 0); 384 \brief Determines the best translator in the roster to perform a certain 385 conversion. 386 387 \param source Read and seek interface to the data to be examined. 388 \param ioExtension A message containing configuration infortmation for the 389 translators. 390 \param _info Where information about the best translator will be written. 391 \param hintType A hint about the data format in \a source. \c 0 represents 392 an unknown type. 393 \param hintMIME A hint about the MIME type of \a source. \c NULL represents 394 an unknown type. 395 \param wantType The format that \a source needs to be translated into. \c 0 396 permits any output type. 397 398 To determine the best translator, for all translators that report that 399 they are able to perform the translation, the values they return for 400 quality and capability are multiplied. The translator with the highest 401 value gets returned. Note that quality and capability for the output 402 format are not taken into consideration. 403 404 \retval B_OK Identification was successful. Information about the chosen 405 translator was written to \a _info. 406 \retval B_NO_TRANSLATOR No suitable translator was found. 407 \retval B_BAD_VALUE \a source or \a _info was \c NULL. 408 \retval B_IO_ERROR There was an error interacting with \a source. 409*/ 410 411/*! 412 \fn virtual status_t BTranslatorRoster::Translate(BPositionIO* source,\ 413 const translator_info* info, BMessage* ioExtension, BPositionIO*\ 414 destination, uint32 wantOutType, uint32 hintType = 0, const char*\ 415 hintMIME = NULL); 416 \brief Finds and invokes the best translator for a conversion. 417 418 \param source Read and seek interface to the input data. 419 \param info Information about wich translator should be used. If 420 \a info is \c NULL, Identify() will be used to find a suitable 421 translator. 422 \param ioExtension A message containing configuration information for the 423 translator. 424 \param destination Write interface to the output location. 425 \param wantOutType The desired output format. If this is \c 0, any type 426 is permitted. 427 \param hintType A hint about the type of the data in \a source. 428 \param hintMIME A hint about the MIME type of the data in \a source. 429 430 \retval B_OK The translated data was successfully written to 431 \a destination. 432 \retval B_NO_TRANSLATOR \a info was non-null but did not match to any 433 translator in the roster. 434 \retval B_NO_TRANSLATOR \a info was \c NULL and no suitable translator was 435 found. 436 \retval B_ERROR An error occurred. 437 \retval B_BAD_VALUE \a source or \a destination was \c NULL or 438 \a ioExtension was \c NULL or contained bad data. 439 \retval B_IO_ERROR An error occurred accessing \a source or \a destination. 440*/ 441 442/*! 443 \fn virtual status_t BTranslatorRoster::Translate(translator_id\ 444 translatorID, BPositionIO* source, BMessage* ioExtension, BPositionIO*\ 445 destination, uint32 wantOutType); 446 \brief Uses a specified translator from the roster to perform a conversion. 447 448 \param translatorID The ID of the translator that should be used. 449 \param source Read and seek interface to the input data. 450 \param ioExtension A message containing configuration information for the 451 translator. 452 \param destination Write interface to the output location. 453 \param wantOutType The desired output format. If this is \c 0, any type is 454 permitted. 455 456 \retval B_OK The translated data was successfully written to 457 \a destination. 458 \retval B_NO_TRANSLATOR The specified translator cannot handle the data in 459 \a source. 460 \retval B_ERROR An error occurred. 461 \retval B_BAD_VALUE \a source or \a destination was \c NULL or 462 \a ioExtension was \c NULL or contained bad data. 463 \retval B_IO_ERROR An error occurred accessing \a source or \a destination. 464*/ 465 466//! @} 467 468/*! 469 \name Miscellaneous 470*/ 471 472//! @{ 473 474/*! 475 \fn bool BTranslatorRoster::IsTranslator(entry_ref* ref); 476 \brief Determines whether the specified add-on contains at least one 477 translator. 478 479 \param ref The entry_ref to be tested. 480 481 \retval true The add-on exposes translators. 482 \retval false The add-on exposes no translators or an error occurred. 483*/ 484 485//! @} 486 487/*! 488 \name Notifications 489*/ 490 491//! @{ 492 493/*! 494 \fn status_t BTranslatorRoster::StartWatching(BMessenger target); 495 \brief Register a messenger to be notified when the roster changes. 496 497 \param target The BMessenger to be registered. 498 499 Whenever a translator is added to or removed from the roster, all 500 messengers that were registered through this method are sent a message. 501 \c message->what will be \c B_TRANSLATOR_ADDED or \c B_TRANSLATOR_REMOVED 502 (as defined in AppDefs.h) respectively. 503 504 \retval B_OK \a target was successfully registered. 505 \retval B_NO_MEMORY Unable to allocate more memory for the list of targets. 506*/ 507 508/*! 509 \fn status_t BTranslatorRoster::StopWatching(BMessenger target); 510 \brief Unregister a messenger from the notification list. 511 512 \param target The BMessenger to be removed. 513 514 \retval B_OK \a target was successfully unsubscribed. 515 \retval B_BAD_VALUE \a target could not be found on the notification list. 516 517 \sa StartWatching(BMessenger target) 518*/ 519 520//! @} 521