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